I2C Bus Interface (C/C++ API)

I2C (Inter-Integrated Circuit) is a multi-master, multi-slave, single-ended, serial bus invented by Philips Semiconductor (now NXP Semiconductors). It is typically used for attaching low-speed peripheral ICs to processors and microcontrollers.

I2C can be used to control a wide range of devices: analogue-to-digital and digital-to-analog converters (ADCs and DACs), LCD and OLED displays, keyboards, LED and motor drivers, memory chips and cards (EEPROM, RAM, FERAM, Flash), pressure and temperature sensors and other peripheral devices.

I2C bus specification describes four operating speed categories for bidirectional data transmission:

Standard-mode (Sm)

a bit rate up to 100 kbit/s

Fast-mode (Fm)

a bit rate up to 400 kbit/s

Fast-mode Plus (Fm+)

a bit rate up to 1 Mbit/s

High-speed mode (Hs)

a bit rate up to 3.4 Mbit/s

One more speed category, Ultra-fast mode (UFm), stands for unidirectional data transmission up to 5 Mbit/s.

DLN-series adapters can operate in Standard, Fast and Fast Plus modes.

Rating: 
Average: 1 (2 votes)

I2C Bus Protocol

I2C bus uses two lines – SDA (Serial Data line) and SCL (Serial Clock line). Every device connected to the I2C bus can operate as either I2C master (generates the clock and initiates communication with slaves) or I2C slave (responds when addressed by the master).

DLN-series adapters can operate as master devices (read I2C Master Interface). Some DLN adapters can also operate as slave devices (read I2C Slave Interface).

The I2C bus is a bidirectional bus, but this does not mean that the data is transmitted in both directions simultaneously. At every particular moment, either master or slave sends data over the I2C bus. The device that sends data to the bus is called Transmitter. The device that receives data from the bust is called Receiver. Most I2C devices can both transmit and receive data. However, some I2C devices are only able to receive data. DLN adapters are capable of transmitting and receiving data.

The I2C bus is a multi-master bus; that means that any number of master devices can be present. The DLN-series adapters support clock synchronization and arbitration to avoid conflicts with other master devices on the same I2C bus. Read Avoiding Conflicts in a Multi-master I2C Bus for details.

I2C Bus

The maximum number of slave devices is limited by the address space. Each slave device has a unique address. The I2C bus can use 7 or 10-bit addressing. The DLN-series adapters use 7-bit addressing.

Rating: 
Average: 5 (1 vote)

Data Transmission

Both SDA and SCL are bidirectional lines, connected to a positive supply voltage via a pull-up resistor.

I2C bus

All the devices connected to the I2C bus must have an open-drain (or open-collector) output stages – they can either pull the bus low or be in high-impedance. When there is no data transmission on the I2C bus, both lines are HIGH. In this case, we say that the I2C bus is free.

I2C master generates clock signal on the SCL line. One SCL pulse is generated for each data bit. The data on the SDA line must be stable during the HIGH period of the clock (while SCL line is high). The changes on the SDA line occur when the SCL line is LOW. The only exception from this rule are START, STOP and Repeated START Conditions described later.

I2C bit transmission

Rating: 
No votes yet

Byte Format and Acknowledge Bit

Every byte, sent over the I2C bus, is eight bits long. Data is transferred with the Most Significant Bit (MSB) first. An Acknowledge bit must follow each byte. The master generates all clock pulses, including the acknowledge clock pulse.

The Acknowledge bit allows:

  • The receiver to signal the transmitter that the byte was successfully received and another byte may be sent;

  • The receiver to signal the transmitter that it received enough data and the transmission should be terminated;

  • The slave to signal the master that the specified slave address is present on the bus and transmission can start (see Slave Address and Data Direction);

  • The slave to delay the transmission, while it prepares for another byte of data (see Clock Stretching for details).

After transmission of the last eighth bit of data, the transmitter releases the SCL line (during the low phase of clock). This gives an opportunity to receiver to acknowledge (or not acknowledge) the data.

If the receiver pulls the line LOW during the HIGH period of the ninth clock pulse, it acknowledges the byte (the Acknowledge (ACK) signal).

Acknowledge ACK signal

The Not Acknowledge (NACK) signal is defined when SDA remains HIGH during this clock pulse. The master then can generate either a STOP (P) condition to abort the transmission, or a repeated START (Sr) condition to start a new transmission.

Not Acknowledge NACK signal

The following conditions can lead to the Not Acknowledged (NACK) signal:

  1. There is no device to acknowledge the slave address – no slave with the specified address is connected to the I2C bus.

  2. The slave is unable to receive or transmit – it is busy performing another function.

  3. The slave does not support the specified data direction (read or write).

  4. The receiver gets data that it does not understand.

  5. The receiver cannot receive any more data bytes.

  6. A master-receiver must signal the end of the transmission to the slave-transmitter.

Rating: 
No votes yet

I2C Transaction

The data transmission includes the following steps:

  1. The master initiates communication by generating a START (S) Condition;

  2. The master sends the first byte that includes a Slave Address and Data Direction;

  3. The slave generates the acknowledgement (ACK) signal. If the master receives no acknowledgement signal, it generates the STOP (P) condition to terminate the transmission.

  4. The transmitter (master or slave) writes a byte of data to the bus and the receiver (slave or master) reads this byte of data from the bus.

  5. After each byte of data, the receiver sends the acknowledgement (ACK) signal and the transmission continues. If the receiver sends no acknowledgement signal, the transmitter stops writing data to the I2C bus.

  6. To terminate transmission, the master generates the STOP (P) Condition. To change transmission parameters, the master generates the Repeated START (Sr) Condition.

I2C transmission

Rating: 
Average: 5 (1 vote)

START, STOP and Repeated START Conditions

All transactions begin with a START (S) condition and finish with a STOP (P) condition.

START and STOP conditions

Rating: 
No votes yet

START (S) Condition

To generate a START condition, the master changes the SDA line from one to zero while the SCL line is HIGH (marked in red on the following diagram). The I2C bus is considered busy after the START condition. To prepare the bus for transmission of the first bit, the master outputs zero on the SCL line (marked in green).

START S condition

Rating: 
Average: 5 (1 vote)

STOP (P) Condition

To generate a STOP condition, the master changes the SDA line from zero to one while the SCL line is HIGH (marked in red). The I2C bus is considered free after the STOP condition. To prepare for the STOP condition, the master sets the SDA line to zero during the LOW phase of the SCL line (marked in green).

STOP P condition

Rating: 
No votes yet

Repeated START (Sr) Condition

Instead of the STOP condition, the master can generate a repeated START (Sr) condition. Like a START condition, to generate a repeated START condition, the master changes the SDA line from one to zero while the SCL line is HIGH (marked in red). In this case, the I2C bus remains busy. To prepare for the repeated START condition, the master sets the SDA line to one during the LOW phase of the SCL line (marked in green).

Repeated START Sr condition

The START (S) and repeated START (Sr) conditions are functionally identical. The repeated start conditions is used in the following situations:

  • To continue transmission with the same slave device in the opposite direction. After the repeated START condition, the master sends the same slave device address followed by another direction bit.

  • To start transmission to or from another slave device. After the repeated START condition, the master sends another slave address.

  • To provide a READ operation from internal address. See READ Operation for details.

DLN adapters use the repeated START condition to read from the internal address (the DlnI2cMasterRead() function) and to write to and then read from the same slave device (the DlnI2cMasterTransfer() function). If a DLN adapter needs to communicate with different slaves, it finishes one transmission (with the STOP condition) and starts another transmission.

Rating: 
Average: 5 (5 votes)

Slave Address and Data Direction

Every byte on the SDA line must be eight bits long. The first byte after START contains seven bits of the slave device address and one bit that defines the direction of the transmission.

Slave address and data direction

As any other data, the address is transmitted sequentially starting with the Most Significant Bit (MSB) and ending with the Least Significant Bit (LSB).

The direction bit has the following values:

  • 0 – Write: the master transmits data to the slave;

  • 1 – Read: the master receives data from the slave.

Rating: 
Average: 5 (1 vote)

Reserved I2C Slave Addresses

There are 16 reserved I2C addresses. The following table shows the purposes of these addresses:

I2C slave addressDirection bit (R/W)Description

0000 000

0

General call address

0000 000

1

START byte

0000 001

X

CBUS address

0000 010

X

Reserved for different bus format

0000 011

X

Reserved for future purposes

0000 1XX

X

Hs-mode master code

1111 1XX

1

Device ID

1111 0XX

X

10-bit slave addressing

The general call address is for addressing all devices connected to the I2C bus. If a device does not need the provided data, it can ignore this address (it does not issue the acknowledgement). If a device requires data from a general call address, it acknowledges this address and behaves as a slave-receiver. If one or more slaves acknowledge the general call address, the master does not know how many devices did it and does not see not-acknowledged slaves.

If you use a DLN-series adapter as I2C slave, you can configure it to support general call addressing or to ignore it.

Rating: 
Average: 5 (1 vote)

Using Internal Addresses

Some I2C slave devices have fixed internal address setting. The internal address is the slave’s internal register. Possible internal addresses depend on the slave device. Some very simple devices do not have any, but most do.

To communicate with a certain register, after the I2C master addressed the slave device and received acknowledgement, it sends the internal address inside the slave where it wants to transmit data to or from.

Both read and write operations can use an internal address. When an internal address is set, the same address is used in every READ and WRITE operations that follows the previous operation.

Rating: 
Average: 5 (1 vote)

WRITE Operation

To write to a slave device, the I2C master follows these steps:

  1. Sends the START (S) condition.

  2. Sends the I2C address of the slave device.

  3. Sends the WRITE (W) direction bit.

  4. Receives the acknowledgement (ACK) bit.

  5. Sends the internal address where it wants to write.

  6. Receives the acknowledgement (ACK) bit.

  7. Sends data bytes and receives the acknowledgement (ACK) bit after each byte.

  8. Sends the STOP (P) condition.

Write to internal address

To write data using internal address, call the DlnI2cMasterWrite() function. It requires the slave device address (the slaveDeviceAddress parameter), the length of the internal address (the memoryAddressLength parameter) and the internal address (the memoryAddress parameter).

Rating: 
Average: 4.5 (2 votes)

READ Operation

Before reading data from the slave device, the master tells the slave which of the internal addresses it wants to read. Therefore, a read operation starts by writing to the slave.

To read from a slave device, the I2C master follows these steps:

  1. Sends a START (S) condition.

  2. Sends the I2C address of the slave device.

  3. Sends the WRITE (W) direction bit.

  4. Receives the acknowledgement (ACK) bit.

  5. Sends the internal address where it wants to read from.

  6. Receives the acknowledgement (ACK) bit.

  7. Sends the repeated START (Sr) condition.

  8. Sends the READ (R) direction bit.

  9. Receives the acknowledgement (ACK) bit.

  10. Receives data bytes and sends acknowledgement (ACK) bits to continue reading or a not acknowledgement (NACK) bit to stop reading.

  11. Sends the STOP (P) condition.

Read from internal address

To read data using internal address, call the DlnI2cMasterRead() function. It requires the slave device address (the slaveDeviceAddress parameter), the length of the internal address (the memoryAddressLength parameter) and the internal address (the memoryAddress parameter).

Rating: 
Average: 5 (1 vote)

Avoiding Conflicts in a Multi-master I2C Bus

In a multi-master I2C bus, the collision when more than one master simultaneously initiate data transmission is possible. To avoid the chaos that may ensue from such an event, DLN adapters, like all I2C master devices, support clock synchronization and arbitration. These procedures allow only one master to control the bus; other masters cannot corrupt the winning message.

Clock synchronization allows to perform the level on the SCL line. Arbitration determines which master completes transmission. If a master loses arbitration, it turns off its SDA output driver and stops transmitting data.

Slaves are not involved in clock synchronization and arbitration procedures.

Rating: 
Average: 4.5 (2 votes)

Clock Synchronization

A DLN adapter and one or more I2C masters can begin transmitting on a free I2C bus at the same time. Each master generates its own clock on the SCL line. Therefore, there must be a method for deciding which master generates LOW and HIGH periods of the SCL line. Clock synchronization does it.

Once a DLN adapter or any other I2C master outputs LOW on its clock line, the SCL line goes LOW. When a master releases its clock line, the SCL line goes HIGH only if no other master has its clock line in LOW state. The master with the longest LOW period holds the SCL line in LOW state. Masters with shorter LOW periods stay in a HIGH wait-state during this time.

When all masters concerned have released their clock lines, the SCL line goes HIGH and all the masters start counting their HIGH periods. The first master that completes its HIGH period pulls the SCL line LOW again.

Therefore, the master with the longest clock LOW period determines a LOW period on the SCL line; the master with the shortest clock HIGH period determines a HIGH period on the SCL line.

The following figure shows clock synchronization for the DLN adapter and the Master2 device. The DLN adapter has a shorter HIGH period; it pulls the SCL line LOW. The Master2 device has a longer LOW period, only when it releases its clock line, both masters start counting HIGH period.

Clock synchronization

Rating: 
Average: 3 (2 votes)

Arbitration

Arbitration, like clock synchronization, is required only if more than one master is used in the system. A master may start transmission only if the bus is free. A DLN adapter and one or more other masters may generate a START condition within the minimum hold time, which results in a valid START condition on the bus. Arbitration is then required to determine which master will complete its transmission.

Arbitration proceeds bit by bit. During every bit, while SCL is HIGH, each master checks to see if the SDA level matches what it has sent. If at least one master outputs LOW, the SDA line will have the LOW level. If a master changes the state of the SDA line to HIGH, but the line stays in LOW, then this indicates that this master lost arbitration and it needs to back off.

The arbitration process may take many bits. More than one masters can even complete an entire transaction without error if their transmissions are identical.

A master that loses the arbitration can generate clock pulses until the end of the byte in which it loses the arbitration and can restart its transaction when the bus is free.

If a master can act as a slave and it loses arbitration during the addressing stage, it must switch immediately to its slave mode because the winning master may try to address it.

The following figure shows the arbitration procedure for the DLN adapter and the Master2 device. The moment when there is a difference between the DATA1 level and the actual level on the SDA line, the DLN adapter switches off the DATA1 output.

Arbitration

Rating: 
Average: 4.3 (3 votes)

Clock Stretching

In an I2C communication, a master device determines the clock speed. The I2C bus provides an explicit clock signal that relieves a master and a slave from synchronizing exactly to a predefined baud rate.However, some slave devices may receive or transmit bytes of data at a fast rate, but need more time to store a received byte or prepare another byte to be transmitted. Slaves can then hold the SCL line LOW to force the master into a wait-state until the slave is ready for the next byte transmission. This mechanism is called clock stretching. An I2C slave is allowed to hold the SCL line LOW if it needs to reduce the bus speed. The master on the other hand is required to read back the SCL signal after releasing it to the HIGH state and wait until the SCL line has actually gone HIGH. DLN-series adapters support clock stretching. Taking into consideration the impacts of clock stretching, the total speed of the I2C bus might be significantly decreased.

Rating: 
No votes yet

I2C Master Interface

All DLN-series adapters support I2C master interface. Some of them can have several independent I2C ports. To know the number of available I2C master ports, use the DlnI2cMasterGetPortCount() function.Before using the I2C bus for transmitting data, you need to configure the I2C master port and enable it (see Configuring the I2C Master Interface). To stop using the I2C master port, you can disable it by the DlnI2cMasterDisable() function.

Rating: 
No votes yet

Configuring the I2C Master Interface

To start using the I2C master port, you need to configure the I2C master interface:

  1. Configure the I2C frequency. This parameter influences the speed of data transmission. For details, read I2C Speed and Frequency.

  2. Configure the number of attempts to resend data if Not Acknowledgement is received. For details, read Reply Count.

  3. Enable the I2C master port. If the pins of the I2C port are not used by other modules, you can enable the I2C master port by the DlnI2cMasterEnable() function.

Rating: 
No votes yet

I2C Speed and Frequency

I2C bus specification describes four operating speed categories for bidirectional data transmission:

Standard-mode (Sm)

a bit rate up to 100 kbit/s

Fast-mode (Fm)

a bit rate up to 400 kbit/s

Fast-mode Plus (Fm+)

a bit rate up to 1 Mbit/s

High-speed mode (Hs)

a bit rate up to 3.4 Mbit/s

One more speed category, Ultra-fast mode (UFm), stands for unidirectional data transmission up to 5 Mbit/s.

Configuring the I2C master interface, you can specify the frequency value by calling the DlnI2cMasterSetFrequency() function.

The range of supported frequency values depends on the DLN adapter:

  • DLN-1 and DLN-2 adapters support frequency from 1kHz up to 4MHz.

  • DLN-4 adapters support frequency from 1.47kHz up to 1MHz.

The quality of I2C lines, the values of pull-up resistors and the number of slaves connected to the I2C bus may influence the working frequency of the I2C bus. Besides, the frequency reflects the speed of a single byte transmission, but not the speed of transmitting all data. It is a fact that the time of data processing can exceed significantly the time of data transmission. That is why data transmitted at high speed can have no effect on the speed of the I2C bus if delays between bytes are longer than the bytes themselves.

Rating: 
No votes yet

Reply Count

The I2C transmission expects an Acknowledge bit after every byte. This bit is sent by a slave and by a receiver:

  • A slave sends an Acknowledge bit after the slave address and direction bit to signal that the device with the specified address is present on the I2C bus;

  • A receiver sends an Acknowledge bit after a data byte to signal that the byte was successfully received and another byte may be sent.

The Acknowledge signal is LOW on the SDA line that remains stable during the HIGH period of the ninth pulse on the SCL line. If the SDA line remains HIGH during this clock pulse, this is defined as Not Acknowledge signal. In this case, the master has the following options:

  • Generate a STOP (P) condition to abort the transmission;

  • Generate a repeated START (Sr) condition to start a new transmission.

DLN-1 and DLN-2 adapters provide one more option for the I2C master:

  • Generate a STOP (P) condition followed by a START (S) condition to start the same transmission from the very beginning.

This option allows to repeat transmission if acknowledgement was not received. By default, transmissions can repeat 10 times. If all these times acknowledgement was not received, the transmission is supposed to fail. If acknowledgement was received, the transmission is successful.

Using the DlnI2cMasterSetMaxReplyCount() function, you can change the maximum number of attempts to transmit data. The DlnI2cMasterGetMaxReplyCount() function allows to check the currently specified number of attempts.

This option is available only for DLN-1 and DLN-2 adapters.
Rating: 
No votes yet

I2C Addresses

DLN-series adapters support only 7-bit addressing. To start transmission, the I2C master generates the START (S) condition followed by seven bits of a slave address and an eighth bit which is a data direction bit.

Some vendors provide 8-bit addresses for their devices. Actually, this is the 7-bit slave address and the direction bit. It is important to use only top 7 bits as the slave address and to discard the least significant bit of such address.

7-bit addressing allows 127 different addresses. Some addresses are reserved (See Slave Address and Data Direction), only 112 devices can actually be connected to the I2C bus. To scan all possible addresses and to find devices connected to the I2C bus, us the DlnI2cMasterScanDevices() function. It returns the number of connected devices and the list of their addresses.You can use these addresses for I2C transmission in one of the following functions:

DlnI2cMasterRead()

Receives data from the specified slave. Internal address can be specified (See READ Operation for details).

DlnI2cMasterWrite()

Sends data to the specified slave. Internal address can be specified (See WRITE Operation for details).

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: 
No votes yet

Simple I2C Master Module Example

The following example shows how to operate with I2C master module. You can find the complete example in the “..\Program Files\Diolan\DLN\examples\c_cpp\examples\simple” folder after DLN setup package installation.

C/C++
#include "..\..\..\common\dln_generic.h"
#include "..\..\..\common\dln_i2c_master.h"
#pragma comment(lib, "..\\..\\..\\bin\\dln.lib")


int _tmain(int argc, _TCHAR* argv[])
{
	// Open device
	HDLN device;
	DlnOpenUsbDevice(&device);

	// Set frequency
	uint32_t frequency;
	DlnI2cMasterSetFrequency(device, 0, 100000, &frequency);
	// Enable I2C master
	uint16_t conflict;
	DlnI2cMasterEnable(device, 0, &conflict);

	// Prepare output buffer
	uint8_t output[8], input[8];
	for (int i = 0; i < 8; i++) output[i] = i;
	// Write bytes 
	DlnI2cMasterWrite(device, 0, 0x50, 1, 0, 8, output);

	// Read bytes
	DlnI2cMasterRead(device, 0, 0x50, 1, 0, 8, input);
	// Print input data
	for (int i = 0; i < 8; i++) printf("%02x ", input[i]);

	// Disable I2C master
	DlnI2cMasterDisable(device, 0);
	// Close device
	DlnCloseHandle(device);
	return 0;
}

  • Line 1:#include "..\..\..\common\dln_generic.h"

    The dln_generic..h header file declares functions and data structures for the generic interface.

  • Line 2:#include "..\..\..\common\dln_i2c_master.h"

    The dln_i2c_master.h header file declares functions and data structures for the I2C master interface.

  • Line 3:#pragma comment(lib, "..\\..\\..\\bin\\dln.lib")

    Use dln.lib library while project linking.

  • Line 10:DlnOpenUsbDevice(&device);

    The function establishes the connection with the DLN adapter. This application uses the USB connectivity of the adapter. For additional options, refer to the Device Opening & Identification section.

  • Line 14:DlnI2cMasterSetFrequency(device, 0, 100000, &frequency);

    This function sets frequency on the I2C bus. It is set in Hertz. Any frequency value can be provided to the function, but only device compatible frequency will be set. You can read the actual frequency value by providing pointer to the unsigned 32-bit integer variable. You can read more about I2C bus speed and frequency by navigating to I2C Speed and Frequency section.

  • Line 17:DlnI2cMasterEnable(device, 0, &conflict);

    This function enables I2C master module.

  • Line 21:for (int i = 0; i < 8; i++) output[i] = i;

    Fill output array with the values from 0 to 8. It will be used as data buffer for sending it via I2C bus.

  • Line 23: DlnI2cMasterWrite(device, 0, 0x50, 1, 0, 8, output);

    This function sends provided data buffer via I2C bus to connected I2C slave device. To send data properly to slave device it is required to provide also slave device address and memory address. You can read more about I2C addressing at I2C Addresses.

  • Line 26: DlnI2cMasterRead(device, 0, 0x50, 1, 0, 8, &input);

    This function reads data from the I2C slave device. The parameters are almost similar to the data writing process.

  • Line 28: for (int i = 0; i < 8; i++) printf("%02x ", input[i]);

    Print to console data, which was read from the I2C slave device.

  • Line 31: DlnI2cMasterDisable(device, 0);

    Disable I2C master port.

  • Line 33: DlnCloseHandle(device);

    Closing handle to the previously opened DLN-series adapter.

Rating: 
No votes yet

I2C Master Functions

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

General port information:

DlnI2cMasterGetPortCount()

Retrieves the total number of I2C master ports available at your DLN-series adapter.

DlnI2cMasterEnable()

Assigns a port to the I2C Master module.

DlnI2cMasterDisable()

Releases a port from the I2C Master module.

DlnI2cMasterIsEnabled()

Retrieves whether a port is assigned to the I2C Master module.

DlnI2cMasterScanDevices()

Scans all slave addresses searching for connected I2C slave devices.

I2C Master module configuration functions:

DlnI2cMasterSetFrequency()

Configures frequency for the specified I2C master port.

DlnI2cMasterGetFrequency()

Retrieves frequency configuration for an I2C Master port.

DlnI2cMasterSetMaxReplyCount()

Configures the maximum reply count for an I2C 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: 
No votes yet

DlnI2cMasterDisable() Function

The DlnI2cMasterDisable() function releases the specified port from the I2C 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 I2C master port.

Return Value
DLN_RES_SUCCESS (0x00)

The function deactivated the I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C master ports.

Return Value
DLN_RES_SUCCESS (0x00)

The function retrieved the number of available I2C 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 I2C 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 I2C master port is activated. There are two possible values:

  • DLN_I2C_MASTER_DISABLED (0) - The port is not configured as an I2C master.

  • DLN_I2C_MASTER_ENABLED (1) - The port is configured as an I2C master.

Return Value
DLN_RES_SUCCESS (0x00)

The function retrieved the state of the I2C 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 I2C 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 I2C master port.

slaveDeviceAddress

A 7-bit number, assigned to each I2C slave device. For additional details refer to the I2C slave address section.

memoryAddressLength

An internal address length. If set to zero, no internal address is sent.

memoryAddress

An internal I2C 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 I2C slave device during the function execution. The array must contain at least bufferLength elements.

Return Value
DLN_RES_SUCCESS (0x00)

The function executed the I2C 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 I2C read operation because the specified I2C master port is not active. Use the DlnI2cMasterEnable()function to activate the I2C 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 I2C 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 I2C master port scan for I2C slave devices.

addressCount

A pointer to an unsigned 8-bit integer that receives the number of found I2C slave devices.

addressList

A pointer to an array of unsigned 8-bit integers that receives the addresses of found I2C slave devices. I2C 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 I2C address to 7-bit address, take a look at I2C address article.

Return Value
DLN_RES_SUCCESS (0x00)

The function scanned the I2C addresses and found all connected I2C 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 I2C addresses while the I2C master port is busy transferring.

DLN_RES_DISABLED (0xB7)

The function cannot scan I2C addresses because the specified I2C master port is not active. Use the DlnI2cMasterEnable()function to activate the I2C 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 I2C 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 I2C master port.

frequency

I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C master port.

slaveDeviceAddress

The I2C 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 I2C 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 I2C bus because the specified I2C master port is not active. Use the DlnI2cMasterEnable()function to activate the I2C 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 I2C 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 I2C 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 I2C 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 I2C 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 I2C write operation because the specified I2C master port is not active. Use the DlnI2cMasterEnable()function to activate the I2C master port.

Remarks

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

I2C Slave Interface

Some DLN-series adapters support I2C slave interface.

Before you activate the I2C slave port, you need to configure it (See Configuring I2C Slave Interface).

You can configure events to be informed when an I2C master receives data from your slave and/or transmits data to it (See I2C Slave Events).

Rating: 
No votes yet

Configuring I2C Slave Interface

To provide the I2C communication, you need to configure the I2C slave port:

  1. Specify the I2C slave address of your device. DLN adapters support 7-bit addressing. Some DLN adapters allow to specify several I2C slave addresses. For details, read I2C Slave Addressing.

  2. Configure general call support. I2C slave can ignore or acknowledge the general call addressing when data can be transmitted to all I2C slaves simultaneously. For details, read General Call Support.

  3. Configure generating events. Events can be generated when an I2C master initiates data transmission. If you do not need these notifications, cancel generating events. Read I2C Slave Events.

After you have finished configuring the I2C slave device, enable the I2C slave port by the DlnI2cSlaveEnable() function.

Rating: 
No votes yet

I2C Slave Addressing

DLN adapters support only 7-bit addressing. To assign a I2C slave address to your device, use the DlnI2cSlaveSetAddress() function. This function does not prevent you from assigning reserved addresses to your DLN adapter. For more information about reserved addresses, read Reserved I2C Slave Addresses.

Some DLN adapters can support more than one I2C slave addresses simultaneously. To check how many I2C slave addresses are supported by your DLN adapter, use the DlnI2cSlaveGetAddressCount() function. To assign several I2C slave addresses to your DLN adapter, use the DlnI2cSlaveSetAddress() function for every address. In the function, you specify the slaveAddressNumber parameter; its value should be unique for every I2C slave address but should not exceed the number of supported slave addresses.

To check an I2C slave address assigned to your device, call the DlnI2cSlaveGetAddress() function and point the desired value of the slaveAddressNumber parameter. To check all assigned I2C slave addresses, call the DlnI2cSlaveGetAddress() function for every possible slaveAddressNumber value.

Rating: 
No votes yet

General Call Support

I2C bus allows to transmit data to all I2C slaves simultaneously. This option is called General Call. To make a general call, the I2C master generates the following address: 0000 000 followed by the Write (0) direction bit. The General Call address is one of the reserved addresses and cannot be assigned to any I2C slave device.

When an I2C slave receives the general call address, it can acknowledge it to receive transmitted data or ignore it.

You can configure the I2C slave’s behavior when it receives the general call address:

To check the current configuration of the general call support, use the DlnI2cSlaveGeneralCallIsEnabled() function.

Rating: 
Average: 5 (1 vote)

I2C Slave Events

There are two ways to detect an I2C transmission:

  • To observe I2C lines permanently. This consumes much CPU time. Besides, the more times the device polls the I2C bus, the less time it can spend carrying out its intended function. That is why such devices are slow.

  • To receive events about the requests from the I2C bus. You can configure event generation when the I2C master addresses for receiving or transmitting data.

To configure events, use the DlnI2cSlaveSetEvent() function. You need to specify the slaveAddressNumber and eventType parameters. The DlnI2cSlaveGetSupportedEventTypes() function returns the list of event types available for the I2C slave port.

The eventType parameter can have one of the following values:

I2C Events Types

DLN_I2C_SLAVE_EVENT_NONE

A DLN adapter does not generate any I2C events.

DLN_I2C_SLAVE_EVENT_READ

A DLN adapter generates events when the I2C master device initiates receiving data from the I2C slave address assigned to the DLN adapter. The DLN_I2C_SLAVE_READ_EV structure describes the event details. Read DLN_I2C_SLAVE_EVENT_READ Events

DLN_I2C_SLAVE_EVENT_WRITE

A DLN adapter generates events when the I2C master device initiates transmitting data to the I2C slave address assigned to the DLN adapter. The DLN_I2C_SLAVE_WRITE_EV structure describes the event details. Read DLN_I2C_SLAVE_EVENT_WRITE Events

DLN_I2C_SLAVE_EVENT_READ_WRITE

A DLN adapter generates events when the I2C master device initiates receiving data from or transmitting data to the I2C slave address assigned to the DLN adapter. The DLN_I2C_SLAVE_READ_EV structure describes the read event details. The DLN_I2C_SLAVE_WRITE_EV structure describes the write event details. Read DLN_I2C_SLAVE_EVENT_READ_WRITE Events

By default, event generation is disabled for all I2C slave addresses (the eventType parameter is set to DLN_I2C_SLAVE_EVENT_NONE).

If your DLN adapter uses more than one I2C slave address, you can specify different event configuration for each I2C slave address.

Rating: 
No votes yet

DLN_I2C_SLAVE_EVENT_READ Events

A DLN adapter generates the DLN_I2C_SLAVE_EVENT_READ events each time the I2C master device initiates receiving data from the I2C slave address assigned to the DLN adapter.

DLN_I2C_SLAVE_EVENT_READ event

Use the DlnI2cSlaveSetEvent() function to configure events. Pass DLN_I2C_SLAVE_EVENT_READ for the eventType parameter.

The DLN_I2C_SLAVE_READ_EV structure describes the event details: event counter, I2C slave address and port number, and the buffer size. The header of the structure contains the msgId field that is set to DLN_MSG_ID_I2C_SLAVE_READ_EV (0x0C10).

Rating: 
No votes yet

DLN_I2C_SLAVE_EVENT_WRITE Events

A DLN adapter generates the DLN_I2C_SLAVE_EVENT_WRITE events each time the I2C master device initiates transmitting data to the I2C slave address assigned to the DLN adapter.

DLN_I2C_SLAVE_EVENT_WRITE event

Use the DlnI2cSlaveSetEvent() function to configure events. Pass DLN_I2C_SLAVE_EVENT_WRITE for the eventType parameter.

The DLN_I2C_SLAVE_WRITE_EV structure describes the event details: event counter, I2C slave address and port number, the buffer size and the received data. The header of the structure contains the msgId field that is set to DLN_MSG_ID_I2C_SLAVE_WRITE_EV (0x0C11).

Rating: 
No votes yet

DLN_I2C_SLAVE_EVENT_READ_WRITE Events

A DLN adapter generates the DLN_I2C_SLAVE_EVENT_READ_WRITE events each time the I2C master device initiates receiving data from or transmitting data to the I2C slave address assigned to the DLN adapter.

DLN_I2C_SLAVE_EVENT_READ_WRITE events

Use the DlnI2cSlaveSetEvent() function to configure events. Pass DLN_I2C_SLAVE_EVENT_READ_WRITE for the eventType parameter.

The DLN_I2C_SLAVE_EVENT_READ_WRITE events are described by two structures:

  • The DLN_I2C_SLAVE_READ_EV structure describes the I2C read event details: event counter, I2C slave address and port number, and the buffer size. The header of the structure contains the msgId field that is set to DLN_MSG_ID_I2C_SLAVE_READ_EV (0x0C10).

  • The DLN_I2C_SLAVE_WRITE_EV structure describes the I2C write event details: event counter, I2C slave address and port number, the buffer size and the received data. The header of the structure contains the msgId field that is set to DLN_MSG_ID_I2C_SLAVE_WRITE_EV (0x0C11).

Rating: 
No votes yet

I2C Slave Functions

Use the I2C Slave Interface functions to control and monitor the I2C Slave module of a DLN-series adapter. The dln_i2c_slave.h file declares the I2C Slave Interface functions.

General port information:

DlnI2cSlaveGetPortCount()

Retrieves the total number of I2C slave ports available at your DLN-series adapter.

DlnI2cSlaveEnable()

Assigns a port to the I2C Slave module.

DlnI2cSlaveDisable()

Releases a port from the I2C Slave module.

DlnI2cSlaveIsEnabled()

Retrieves whether a port is assigned to the I2C Slave module.

DlnI2cSlaveLoadReply()

Loads data to be transmitted to an I2C master device.

I2C Slave module configuration functions:

DlnI2cSlaveGeneralCallEnable()

Activates I2C general call support.

DlnI2cSlaveGeneralCallDisable()

Disables I2C general call support.

DlnI2cSlaveGeneralCallIsEnabled()

Retrieves whether I2C general call support is activated.

DlnI2cSlaveGetAddressCount()

Retrieves the number of I2C slave addresses supported by the DLN adapter.

DlnI2cSlaveSetAddress()

Assigns an I2C slave address to the specified I2C slave module.

DlnI2cSlaveGetAddress()

Retrieves one of the I2C slave addresses assigned to the specified I2C slave module.

I2C Slave event functions:

DlnI2cSlaveSetEvent()

Configures event generation for an I2C slave port.

DlnI2cSlaveGetEvent()

Retrieves event generation configuration for an I2C slave port.

DlnI2cSlaveGetSupportedEventTypes()

Retrieves the list of event types available for an I2C slave port.

Rating: 
No votes yet

DlnI2cSlaveDisable() Function

The DlnI2cSlaveDisable() function deactivates the specified I2C slave port at your DLN-series adapter and releases the pins previously used for SDA and SCL lines.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveDisable(
   HDLN handle,
   uint8_t port,
   uint8_t waitForTransferCompletion
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

waitForTransferCompletion

The parameter that contains your choice according the function behavior if the I2C slave port is busy transmitting data. The following values are possible:

  • DLN_I2C_SLAVE_WAIT_FOR_TRANSFERS(1) - Wait until the transmission completes.

  • DLN_I2C_SLAVE_CANCEL_TRANSFERS(0) - Cancel all pending data transmissions and disable the module.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully deactivated the I2C slave port.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

DLN_RES_TRANSFER_CANCELLED (0x20)

The function cancelled the pending data transmission.

Remarks

The DlnI2cSlaveDisable() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveEnable() Function

The DlnI2cSlaveEnable() function activates the specified I2C slave port at your DLN-series adapter.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveEnable(
   HDLN handle,
   uint8_t port,
   uint16_t* conflict
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

conflict

A number of the pin that is currently occupied by another module. To fix this, check which module uses the pin (call the DlnGetPinCfg()function), disconnect the pin from that module and call the DlnI2cSlaveEnable() function once again.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully activated the I2C slave port.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

DLN_RES_PIN_IN_USE (0xA5)

At least one pin of the port is assigned to another module. The conflict parameter contains the number of the conflicting pin.

DLN_RES_I2C_SLAVE_ADDRESS_NEEDED (0xBE)

The I2C slave address is not specified for this device. Use the DlnI2cSlaveSetAddress() function to specify the address.

Remarks

The I2C bus interface requires two lines for data transmission and synchronization (SDA and SCL). If any of these lines is used by another module, the DLN adapter cannot activate the I2C slave port. The DlnI2cSlaveEnable() function returns only one conflicting pin. If both SCL and SDA lines are in use, you need to call this function three times: two times to detect both conflicting pins and the third time to enable the I2C slave port.

The DlnI2cSlaveEnable() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveGeneralCallDisable() Function

The DlnI2cSlaveGeneralCallDisable() function disables the I2C general call support to make this slave ignore general call addressing.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveGeneralCallDisable(
   HDLN handle,
   uint8_t port,
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully disabled the general call support.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cSlaveGeneralCallDisable()function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveGeneralCallEnable() Function

The DlnI2cSlaveGeneralCallEnable() function activates I2C general call support. With general call all I2C slave devices on the circuit can be addressed by sending zero as I2C slave address.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveGeneralCallEnable(
   HDLN handle,
   uint8_t port,
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully enabled the general call support.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cSlaveGeneralCallEnable() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveGeneralCallIsEnabled() Function

The DlnI2cSlaveGeneralCallIsEnabled() function checks whether I2C general call support is enabled for the specified I2C slave port.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveGeneralCallIsEnabled(
   HDLN handle,
   uint8_t port,
   uint8_t* enabled
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

enabled

A pointer to an unsigned 8-bit integer that receives information whether general call support is enabled. There are two possible values:

  • DLN_I2C_SLAVE_GENERAL_CALL_DISABLED (0) - The I2C slave port ignores the general call address.

  • DLN_I2C_SLAVE_GENERAL_CALL_ENABLED (1) - The 2C slave port acknowledges the general call address and receives transmitted data.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully retrieved whether the general call support is enabled.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cSlaveGeneralCallIsEnabled() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveGetAddress() Function

The DlnI2cSlaveGetAddress() function retrieves one of the I2C slave addresses, assigned to the specified I2C slave module. The total number of simultaneously assigned addresses can be retrieved with the DlnI2cSlaveGetAddressCount() function.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveGetAddress(
   HDLN handle,
   uint8_t port,
   uint8_t slaveAddressNumber,
   uint8_t* address
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

slaveAddressNumber

A number of the I2C slave address to be retrieved. The slaveAddressNumber value can be in the range from 0 up to (but not including) the value returned by the DlnI2cSlaveGetAddressCount() function.

address

A pointer to an unsigned 8-bit integer that receives the I2C slave address.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully retrieved the I2C slave address.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cSlaveGetAddress() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveGetAddressCount() Function

The DlnI2cSlaveGetAddressCount() function retrieves the number of I2C slave addresses supported by the DLN adapter.

DLN-series adapters can acknowledge any I2C slave address. The limitation is only in the amount of slave addresses to be used simultaneously. You can use the DlnI2cSlaveSetAddress() function to configure the I2C slave module to acknowledge specific addresses.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveGetAddressCount(
   HDLN handle,
   uint8_t port,
   uint8_t* count
);
Parameters
handle

A handle to the DLN-series adapter

port

A number of the I2C slave port.

count

A pointer to an unsigned 8-bit integer that receives the number of supported I2C slave addresses.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully retrieved the number of possible slave addresses.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cSlaveGetAddressCount() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveGetEvent() Function

The DlnI2cSlaveGetEvent() function retrieves settings for I2C event generation for the specified I2C slave port and I2C slave address.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveGetEvent(
   HDLN handle,
   uint8_t port,
   uint16_t slaveAddressNumber
   uint8_t* eventType,
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

slaveAddressNumber

A number of the I2C slave address to retrieve settings for. Use the DlnI2cSlaveGetAddressCount() function to obtain the total number of supported I2C slave addresses.

eventType

A pointer to an unsigned 8-bit integer that receives the current event generation settings. The following values are supported:

  • I2C_SLAVE_EVENT_NONE (0) - No I2C slave events are generated.

  • I2C_SLAVE_EVENT_READ (1) - I2C slave events are generated when an I2C master device reads data from the PC-I2C adapter.

  • I2C_SLAVE_EVENT_WRITE (2) - I2C slave events are generated when an I2C master device writes data to the PC-I2C adapter.

  • I2C_SLAVE_EVENT_READ_WRITE (1) - I2C slave events are generated both for read and write transactions.

Refer to I2C Slave Events section for additional information.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully retrieved the current I2C slave events configuration.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cSlaveGetEvent() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveGetPortCount() Function

The DlnI2cSlaveGetPortCount() function retrieves the total number of I2C slave ports available in your DLN-series adapter.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveGetPortCount(
   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 I2C slave ports.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully retrieved the number of I2C slave ports.

Remarks

The DlnI2cSlaveGetPortCount() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveGetSupportedEventTypes() Function

The DlnI2cSlaveGetSupportedEventTypes() function returns all supported I2C slave event types for opened DLN-series adapter.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveGetSupportedEventTypes(
    HDLN handle, 
    uint8_t port, 
    DLN_I2C_SLAVE_EVENT_TYPES *supportedEventTypes
);
Parameters
handle

A handle to the DLN-series adapter.

port

I2C slave port number.

supportedEventTypes

The pointer to DLN_I2C_SLAVE_EVENT_TYPES structure that receives the supported event types.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully retrieved the supported I2C slave events.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cSlaveGetSupportedEventTypes() function is defined in dln_spi_slave.h file.

DlnI2cSlaveIsEnabled() Function

The DlnI2cSlaveIsEnabled() function checks whether the specified I2C slave port is active or not.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveIsEnabled(
  HDLN handle,
  uint8_t port,
  uint8_t* enabled
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

enabled

A pointer to an unsigned 8-bit integer that receives information whether the specified I2C slave port is active or not. There are two possible values:

  • DLN_I2C_SLAVE_DISABLED (0) - The I2C slave port is inactive.

  • DLN_I2C_SLAVE_ENABLED (1) - The I2C slave port is active.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully retrieved information.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

Remarks

The DlnI2cSlaveIsEnabled() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveLoadReply() Function

The DlnI2cSlaveLoadReply() function loads data to be transferred to an I2C master device.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveLoadReply(
   HDLN handle,
   uint8_t port,
   uint16_t size,
   uint8_t* buffer
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

size

A size of the data buffer to be loaded. The size is specified as a number bytes and can vary from 1 to 256.

buffer

A pointer to an array of unsigned 8-bit integers that receives data to be sent to an I2C master. The size of the buffer is specified in the size parameter.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully loaded data to the buffer.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

DLN_RES_BUSY (0xB6)

The function cannot specify I2C slave addresses for the DLN adapter while the I2C slave port is busy transmitting data.

DLN_RES_INVALID_BUFFER_SIZE (0xAE)

The specified buffer size is not valid.

Remarks

The DlnI2cSlaveLoadReply() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveSetAddress() Function

The DlnI2cSlaveSetAddress() function assigns I2C addresses to the specified I2C slave module. You can assign any 7-bit address, the limitation is only in quantity of addresses that can be used simultaneously. Use the DlnI2cSlaveGetAddressCount() function to retrieve the number of simultaneously supported I2C slave addresses.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveSetAddress(
   HDLN handle,
   uint8_t port,
   uint8_t slaveAddressNumber,
   uint8_t address
);
Parameters
handle

A handle to the DLN-series adapter.

port

An I2C slave port to be configured.

slaveAddressNumber

A number of the I2C slave address to be assigned. Use the DlnI2cSlaveGetAddressCount()function to retrieve the number of simultaneously supported I2C slave addresses. The slaveAddressNumber is zero based.

address

An I2C slave address to be set to the specified I2C slave port.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully specified I2C slave addresses for your DLN adapter.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

DLN_RES_BUSY (0xB6)

The function cannot specify I2C slave addresses for the DLN adapter while the I2C slave port is busy transmitting data.

DLN_RES_INVALID_ADDRESS (0xB4)

The I2C slave address is not valid.

Remarks

The DlnI2cSlaveSetAddress() function is defined in the dln_i2c_slave.h file.

DlnI2cSlaveSetEvent() Function

The DlnI2cSlaveSetEvent() function configures the I2C slave events generation conditions for the specified I2C slave port and I2C slave address.I2C slave events can vary for different I2C slave addresses. Specify the number of the I2C slave address in the slaveAddressNumber parameter.

Syntax
C/C++
DLN_RESULT DlnI2cSlaveSetEvent(
   HDLN handle,
   uint8_t port,
   uint8_t slaveAddressNumber,
   uint8_t eventType,
);
Parameters
handle

A handle to the DLN-series adapter.

port

A number of the I2C slave port.

slaveAddressNumber

A number of the I2C slave address. The slaveAddressNumber parameter is zero base. Possible value are from zero up to (but not including) the value returned by the DlnI2cSlaveGetAddressCount() function.

eventType

A condition for I2C slave event generation. The following values are available:

  • I2C_SLAVE_EVENT_NONE (0) - No I2C slave events are generated.

  • I2C_SLAVE_EVENT_READ (1) - I2C slave events are generated when an I2C master device reads data from the PC-I2C adapter.

  • I2C_SLAVE_EVENT_WRITE (2) - I2C slave events are generated when an I2C master device writes data to the PC-I2C adapter.

  • I2C_SLAVE_EVENT_READ_WRITE (3) - I2C slave events are generated both for read and write transactions.

For additional details, read the I2C Slave Events section.

Return Value
DLN_RES_SUCCESS (0x00)

The function successfully configured I2C slave events.

DLN_RES_INVALID_PORT_NUMBER (0xA8)

The port number is not valid. Use the DlnI2cSlaveGetPortCount() function to find the maximum possible port number.

DLN_RES_BUSY (0xB6)

The function cannot configure I2C slave addresses for the DLN adapter while the I2C slave port is busy transmitting data.

DLN_RES_INVALID_EVENT_TYPE (0xA9)

The specified event type is not valid. Use the DlnI2cSlaveGetSupportedEventTypes() function to check the list of supported I2C slave events.

Remarks

The DlnI2cSlaveSetEvent() function is defined in the dln_i2c_slave.h file.

I2C Event Structures

This section describes the structures used for I2C events. These structures are declared in the dln_i2c_slave.h file.

Rating: 
No votes yet

DLN_I2C_SLAVE_READ_EV Structure

The DLN_I2C_SLAVE_READ_EV structure contains information about the I2C read event.

Syntax
C/C++
typedef struct
{
        DLN_MSG_HEADER header;
        uint16_t eventCount;
        uint8_t eventType;
        uint8_t port;
        uint8_t slaveAddress;
        uint16_t size;
} __PACKED_ATTR DLN_I2C_SLAVE_READ_EV;
Event Structure Members
header

Defines the DLN message header. It should have the following value: DLN_MSG_ID_I2C_SLAVE_READ_EV (0x0C10).

eventCount

The number of events generated after the event configuration changed.

eventType

The type of generating events. The following values are possible:

ValueConstantDescription

1

DLN_I2C_SLAVE_EVENT_READ

Events are generated when the I2C master initiates receiving data from the I2C slave device.

3

DLN_I2C_SLAVE_EVENT_READ_WRITE

Events are generated when the I2C master initiates receiving data from or transmitting data to the I2C slave device.

port

The number of the I2C slave port where the event is generated.

slaveAddress

The I2C slave address assigned to the DLN adapter that generated the event.

size

A size of the buffer that stores the event data.

DLN_I2C_SLAVE_WRITE_EV Structure

The DLN_I2C_SLAVE_WRITE_EV structure contains information about the I2C write event.

Syntax
C/C++
typedef struct
{
        DLN_MSG_HEADER header;
        uint16_t eventCount;
        uint8_t eventType;
        uint8_t port;
        uint8_t slaveAddress;
        uint16_t size;
        uint8_t buffer[DLN_I2C_SLAVE_BUFFER_SIZE];
} __PACKED_ATTR DLN_I2C_SLAVE_WRITE_EV;
Event Structure Members
header

Defines the DLN message header. It should have the following value: DLN_MSG_ID_I2C_SLAVE_WRITE_EV (0x0C10).

eventCount

The number of events generated after the event configuration changed.

eventType

The type of generating events. The following values are possible:

ValueConstantDescription

2

DLN_I2C_SLAVE_EVENT_WRITE

Events are generated when the I2C master initiates transmitting data from the I2C slave device.

3

DLN_I2C_SLAVE_EVENT_READ_WRITE

Events are generated when the I2C master initiates receiving data from or transmitting data to the I2C slave device.

port

The number of the I2C slave port where the event is generated.

slaveAddress

The I2C slave address assigned to the DLN adapter that generated the event.

size

A size of the buffer that stores the event data.

buffer

The buffer that contains data received from the I2C master.