I2C Master Functions

Use the I²C Master Interface functions to control and monitor the I²C Master module of a DLN-series adapter. The dln_i2c_master.h file declares the I²C Master Interface functions.

General port information:

DlnI2cMasterGetPortCount(): Retrieves the total number of I²C master ports available at your DLN-series adapter.
DlnI2cMasterEnable(): Assigns a port to the I²C Master module.
DlnI2cMasterDisable(): Releases a port from the I²C Master module.
DlnI2cMasterIsEnabled(): Retrieves whether a port is assigned to the I²C Master module.
DlnI2cMasterScanDevices(): Scans all slave addresses searching for connected I²C slave devices.

I²C Master module configuration functions:

DlnI2cMasterSetFrequency(): Configures frequency for the specified I²C master port.
DlnI2cMasterGetFrequency(): Retrieves frequency configuration for an I²C Master port.
DlnI2cMasterSetMaxReplyCount(): Configures the maximum reply count for an I²C master port.
DlnI2cMasterGetMaxReplyCount(): Retrieves the maximum reply count configuration.

Transmission functions:

DlnI2cMasterRead(): Receives data from the specified slave. Internal address can be specified.
DlnI2cMasterWrite(): Sends data to the specified slave. Internal address can be specified.
DlnI2cMasterTransfer(): Sends data to the specified slave, then reads data from the same slave (only DLN-1 and DLN-2 adapters support this function).

Rating:

DlnI2cMasterDisable() Function

The DlnI2cMasterDisable() function releases the specified port from the I²C Master module.

Syntax

C/C++

DLN_RESULT DlnI2cMasterDisable(
   HDLN handle,
   uint8_t port
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the I²C master port.

Return Value

DLN_RES_SUCCESS (0x00): The function deactivated the I²C master port successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cMasterDisable() function is defined in the dln_i2c_master.h file.

DlnI2cMasterEnable() Function

The DlnI2cMasterEnable() function assigns the specified port to the I²C Master module.

Syntax

C/C++

DLN_RESULT DlnI2cMasterEnable(
   HDLN handle,
   uint8_t port,
   uint16_t* conflict
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the I²C master port.
conflict: A pointer to an unsigned 16-bit integer that receives a number of the conflicted pin, if any.

A conflict arises if a pin is already assigned to another module of the DLN adapter and cannot be used by the I²C master module. To fix this, check which module uses the pin (call the DlnGetPinCfg()function), disconnect the pin from that module and call the DlnI2cMasterEnable() function once again. If there are any more conflicting pins, the next conflicted pin number will be returned.

Return Value

DLN_RES_SUCCESS (0x00): The function activated the I²C master port successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.
DLN_RES_PIN_IN_USE (0xA5): The port cannot be activated as the I²C master port because one or more pins of the port are assigned to another module. The conflict parameter contains the number of a conflicting pin.

Remarks

The DlnI2cMasterEnable() function is defined in the dln_i2c_master.h file.

DlnI2cMasterGetFrequency() Function

The DlnI2cMasterGetFrequency() function retrieves the current I²C bus clock frequency.

Syntax

C/C++

DLN_RESULT DlnI2cMasterGetFrequency(
   HDLN handle,
   uint8_t port,
   uint32_t* frequency
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the I2C master port.
frequency: A pointer to an unsigned 32-bit integer that receives the current I²C bus clock frequency in Hz.

Return Value

DLN_RES_SUCCESS (0x00): The function retrieved the current clock frequency value successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cMasterGetFrequency() function is defined in the dln_i2c_master.h file.

DlnI2cMasterGetMaxReplyCount() Function

The DlnI2cMasterGetMaxReplyCount() function retrieves maximum reply count for I²C master port.

This function can be used only for DLN-1 and DLN-2 adapters.

Syntax

C/C++

DLN_RESULT DlnI2cMasterGetMaxReplyCount(
    HDLN handle, 
    uint8_t port, 
    uint16_t *maxReplyCount
);

Parameters

handle: A handle to the DLN adapter.
port: A number of the I²C master port.
maxReplyCount: Pointer to the variable that receives the current maximum reply count value.

Return Value

DLN_RES_SUCCESS (0x00): The function set the maximum reply count successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cMasterGetMaxReplyCount() function is defined in the dln_i2c_master.h file.

DlnI2cMasterGetPortCount() Function

The DlnI2cMasterGetPortCount() function retrieves the total number of I²C master ports available at your DLN-series adapter.

Syntax

C/C++

DLN_RESULT DlnI2cMasterGetPortCount(
   HDLN handle,
   uint8_t* count
);

Parameters

handle: A handle to the DLN-series adapter.
count: A pointer to an unsigned 8-bit integer that receives the number of available I²C master ports.

Return Value

DLN_RES_SUCCESS (0x00): The function retrieved the number of available I²C master ports successfully.
DLN_RES_HARDWARE_NOT_FOUND (0x81): The handle parameter is invalid, or the corresponding DLN adapter was disconnected.

Remarks

The DlnI2cMasterGetPortCount() function is defined in the dln_i2c_master.h file.

DlnI2cMasterIsEnabled() Function

The DlnI2cMasterIsEnabled() function checks whether the specified I²C master port is active or not.

Syntax

C/C++

DLN_RESULT DlnI2cMasterIsEnabled(
   HDLN handle,
   uint8_t port,
   uint8_t* enabled
);

Parameters

handle

A handle to the DLN-series adapter.

port

A number of the I2C master port.

enabled

A pointer to an unsigned 8-bit integer that receives information whether the specified I²C master port is activated. There are two possible values:

DLN_I2C_MASTER_DISABLED (0) - The port is not configured as an I²C master.
DLN_I2C_MASTER_ENABLED (1) - The port is configured as an I²C master.

Return Value

DLN_RES_SUCCESS (0x00): The function retrieved the state of the I²C master port successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cMasterIsEnabled() function is defined in the dln_i2c_master.h file.

DlnI2cMasterRead() Function

The DlnI2cMasterRead() function reads data from the specified I²C slave device.

Syntax

C/C++

DLN_RESULT DlnI2cMasterRead(
   HDLN handle,
   uint8_t port,
   uint8_t slaveDeviceAddress,
   uint8_t memoryAddressLength,
   uint32_t memoryAddress,
   uint16_t bufferLength,
   uint8_t* buffer
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the I²C master port.
slaveDeviceAddress: A 7-bit number, assigned to each I²C slave device. For additional details refer to the I²C slave address section.
memoryAddressLength: An internal address length. If set to zero, no internal address is sent.
memoryAddress: An internal I²C slave device address. For details, read Using Internal Addresses.
bufferLength: The size of the message buffer (in the range from 1 to 256 bytes).
buffer: A pointer to an array of unsigned 8-bit integers that receives data from the I²C slave device during the function execution. The array must contain at least bufferLength elements.

Return Value

DLN_RES_SUCCESS (0x00): The function executed the I²C read operation successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.
DLN_RES_DISABLED (0xB7): The function cannot execute the I²C read operation because the specified I²C master port is not active. Use the DlnI2cMasterEnable()function to activate the I²C master port.

Remarks

The DlnI2cMasterRead() function is defined in the dln_i2c_master.h file.

DlnI2cMasterScanDevices() Function

The DlnI2cMasterScanDevices() function scans all the 127 slave addresses searching for connected I²C slave devices.

Syntax

C/C++

DLN_RESULT DlnI2cMasterScanDevices(
   HDLN handle,
   uint8_t port,
   uint8_t* addressCount,
   uint8_t* addressList
);

Parameters

handle: A handle to the DLN adapter.
port: A number of the I²C master port scan for I²C slave devices.
addressCount: A pointer to an unsigned 8-bit integer that receives the number of found I²C slave devices.
addressList: A pointer to an array of unsigned 8-bit integers that receives the addresses of found I²C slave devices. I²C address is 7-bit long, so the most significant bit of the received integers will always be equal to zero. Some vendors specify the 8-bit addresses in their documentation. If you need to convert a 8-bit I²C address to 7-bit address, take a look at I²C address article.

Return Value

DLN_RES_SUCCESS (0x00): The function scanned the I²C addresses and found all connected I²C slaves successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.
DLN_RES_BUSY (0xB6): The function cannot scan I²C addresses while the I²C master port is busy transferring.
DLN_RES_DISABLED (0xB7): The function cannot scan I²C addresses because the specified I²C master port is not active. Use the DlnI2cMasterEnable()function to activate the I²C master port.
DLN_RES_OPERATION_TIMEOUT: The function failed to scan all slave addresses.

Remarks

The DlnI2cMasterScanDevices() function is defined in the dln_i2c_master.h file.

DlnI2cMasterSetFrequency() Function

The DlnI2cMasterSetFrequency() function configures the clock frequency for the specified I²C port.

Syntax

C/C++

DLN_RESULT DlnI2cMasterSetFrequency(
   HDLN handle,
   uint8_t port,
   uint32_t frequency,
   uint32_t* actualFrequency
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the I²C master port.
frequency: I²C frequency value, specified in Hz. You may specify any value within the range, supported by your DLN adapter. This range can be retrieved using the respective function. If you enter an incompatible value, it will be approximated as the closest lower frequency value, supported by the adapter.
actualFrequency: A pointer to an unsigned 32-bit integer that receives the actual frequency applied by this function. The frequency is specified in Hz. If the frequency specified in frequency parameter is supported, the actual frequency will be equal to it. Otherwise, the closest lower value will be applied. If NULL is specified in this parameter, the actual frequency value will not be returned. You can still use the DlnI2cMasterGetFrequency() function to check the actual frequency.

Return Value

DLN_RES_SUCCESS (0x00): The function set the I²C master port clock frequency value successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.
DLN_RES_BUSY (0xB6): The function cannot change frequency while the I²C master port is busy transferring.
DLN_RES_VALUE_ROUNDED (0x21): The function approximated the frequency value to the closest supported value.

Remarks

The DlnI2cMasterSetFrequency() function is defined in the dln_i2c_master.h file.

DlnI2cMasterSetMaxReplyCount() Function

The DlnI2cMasterSetMaxReplyCount() function sets maximum reply count for I²C master port.

DLN-1 and DLN-2 adapters cannot send a single slave address and direction bit without data bytes. This is a firmware driver limitation. Therefore, an adapter cannot read a single byte at all possible addresses. Retrying every read/write operation 10 times is set by default in firmware I²C driver, but using the DlnI2cMasterSetMaxReplyCount() function you can modify this parameter.

This function can be used only for DLN-1 and DLN-2 adapters.

Syntax

C/C++

DLN_RESULT DlnI2cMasterSetMaxReplyCount(
    HDLN handle, 
    uint8_t port, 
    uint16_t maxReplyCount
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the I2C master port.
maxReplyCount: Maximum reply count value.

Return Value

DLN_RES_SUCCESS (0x00): The function set the maximum reply count successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.
DLN_RES_BUSY (0xB6): The function cannot change the maximum reply count while the I²C master port is busy transferring.
DLN_RES_INVALID_VALUE (0xE2): The provided value is zero or not valid.

Remarks

The DlnI2cMasterSetMaxReplyCount() function is defined in dln_i2c_master.h file.

DlnI2cMasterTransfer() Function

The DlnI2cMasterTransfer() function sends and receives data via the I²C bus. The data is sent and received as an array of 1-byte elements.

Syntax

C/C++

DLN_RESULT DlnI2cMasterTransfer(
    HDLN handle, 
    uint8_t port, 
    uint8_t slaveDeviceAddress, 
    uint16_t writeLength, 
    uint16_t readLength, 
    uint8_t *writeBuffer, 
    uint8_t *readBuffer
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the I²C master port.
slaveDeviceAddress: The I²C slave device address value.
writeLength: The length of data that should be written to the slave device.
readLength: The length of data that should be read from the slave device.
writeBuffer: A pointer to an array of unsigned 8-bit integers that receives data to be sent to the slave during the function execution.
readBuffer: A pointer to an array of unsigned 8-bit integers that receives data from the slave during the function execution.

Return Value

DLN_RES_SUCCESS (0x00): The function transmitted data via the I²C bus successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.
DLN_RES_DISABLED (0xB7): The function transmit data via the I²C bus because the specified I²C master port is not active. Use the DlnI2cMasterEnable()function to activate the I²C master port.
DLN_RES_INVALID_BUFFER_SIZE (0xAE): The specified buffer size is not valid.

Remarks

DLN-4 adapters do not support this function.

The DlnI2cMasterTransfer() function is defined in the dln_i2c_master.h file.

DlnI2cMasterWrite() Function

The DlnI2cMasterWrite() function sends data to the specified I²C slave device.

Syntax

C/C++

DLN_RESULT DlnI2cMasterWrite(
   HDLN handle,
   uint8_t port,
   uint8_t slaveDeviceAddress,
   uint8_t memoryAddressLength,
   uint32_t memoryAddress,
   uint16_t bufferLength,
   uint8_t* buffer
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the I2C master port to be used.
slaveDeviceAddress: A 7-bit number, uniquely assigned to each I²C slave device. See I2C address section for additional information.
memoryAddressLength: An internal address length. If set to zero, no internal address is sent.
memoryAddress: An internal I²C slave device address. For details, read Using Internal Addresses.
bufferLength: The size of the message buffer in bytes. This value must fall within a range from 1 to 256.
buffer: A pointer to an array of unsigned 8-bit integers that receives information to be sent to a slave during the function execution. The buffer size must not exceed 256 bytes.

Return Value

DLN_RES_SUCCESS (0x00): The function executed the I²C write operation successfully.
DLN_RES_INVALID_PORT_NUMBER (0xA8): The port number is not valid. Use the DlnI2cMasterGetPortCount() function to find the maximum possible port number.
DLN_RES_DISABLED (0xB7): The function cannot execute the I²C write operation because the specified I²C master port is not active. Use the DlnI2cMasterEnable()function to activate the I²C master port.

Remarks

The DlnI2cMasterWrite() function is defined in the dln_i2c_master.h file.