The DlnOpenDevice() function allows you to open all available devices in a loop. This function accepts two parameters - an index number of the adapter to open and the pointer to the variable that receives the device handle. The deviceNumber parameter is zero-based.

You can call the DlnGetDeviceCount() function to obtain the number of available devices, and then call the DlnOpenDevice() function in a loop to open all devices as illustrated in the following code snippet:

C/C++

HDLN
handle;
DLN_RESULT result = DlnOpenDevice(0, &handle);

You should make no assumptions about the association between deviceNumber parameter and the specific hardware. You can call the DlnGetDeviceSn() or DlnGetDeviceId() function to identify the device after it is open, or use one of the functions listed in the next chapters to open a specific device.

The DlnOpenDevice() and DlnGetDeviceCount() functions enumerate and open devices currently accessible to the DLN library - the device should be accessible to the computer where the DLN Server is running and your application should be connected to this DLN Server. In case of Direct Mode, the library itself establishes connections to the devices accessible to local PC. You can treat this as if the library is connected to the DLN Server running on the same PC where the application is launched.

The connection to the DLN Server is established by calling the DlnConnect() function, providing server IP and TCP port. After connection is established you get access to all devices accessible to the PC where the server is running:

• Devices connected to the USB port of this computer.

• Devices located in the range of Bluetooth Low Energy (BLE) connectivity to this computer.

Every DLN-series adapter has a unique serial number, allocated during the manufacturing. You can obtain the serial number of the device by calling the DlnGetDeviceSn() function. Use the DlnOpenUsbDeviceBySn() function to open the device with the specific serial number.

The device serial number can’t be changed. We do not recommend to use it to distinguish between the devices that are expected to perform different actions. Using the serial number tightly couples your application to the specific hardware.

There is a much more scalable approach. You can assign an ID number to any DLN-series adapter and then use it to identify the specific hardware. To assign the ID number use our DeviceId.exe application or call the DlnSetDeviceId() function. The ID number is stored in the internal non-volatile memory. It remains the same even when the adapter is connected to another computer.

When you know the ID number of the specific adapter, you can open it with the DlnOpenDeviceById() function.

DLN series include a number of different devices. All these devices support API described in the current manual, but their available functionality may slightly differ. For example, they can support different SPI and I2C bus frequencies, not all of the adapters implement I2C/SPI slave interfaces, etc.

If you know that your application needs a specific DLN-series device, you can check the hardware type of the adapter by calling the DlnGetHardwareType() function. The hardware type constants are defined in the dln_generic.h file as follows:

C/C++

#define
DLN_HW_TYPE uint32_t
#define DLN_HW_TYPE_DLN5  ((DLN_HW_TYPE)0x0500)
#define DLN_HW_TYPE_DLN4M ((DLN_HW_TYPE)0x0401)
#define DLN_HW_TYPE_DLN4S ((DLN_HW_TYPE)0x0402)
#define DLN_HW_TYPE_DLN3  ((DLN_HW_TYPE)0x0300)
#define DLN_HW_TYPE_DLN2  ((DLN_HW_TYPE)0x0200)
#define DLN_HW_TYPE_DLN1  ((DLN_HW_TYPE)0x0100)

You can use the DlnOpenDeviceByHwType() function to open the adapter with the predefined hardware type.

Instead of checking the specific device type, you can check if the adapter implements the required functionality. DLN API provides you with a number of ways to do this.

You can interface the DLN series adapters either directly or through the DLN server application. The DLN server is a Windows Service or Linux / Mac OS X Daemon. The applications communicate with the DLN server through TCP/IP. The most prominent difference between the Direct and the Server Based interfaces is that the Direct Interface can provide you with the higher bandwidth when you transfer a large amount of data, while the Server Based Interface allows several applications to communicate with the same adapter simultaneously. For additional details please refer to the Interface Types chapter in the User Manual.

Server Based Interface

Without going into details (the details are described in the Server Base Interface implementation chapter), you need to connect to the DLN server if you use the Server Based Interface. The connection is established by calling the DlnConnect() function. The DLN Server IP address and TCP port number are passed to this function as parameters.

If the DLN series adapter is connected to the computer where you launch your application, and you don’t change the default port configuration, you can use the DlnConnectDefault() function to connect to the DLN server.

As with most of the functions that allocate resources, the established connection can be closed by calling the DlnDisconnect() function with the same parameters. Use the DlnDisconnectDefault() function to close the connection established with the DlnConnectDefault() function. If you want to close all currently opened connections, call the DlnDisconnectAll() function.

Direct Interface

The dln.dll library for the Direct Interface does not require the connection to the DLN server. It is designed to directly communicate with DLN-series adapters connected to the computer where the application is running. You are not required to call the DlnConnect(), DlnDisconnect() and DlnDisconnectAll() functions in the Direct Interface, but you can do this to make your code compatible with the Server Based Interface. These functions do nothing in the Direct Interface, they simply return the successful result code

The DLN library may notify the user application when new messages arrive from the device.

There are 4 different types of notifications:

• Callback function.

• Event object.

• Window message.

• Thread message.

You can configure the same notification settings for all the messages. To do so, call the DlnRegisterNotification() function and specify HDLN_ALL_DEVICES(0) value as a handle. In this case the DLN library will notify the user application about messages from all devices.

The DLN library may notify the application about messages from a specific device. To configure such notification settings, call the DlnRegisterNotification() function and specify the handle of the device. Streams (like devices) have their own handles. So, you may configure the notification settings for a specific stream as well.

You can use the DlnRegisterNotification() function several times, specifying various notification settings for different devices (streams). For example, if you have 4 devices, you may register certain notification settings for one device and different settings for other devices. When a device sends a message, the library checks the notification settings for current device. If the library finds such settings, the notification is generated. If there are no settings for current device, the library checks the notification settings for all devices. If there are no such settings either, the notification isn't generated and the message isn't pushed into the queue.

Sometimes it is useful when messages aren't pushed into the queue. It is most convenient for those who use only synchronous communication. During the synchronous communication the application doesn't call the DlnGetMessage() function. Thus the messages aren't removed from the queue. It leads to memory leak and eventually to memory overflow. If you don't want messages to be enqueued, you shouldn't register any notification settings.

If you want the messages to be enqueued without notification, do the following. Call the DlnRegisterNotification() function and specify DLN_NOTIFICATION_TYPE_NO_NOTIFICATION value as the notification type. In this case the messages will be pushed into the queue without notification to the user application. The messages can be obtained with the help of the DlnGetMessage() function.

To unregister the notification settings call the DlnUnregisterNotification() function.

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

All the devices connected to the I²C 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 I²C bus, both lines are HIGH. In this case, we say that the I²C bus is free.

I²C 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.

Every byte, sent over the I²C 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).

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.

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 I²C 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.

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 I²C bus.

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

Some I²C 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 I²C 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.

In a multi-master I²C 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 I²C 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.

In an I²C communication, a master device determines the clock speed. The I²C 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 I²C 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 I²C bus might be significantly decreased.

To start using the I²C master port, you need to configure the I²C master interface:

1. Configure the I²C 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 I²C master port. If the pins of the I²C port are not used by other modules, you can enable the I²C master port by the DlnI2cMasterEnable() function.

I²C bus specification describes four operating speed categories for bidirectional data transmission:

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

Configuring the I²C 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 I²C lines, the values of pull-up resistors and the number of slaves connected to the I²C bus may influence the working frequency of the I²C 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 I²C bus if delays between bytes are longer than the bytes themselves.

The I²C 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 I²C 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 I²C 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.

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

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 I²C bus. To scan all possible addresses and to find devices connected to the I²C bus, us the DlnI2cMasterScanDevices() function. It returns the number of connected devices and the list of their addresses.You can use these addresses for I²C 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).

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.

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).

To provide the I²C communication, you need to configure the I²C slave port:

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

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

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

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

DLN adapters support only 7-bit addressing. To assign a I²C 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 I²C slave addresses simultaneously. To check how many I²C slave addresses are supported by your DLN adapter, use the DlnI2cSlaveGetAddressCount() function. To assign several I²C 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 I²C slave address but should not exceed the number of supported slave addresses.

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

There are two ways to detect an I²C transmission:

• To observe I²C lines permanently. This consumes much CPU time. Besides, the more times the device polls the I²C 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 I²C bus. You can configure event generation when the I²C 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:

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

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

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

General port information:

DlnI2cSlaveGetPortCount()

Retrieves the total number of I²C slave ports available at your DLN-series adapter.

DlnI2cSlaveEnable()

Assigns a port to the I²C Slave module.

DlnI2cSlaveDisable()

Releases a port from the I²C Slave module.

DlnI2cSlaveIsEnabled()

Retrieves whether a port is assigned to the I²C Slave module.

DlnI2cSlaveLoadReply()

Loads data to be transmitted to an I²C master device.

I²C Slave module configuration functions:

DlnI2cSlaveGeneralCallEnable()

Activates I²C general call support.

DlnI2cSlaveGeneralCallDisable()

Disables I²C general call support.

DlnI2cSlaveGeneralCallIsEnabled()

Retrieves whether I²C general call support is activated.

DlnI2cSlaveGetAddressCount()

Retrieves the number of I²C slave addresses supported by the DLN adapter.

DlnI2cSlaveSetAddress()

Assigns an I²C slave address to the specified I²C slave module.

DlnI2cSlaveGetAddress()

Retrieves one of the I²C slave addresses assigned to the specified I²C slave module.

I²C Slave event functions:

DlnI2cSlaveSetEvent()

Configures event generation for an I²C slave port.

DlnI2cSlaveGetEvent()

Retrieves event generation configuration for an I²C slave port.

DlnI2cSlaveGetSupportedEventTypes()

Retrieves the list of event types available for an I²C slave port.

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

For reliable SPI communication, you have to configure the SPI master interface according to the SPI slave requirements:

1. Configure the clock (SCK) signal, using a frequency, which does not exceed the maximum frequency that the slave device supports. For details, read Clock Frequency.

2. Configure the transmission mode (clock polarity and clock phase). The clock polarity (CPOL) and clock phase (CPHA) configuration must be the same for both SPI master and SPI slave devices. For details, read Clock Phase and Polarity.

3. Configure the frame size. The frame size instructs the DLN adapter how to treat data inside the buffer. The data can be treated as 8-16 bit integers. If the configured frame size exceeds 8 bits, the bytes inside the frame are stored in Little Endian format. For details, read SPI Data Frames.

4. Customize releasing the SS line between frames. Some slave devices require the signal in the SS line going LOW to initiate data transmission. When the frame transmission is complete, the master should pull the SS line HIGH and then LOW again to reinitiate the frame transmission with the same slave. This parameter is optional. For details, read SS Line Release Between Frames.

5. If a slave device needs additional time to process or generate data, configure delays. For details, read SPI Delays.

To start communication, you need to select the slave. Dropping the signal on an SS line initiates data transmission between the master and the appropriate slave device. The Connecting Multiple Slave Devices section describes possible configurations. You can select a slave device before or after enabling the SPI master port.

SPI bus allows continuous data transmission. When you pass a buffer (array of words) to one of the SPI Master Transmission Functions, the DLN adapter transmits the data bit after bit as in the following figure.

Logically, your application and an SPI slave device treat this data as an array of 8-bit or 16-bit words. Some SPI slave devices (for example, digital-to-analog or analog-to-digital converters) operate with 12-bit words.

DLN adapters allow you to support a wide range of SPI slave devices. You can configure the frame size (number of bits in the word) by using the DlnSpiMasterSetFrameSize() function. DLN adapters support 8 to 16 bits per frame.

In DLN adapters, the frame data is transmitted in a Little Endian format (starting from the most-significant bit and up to the least-significant bit). If the frame size is not a multiple of 8, the unused (most-significant) bits are discarded, regardless of their content.

To transmit data as arrays of more than 8 bits, you can use the DlnSpiMasterReadWrite16() function. It transmits data in little endian format that is very useful because most microcontrollers store data in this format.

For information about all functions that you can use to transmit data, read the SPI Master Transmission Functions section.

SPI bus can operate at very high speeds, which may be too fast for some slave devices. To accommodate such devices, the SPI bus contains the clock (CLK). The signal on the SCK line is transmitted with the same frequency as data flows. Thus, there is no need to synchronize the transmission speed of master and slave devices.

To configure the clock signal of the master, use the DlnSpiMasterSetFrequency() function.

When configuring the SPI master interface, you specify the frequency value supported by the slave device. If the specified value is not compatible with your DLN adapter, the function approximates the value to the closest lower frequency value supported by the adapter.

A range of supported clock frequency values depends on the DLN adapter:

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

• DLN-2 adapters support clock frequency from 2kHz up to 18MHz.

• DLN-4 adapters support clock frequency from 376kHz up to 48MHz.

In addition to setting the clock frequency, the master also configures the clock polarity (CPOL) and clock phase (CPHA). For detailed information, read Clock Phase and Polarity.

The master configures the clock polarity (CPOL) and clock phase (CPHA) to correspond to slave device requirements. These parameters determine when the data must be stable, when it should be changed according to the clock line and what the clock level is when the clock is not active.

The CPOL parameter assigns the clock level when the clock is not active. The clock (SCK) signal may be inverted (CPOL=1) or non-inverted (CPOL=0). For the inverted clock signal, the first clock edge is falling. For the non-inverted clock signal, the first clock edge is rising.

The CPHA parameter is used to shift the capturing phase. If CPHA=0, the data are captured on the leading (first) clock edge, regardless of whether that clock edge is rising or falling. If CPHA=1, the data are captured on the trailing (second) clock edge; in this case, the data must be stable for a half cycle before the first clock cycle.

There are four possible modes that can be used in an SPI protocol:

1. For CPOL=0, the base value of the clock is zero. For CPHA=0, data are captured on the clock’s rising edge and data are propagated on a falling edge.

   

2. For CPOL=0, the base value of the clock is zero. For CPHA=1, data are captured on the clock’s falling edge and data are propagated on a rising edge.

   

3. For CPOL=1, the base value of the clock is one. For CPHA=0, data are captured on the clock’s rising edge and data are propagated on a falling edge.

   

4. For CPOL=1, the base value of the clock is one. For CPHA=1, data are captured on the clock’s falling edge and data are propagated on a rising edge.

   

In DLN adapters, the default transmission mode configuration has CPOL=0, CPHA=0 values.

You can specify the mode using the DlnSpiMasterSetMode() function. To configure the CPOL and CPHA values separately, use the DlnSpiMasterSetCpol() and DlnSpiMasterSetCpha() functions.

The master and a slave must use the same set of parameters (clock frequency, CPOL and CPHA); otherwise, a communication will be impossible. If multiple slaves are used, the master configuration should change each time before the master initiates communication with a different slave.

DLN adapters can operate in the following modes:

• Full-duplex – the master sends data to a slave and receives data from the slave simultaneously.

• Half-duplex (read) – the master receives data from a slave.

• Half-duplex (write) – the master sends data to a slave.

In SPI, a master can communicate with a single or multiple slaves. For applications using multiple slaves, the following configurations are possible:

1. Independent slaves. This is a most common configuration of the SPI bus. The MOSI, MISO and SCK lines of all slaves are interconnected. The SS line of every slave device is connected to a separate pin of SPI master device. Since the MISO pins of the slaves are connected together, they are required to be tristate pins (high, low or high-impedance).

   

   To select the slave, the master pulls the corresponding SS line low. Only one slave can be selected.

   For DLN-1 or DLN-2 adapters, you can use the following functions:

   DlnSpiMasterSetSS()

   to select the SS line. The SS line value can include only one bit set to 0;

   DlnSpiMasterReadWrite()

   to transmit data to/from the slave device;

   DlnSpiMasterReleaseSS()

   to release the SS line after transmission if the master does not need to transmit more data to the same slave.

   For a DLN-4M adapter, use the DlnSpiMasterReadWriteSS() function – it selects the specified SS line, transmits data and releases the SS line.In a half-duplex read mode, you can also select only one slave. The following functions can be used:

   DlnSpiMasterSetSS()

   to select the SS line. The SS line value can include only one bit set to 0;

   DlnSpiMasterReadEx()

   to read data from the slave device and to release the SS line after transmission if required.

2. Independent slave configuration with decoder/demultiplexer. The SS lines are used to send an n-bit value, which is the number of the selected slave. Here, the master can communicate with m=2ⁿ slaves.

   

   If you use this configuration, in the DlnSpiMasterSetSS() function the value of the SS lines can include more than one zeros. The demultiplexer converts this value and activates only one SS line.

3. Half-duplex write configuration. The master transmits data on the MOSI line and the slave receives it. The MISO line remains inactive.

   

   If your slave devices only receive data, you can address multi slaves simultaneously. The following functions can be used:

   DlnSpiMasterSetSS()

   to select the SS line; the SS line value can include more than one bits set to 0 (several SS lines can be selected – the master can send data to several slave devices simultaneously);

   DlnSpiMasterWriteEx()

   to write data from the slave device(s) and to release the SS line(s) after transmission (optionally).

   If the master always sends equal data to some group of slaves in a half-duplex write configuration, all the slaves from the group can be connected to one SS line:

   

4. Daisy-chain slaves: the first slave output is connected to the second slave input, etc. The SPI port of each slave is designed to send out during the second group of clock pulses an exact copy of the data it received during the first group of clock pulses.

   

To check the number of available SS lines in the SPI port, use the DlnSpiMasterGetSSCount() function.

To select the slave, use the DlnSpiMasterSetSS() function. By default, the first SS line (SS0) is selected.

Only one slave can be activated (the signal level on the SS line is low). However, if you use a demultiplexer, you do not select the line, but set the value of the line. The demultiplexer converts this value and selects only one SS line.

The DlnSpiMasterEnable() function enables the selected SS line. Use this function after you configure communication settings.

If you do not need to use all SS lines available in a SPI port, you can disable some of them to use them in other modules. On the contrary, you can enable SS lines that were used for other modules. To disable one SS line, use the DlnSpiMasterSSDisable() function. To disable several SS lines, use the DlnSpiMasterSSMultiDisable() function. To enable one or more SS lines, use the DlnSpiMasterSSEnable() or DlnSpiMasterSSMultiEnable() function accordingly.