The Serial Peripheral Interface (SPI) bus is a synchronous serial communication interface used for short distance communication between various peripheral devices. The SPI bus interconnects a single master device with one or more slave devices.
The master device originates the data transmission by selecting a slave device and generating a clock. Data is transmitted in both directions simultaneously (full-duplex mode) or in one direction (half-duplex mode).
DLN adapters can operate as a master device (read SPI Master Interface). DLN-4S adapter can also operate as a slave device (read SPI Slave Interface).
The SPI bus uses four signal lines:
SCK (Clock) – The master generates the clock to synchronize data transmission.
MOSI (Master Output, Slave Input) – The master sends data on the MOSI line, the slave receives it.
MISO (Master Input, Slave Output) – The slave sends data on the MISO line, the master receives it.
CS or SS (Chip Select or Slave Select) – The master drops the SS line to select the specific SPI slave device. The DLN adapters have several SS lines that you can connect to different slave devices.
Among these four lines, two of them (MOSI and MISO) are data lines, the other two (SS and SCK) are control and synchronization lines.
The SPI bus with a single master and a single slave connects the devices in the following way:
The SPI bus with a single master and multiple slaves connects the devices in the following way:
There are different ways to connect multiple slaves to a single master. See Connecting Multiple Slave Devices for additional information.
To initiate communication, the SPI master selects the slave (by pulling the corresponding SS line low) and starts generating the clock signal.
The clock signal synchronizes data transmission both from the master to a slave (the MOSI line) and from the slave to the master (the MISO line). The clock phase and polarity defines the clock phases where the master and the slave can sample data on the MOSI and MISO lines.
The DlnSpiFlashGetPortCount()
function retrieves the total number of SPI flash ports available in your DLN-series adapter.
The DlnSpiFlashEnable()
function activates the specified SPI flash port on your DLN-series adapter.
The DlnSpiFlashDisable()
function deactivates the specified SPI flash port on your DLN-series adapter.
The DlnSpiFlashIsEnabled()
function retrieves information whether the specified SPI flash port is activated.
The DlnSpiFlashSetFrequency()
function sets the clock frequency on the SCK line.
The DlnSpiFlashGetFrequency()
function retrieves the current setting for SPI clock frequency.
The DlnSpiFlashSetSS()
function selects a Slave Select (SS) line.
The DlnSpiFlashGetSS()
function retrieves the current Slave Select (SS) line.
The DlnSpiFlashSetSSMask()
function selects a required Slave Select (SS) lines by using mask value.
The DlnSpiFlashGetSSMask()
function retrieves the mask value of current selected Slave Select (SS) lines.
The DlnSpiFlashProgramPage()
function transfers data by using SPI flash interface.
The DlnSpiFlashReadPage()
function receives data via SPI flash interface. The data is received as an array of 1-byte elements.
Most of the DLN adapters support the SPI master interface. Some of them have several independent SPI master ports.
Before transmitting data, you need to configure the SPI master ports according to the slave requirements and enable it (See Configuring the SPI Master Interface).
You can either transmit data in full-duplex or in half-duplex mode (See SPI Data Transmission).
If you need to work with multi slave devices, you can interconnect them following the instructions in Connecting Multiple Slave Devices.
For reliable SPI communication, you have to configure the SPI master interface according to the SPI slave requirements:
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.
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.
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.
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.
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.
You want to transmit an array with the following data: ABCDEF01
If the frame size is 8 bits, the transmission proceeds as four 8-bit words: AB CD EF 01
If the frame size is 16 bits, the transmission proceeds as two 16-bit words. Each word is stored in the array in little endian format: CDAB 01EF
If the frame size is 12 bits, the transmission proceeds as two 12-bit words. This frame is not a multiple of 8, so the unused (most-significant) bits of the second byte in each word are discarded: ABC EF0
.
Each word is stored in the array in little endian format: CAB 0EF
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.
By default, if an array of several frames is transmitted between the master and the same slave, the SS line stays enabled until data transmission completes.
However, some SPI slave devices require the SS line to be deasserted between frames.
To release the SS line, use the DlnSpiMasterReleaseSS(). Use the DlnSpiMasterSSEnable() function to enable the SS line.
If an SPI slave device is not fast enough to process continuously incoming data, you can configure your DLN adapter to introduce a specified delay between frames. For more information about this and other delays, read SPI Delays.
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:
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.
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.
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.
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.
A full-duplex data transmission occurs during each SPI clock cycle: the master transmits data to the slave on the MOSI line and the slave receives it; at the same time, the slave transmits data to the master on the MISO line and the master receives it.
To transmit data in a full-duplex mode, use the DlnSpiMasterReadWrite() function (for 8-bit frames) or the DlnSpiMasterReadWrite16() function (for 9-16-bit frames).
Transmission may continue for any number of clock cycles. When complete, the master idles the clock and releases the SS line. Using the DlnSpiMasterReadWriteEx() function, you can configure whether to release SS line after the transmission or to leave it on the low level.
The DlnSpiMasterReadWriteSS() function allows to select the SS line, transmit data and release the SS line. For details, read Connecting Multiple Slave Devices.
In a half-duplex read mode, the slave transmits data on the MISO line and the master receives it. The MOSI line remains inactive.
To receive data in a half-duplex mode, use the DlnSpiMasterReadEx() function. This function allows to configure whether the SS line should be released after the transmission or left on the low level.
In a half-duplex write mode, the master sends data on the MOSI line and the slave receives it. The MISO line remains inactive.
To send data in a half-duplex mode, use the DlnSpiMasterWriteEx() function. This function allows to configure whether the SS line should be released after the transmission or left on the low level.
In a half-duplex mode, the master can send data to multiple slaves simultaneously. For details, read Connecting Multiple Slave Devices.
In SPI, a master can communicate with a single or multiple slaves. For applications using multiple slaves, the following configurations are possible:
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:
to select the SS line. The SS line value can include only one bit set to 0;
to transmit data to/from the slave device;
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:
to select the SS line. The SS line value can include only one bit set to 0;
to read data from the slave device and to release the SS line after transmission if required.
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=2n 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.
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:
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);
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:
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.
Sometimes slave devices need additional time to process data. In order to provide this time, DLN-series adapters can insert delays at different data transmission stages:
Delay between data frames;
Delay after slave selection;
Delay between slave selections.
All of the delays are set in nanoseconds (ns) and are configured only once. The defined delay values are the same for all SS lines of the port.
In case a slave device is not fast enough to process continuously incoming data, you can configure the DLN adapter to insert delays between each two consecutive frames. This gives the slave device additional time to process the data from the previous frame. Once enabled, the delay is inserted after each frame.
The default value of the delay between frames is 0ns. The delay value is adjusted using the DlnSpiMasterSetDelayBetweenFrames() function. The current delay between frames value can be retrieved by calling the DlnSpiMasterGetDelayBetweenFrames() function.
When an SPI slave device needs additional time for initialization, you can configure delay after slave selection (SS). When enabled, the delay is introduces after SS line assertion and before transmission of the first data bit.
The default value of the delay after slave selection is 0ns. To adjust the delay value, use the DlnSpiMasterSetDelayAfterSS() function. To retrieve the current delay value, call the DlnSpiMasterGetDelayAfterSS() function.
Delay between slave selections is inserted after one SS line release and before assertion of another SS line.
The default value of the delay between slave selections is 62ns. The delay value is adjusted using the DlnSpiMasterSetDelayBetweenSS() function, and can be retrieved using the DlnSpiMasterGetDelayBetweenSS() function.
SPI master interface allows you a wide choice of functions for transmission data. These functions differ:
by operation mode;
by frame size;
by additional attributes.
The following list includes possible functions with brief descriptions:
Provides SPI communication in a full-duplex mode (sends and receives data). The function treats data as arrays of 8-bit frames.
Provides SPI communication in a full-duplex mode (sends and receives data). The function treats data as arrays of frames up to 16 bits.
Provides SPI communication in a full-duplex mode (sends and receives data).The function treats data as arrays of 8-bit frames. When transmission completes, the function can release the SS line or leave it active.
Provides SPI communication in a full-duplex mode (sends and receives data). The function treats data as arrays of 8-bit frames. The function allows to select the specified SS line. When transmission completes, the function releases the SS line.
Provides SPI communication in a half-duplex read mode (receives data). The function treats data as an array of 8-bit frames.
Provides SPI communication in a half-duplex read mode (receives data). The function treats data as an array of 8-bit frames. When transmission completes, the function can release the SS line or leave it active.
Provides SPI communication in a half-duplex write mode (sends data). The function treats data as an array of 8-bit frames.
Provides SPI communication in a half-duplex write mode (sends data). The function treats data as an array of 8-bit frames. When transmission completes, the function can release the SS line or leave it active.
The following example shows how to transmit data over SPI bus. For brevity, this example uses default SPI configuration and does not include error detection. You can find the complete example in the “..\Program Files\Diolan\DLN\examples\c_cpp\examples\simple
” folder after DLN setup package installation.
#include "..\..\..\common\dln_generic.h" #include "..\..\..\common\dln_spi_master.h" #pragma comment(lib, "..\\..\\..\\bin\\dln.lib") int _tmain(int argc, _TCHAR* argv[]) { // Open device HDLN device; DlnOpenUsbDevice(&device); // Set SPI frequency uint32_t frequency; DlnSpiMasterSetFrequency(device, 0, 100000, &frequency); // Enable SPI master uint16_t conflict; DlnSpiMasterEnable(device, 0, &conflict); // Prepare output buffer uint8_t input[10], output[10]; for (int i = 0; i < 10; i++) output[i] = i; // Perform SPI transaction DlnSpiMasterReadWrite(device, 0, 10, output, input); // Print received data for (int i = 0; i < 10; i++) printf("%02x ", input[i]); // Disable SPI and close device DlnSpiMasterDisable(device, 0, 0); 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_spi_master.h"
The dln_spi_master.h
header file declares functions and data structures for the SPI master interface.
Line 3:#pragma comment(lib, "..\\..\\..\\bin\\dln.lib")
Use specified dln.lib
library while project linking.
Line 9:DlnOpenUsbDevice(&device);
The application 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 13:DlnSpiMasterSetFrequency(device, 0, 100000, frequency);
The application configures the frequency of the SPI master port 0. You can also configure SPI transmission mode, frame size, etc. See Configuring the SPI Master Interface for details.
Line 17:DlnSpiMasterEnable(device, 0, conflict);
The application enables the SPI master port 0. The DlnSpiMasterEnable() function assigns the corresponding pins to the SPI master module and configures them. If some other module uses a pin required for the SPI bus interface, the DlnSpiMasterEnable() function returns the DLN_RES_PIN_IN_USE
error code. The conflict
parameter receives the pin’s number.
Lines 21:for (int i = 0; i < 10; i++) output[i] = i;
The application allocates buffers for output and input data. The output buffer is filled with the sequential numbers from 0 to 9.
Line 24:DlnSpiMasterReadWrite(device, 0, 10, output, input);
The DlnSpiMasterReadWrite() function transmits the data to and from the SPI slave device. See the SPI Master Transmission Functions section for additional data transmission functions.
Line 27:for (int i = 0; i < 10; i++) printf("%02x ", input[i]);
The application prints the buffer received from the SPI slave device.
Line 30:DlnSpiMasterDisable(device, 0);
The application releases the SPI master port.
Line 31:DlnCloseHandle(device);
The application closes the handle to the DLN adapter.
The default configuration for the SPI master port is as 8-bit SPI master with CPOL=0 and CPHA=0 transmission parameters. By default, the clock is selected with a frequency of 1Mhz.
Using the SPI master functions allows you to change and check the current SPI master configuration, to control data transmission.
The SPI master functions include the following:
General port information:
Retrieves the number of SPI master ports available in the DLN adapter.
Assigns the selected port to the SPI master module.
Releases the selected SPI master port.
Retrieves whether the selected port is assigned to the SPI master module.
Configuration functions:
Configures the clock frequency for the selected SPI master port.
Retrieves the clock frequency configuration for the SPI master port.
Configures the size of a single data frame for the selected SPI master port.
Retrieves the data frame configuration for the selected SPI master port.
Configures the transmission mode based on CPOL and CPHA values.
Retrieves the transmission mode configuration for the selected SPI master port.
Configures the CPOL value for the selected SPI master port.
Retrieves the CPOL value for the selected SPI master port.
Configures the CPHA value for the selected SPI master port.
Retrieves the CPHA value for the selected SPI master port.
Retrieves the supported transmission modes for the selected SPI master port.
Retrieves the supported CPOL values for the selected SPI master port.
Retrieves the supported CPHA values for the selected SPI master port.
Slave selection functions:
Retrieves the available number of SS lines for the selected SPI master port.
Selects a Slave Select (SS) line.
Retrieves the selected SS line.
Activates the selected SS line.
Disables the selected SS line.
Retrieves whether the selected SS line is activated.
Activates several selected SS lines.
Disables several selected SS lines.
Retrieves whether several selected SS lines are activated.
Releases the selected SS line.
Activates releasing SS line between data frames exchanged with a single slave device.
Disables releasing SS line between data frames exchanged with a single slave device.
Retrieves whether releasing SS line between data frames is activated.
Transmission functions:
Provides SPI communication in a full-duplex mode with arrays of 8-bit frames.
Provides SPI communication in a full-duplex mode with arrays of frames up to 16 bits.
Provides SPI communication in a full-duplex mode with arrays of 8-bit frames; can release the SS line after transmission.
Provides SPI communication in a full-duplex mode with arrays of 8-bit frames; releases the SS line after transmission.
Provides SPI communication in a half-duplex read mode with arrays of 8-bit frames.
Provides SPI communication in a half-duplex read mode with arrays of 8-bit frames; can release the SS line after transmission.
Provides SPI communication in a half-duplex write mode with arrays of 8-bit frames.
Provides SPI communication in a half-duplex write mode with arrays of 8-bit frames; can release the SS line after transmission.
Delay functions:
Configures a delay between data frames exchanged with a single slave device.
Retrieves current delay between data frames exchanged with a single slave device.
Configures a delay between activating SS line and the first data frame.
Retrieves current delay between activating SS line and the first data frame.
Configures a minimum delay between releasing one SS line and activating another SS line.
Retrieves current delay between releasing one SS line and activating another SS line.
The dln_spi_master.h
file declares the SPI Master Interface functions.
The DlnSpiMasterGetPortCount()
function retrieves the total number of SPI master ports available in your DLN-series adapter.
The DlnSpiMasterEnable()
function activates the selected SPI master port on your DLN-series adapter.
The DlnSpiMasterDisable()
function releases the selected SPI master port on your DLN-series adapter.
The DlnSpiMasterIsEnabled()
function retrieves whether the specified SPI master port is activated.
The DlnSpiMasterSetFrequency()
function sets the clock frequency on the SCK line, used to synchronize data transmission between master and slave devices.
The DlnSpiMasterGetFrequency()
function retrieves the current setting for SPI clock frequency.
The DlnSpiMasterSetFrameSize()
function sets the size of a single SPI data frame.
The DlnSpiMasterGetFrameSize()
function retrieves the current size setting for SPI data frame.
The DlnSpiMasterSetMode()
function sets SPI transmission parameters (CPOL and CPHA).
The DlnSpiMasterGetMode()
function retrieves current configuration of the selected SPI master port.
The DlnSpiMasterSetCpol()
function sets the clock polarity value.
The DlnSpiMasterGetCpol()
function retrieves the current value of clock polarity (CPOL).
The DlnSpiMasterSetCpha()
function allows to set clock phase (CPHA) value.
The DlnSpiMasterGetCpha()
function retrieves the current value of clock phase (CPHA).
The DlnSpiMasterGetSupportedModes()
function retrieves all supported SPI master modes (CPOL and CPHA values). For more information, read Clock Phase and Polarity.
The DlnSpiMasterGetSupportedCpolValues()
function retrieves supported CPOL values.
The DlnSpiMasterGetSupportedCphaValues()
function retrieves the available CPHA values.
The DlnSpiMasterGetSSCount()
function returns the available number of SS lines.
The DlnSpiMasterSetSS()
function selects a Slave Select (SS) line.
The DlnSpiMasterGetSS()
function retrieves current Slave Select (SS) line.
The DlnSpiMasterSSEnable()
function enables the specified SS line.
The DlnSpiMasterSSDisable()
function disables the specified SS line.
The DlnSpiMasterSSIsEnabled()
function enables the specified SS line.
The DlnSpiMasterSSMultiEnable()
function enables the specified SS lines.
The DlnSpiMasterSSMultiDisable()
function enables the specified SS lines.
The DlnSpiMasterSSMultiIsEnabled()
function enables the specified SS lines.
The DlnSpiMasterReleaseSS()
function releases SS lines.
The DlnSpiMasterSSBetweenFramesEnable()
function enables release of an SS line between data frames exchanged with a single slave device.
The DlnSpiMasterSSBetweenFramesDisable()
function disables release of an SS line between data frames exchanged with a single slave device.
The DlnSpiMasterSSBetweenFramesIsEnabled()
function checks whether the DLN-series adapter releases SS line between successive SPI frames transmission.
The DlnSpiMasterReadWrite()
function sends and receives data via SPI bus. The received and sent data are arrays of 1-byte elements. This function is suited to transmit data frames of 8 bits or less. In case you set a frame size more than 8 bits, it is advised to use the DlnSpiMasterReadWrite16() function.
The DlnSpiMasterReadWrite16()
function sends and receives 2-byte frames via SPI bus.
The DlnSpiMasterReadWriteSS()
function selects the specified SS line, transmits data via SPI bus and releases the SS line.
The DlnSpiMasterReadWriteEx()
function sends and receives data via SPI bus. The data is transmitted as an array of 1-byte elements. In this function you can use additional attributes to configure the SS line state after data transmission.
The DlnSpiMasterRead()
function receives data via SPI bus. The received data is an array of 1-byte elements.
The DlnSpiMasterReadEx()
function receives data via SPI bus. The received data is an array of 1-byte elements. In this function you can use additional attributes to configure the SS line state after data transmission.
The DlnSpiMasterWrite()
function sends data via SPI bus. The data is sent as an array of 1-byte elements.
The DlnSpiMasterWriteEx()
function sends data via SPI bus. The data is sent as an array of 1-byte elements. By using this function you can use additional attributes.
The DlnSpiMasterSetDelayBetweenFrames()
function sets a delay between data frames exchanged with a single slave device. For more information, read SPI Delays.
The DlnSpiMasterGetDelayBetweenFrames()
function retrieves current setting for delay between data frames exchanged with a single slave device.
The DlnSpiMasterSetDelayAfterSS()
function sets a delay duration between assertion of an SS line and first data frame. For more information, read SPI Delays.
The DlnSpiMasterGetDelayAfterSS()
function retrieves the current setting for minimum delay between assertion of an SS line and the first data frame.
The DlnSpiMasterSetDelayBetweenSS()
function sets a minimum delay between release of an SS line and assertion of another SS line. For more information, read SPI Delays.
The DlnSpiMasterGetDelayBetweenSS()
function retrieves the current setting for minimum delay after one SS line is released and before another SS line is asserted.
Some DLN-series adapters support the SPI Slave Interface.
To configure the slave for the communication, follow these steps:
Configure SS idle timeout. When you enable the SPI slave, the SS line may be busy. The DLN adapter waits until the SS line drives high. If the SS line is not released during the SS idle timeout, the SPI slave cannot be enabled. Read SS Idle Timeout.
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.
Configure loading data to the reply buffer. The reply mode and reply type parameters can prevent from losing data if the frame size, configured by you for the SPI slave, does not correspond the frame size set on the SPI master. Read SPI Slave Reply Buffer.
If needed, configure events. DLN adapters provide event-driven interface for SPI slave devices. Read SPI Slave Events.
When you try to enable the SPI slave module, the SS line can appear busy. To prevent transmitting incorrect data, the DLN adapter idles until the SS line is released (drives high). Only then, the SPI slave can be enabled.
To limit the idle time, you can specify the idle timeout value in milliseconds (ms) by calling the DlnSpiSlaveSetSSIdleTimeout() function. The default value is 100ms. The idle timeout can be from 1ms to 1000ms. If during the specified idle timeout the SS line was not released, the DlnSpiSlaveEnable() function returns the DLN_RES_SPI_SLAVE_SS_IDLE_TIMEOUT
error.
For details about idle event timeout, read DLN_SPI_SLAVE_EVENT_IDLE Events.
When the master initiates transmission, the DLN adapter-slave fills the reply buffer with data that should be sent to the master. To fill the reply buffer, you can use the following functions: DlnSpiSlaveLoadReply() or DlnSpiSlaveEnqueueReply(). The DlnSpiSlaveLoadReply() function clears the buffer and makes the current reply the first in the queue. In contrast, the DlnSpiSlaveEnqueueReply() function puts the current reply to the end of the queue.
Transmitted data is limited to the number of frames received by the master. The sizes of slave buffer (reply buffer) and master buffer (received buffer) may differ.
If the reply buffer size exceeds the received buffer size, the last bytes of the reply buffer can be lost or sent with the following transmission. It depends on the reply mode you configure. For more information, read Reply Modes.
If the reply buffer size is less than the received buffer size, the last bytes can be filled by zeroes or by repeated reply bytes. It depends on the shortage action you configure. For details, read Reply Shortage Actions.
If the reply buffer size exceeds the size of the buffer received by the master, the following options are possible:
If the last bytes of the reply are not weighty, they can be rejected. In this case, the master receives the bytes from the reply buffer until the SS line rises. The last bytes of the reply buffer are lost. This mode is called DLN_SPI_SLAVE_REPLY_MODE_SS_BASED
.
If you do not want to lose any data, the last buffers can be added to the queue. In this case, the master receives the bytes from the reply buffer until the SS line rises. The last bytes of the reply buffer are not lost, they are added to the queue and the master receives them with the next transmission. This mode is called DLN_SPI_SLAVE_REPLY_MODE_COUNT_BASED
.
You have two loaded replies: ABCD
and EF12
. The master initiates two transmissions of 3 words in each. From the slave, the master receives the following:
In the DLN_SPI_SLAVE_REPLY_MODE_SS_BASED
mode, the master receives ABC
and EF1
. The last bytes of every reply are lost.
In the DLN_SPI_SLAVE_REPLY_MODE_COUNT_BASED
mode, the master receives ABC
and DEF
. The last bytes of the second reply is queued for the following transmissions.
To configure the reply mode, use the DlnSpiSlaveSetReplyMode() function. The DlnSpiSlaveGetSupportedReplyModes() function retrieves all supported reply modes.
If the reply buffer size is less than the size of the buffer received by the master, the missed bytes can be filled by zeroes (the DLN_SPI_SLAVE_REPLY_SHORTAGE_SEND_ZEROES
reply type) or by repeating the reply bytes (the DLN_SPI_SLAVE_REPLY_SHORTAGE_REUSE
reply type).
You have a loaded reply: ABCD
. The master initiates a transmission of 6 words. From the slave, the master receives the following:
If the DLN_SPI_SLAVE_REPLY_SHORTAGE_SEND_ZEROES
reply type is set, the master receives ABCD00
. The last bytes are filled with zeroes.
If the DLN_SPI_SLAVE_REPLY_SHORTAGE_REUSE
reply type is set, the master receives ABCDAB
. The last bytes are filled by repeating the first bytes of the reply.
DLN adapters-slaves can be configured to send events. The events are generated when the slave meets the certain predefined conditions.
DLN adapters-slaves support the following events:
Event Type | Description |
| A DLN adapter does not generate any events. |
| A DLN adapter generates events when the level on the SS line rises. For details, read DLN_SPI_SLAVE_EVENT_SS_RISE Events. |
| A DLN adapter generates events when the buffer is full. For details, read DLN_SPI_SLAVE_EVENT_BUFFER_FULL Events. |
| A DLN adapter generates events when the slave idles for the configured time. For details, read DLN_SPI_SLAVE_EVENT_IDLE Events. |
When an event occurs, your application is notified (see the Notifications section). Call the DlnGetMessage() function to obtain the event details. The DLN_SPI_SLAVE_DATA_RECEIVED_EV
structure describes this information.
By default, event generation is disabled (DLN_SPI_SLAVE_EVENT_NONE
).
A DLN adapter generates the DLN_SPI_SLAVE_EVENT_SS_RISE
events each time the level on the SS line rises.
When the transmission from/to the SPI master completes, the master rises the level on the SS line. At this moment, a DLN adapter-slave generates the DLN_SPI_SLAVE_EVENT_SS_RISE
event. After receiving this event, your application can perform certain actions, for example, show received data or start processing them.
The eventCount
field of the first event is set to zero. For every new DLN_SPI_SLAVE_EVENT_SS_RISE
event, the eventCount
field increments. When you reset the slave or change its configuration, the eventCount
filed is reset to zero.
Use the DlnSpiSlaveEnableSSRiseEvent() function to enable generating these events. To disable this event, use the DlnSpiSlaveDisableSSRiseEvent() function. The DlnSpiSlaveIsSSRiseEventEnabled() function allows to check whether this event is enabled.
A DLN adapter generates the DLN_SPI_SLAVE_EVENT_BUFFER_FULL
events each time the buffer becomes full.
You can configure the buffer size by calling the DlnSpiSlaveSetEventSize() function. The supported values are from 1 to 256 bytes. By default, the size parameter is set to 256 bytes. To check the current value, use the DlnSpiSlaveGetEventSize() function.
During the transmission from the SPI master, if the buffer is overfilled, a DLN adapter-slave generates the DLN_SPI_SLAVE_EVENT_BUFFER_FULL
event.
The eventCount
field of the first event is set to zero. For every new DLN_SPI_SLAVE_EVENT_SS_RISE
event, the eventCount
field increments. When you reset the slave or change its configuration, the eventCount
filed is reset to zero.
Use the DlnSpiSlaveEnableEvent() function to enable generating these events. To disable this event, use the DlnSpiSlaveDisableEvent() function. The DlnSpiSlaveIsEventEnabled() function allows to check whether this event is enabled.
The DLN_SPI_SLAVE_EVENT_BUFFER_FULL
event does not conflict with other events.
A DLN adapter generates the DLN_SPI_SLAVE_EVENT_IDLE
events each time the SS line stays raised for a certain time.
When the transmission from/to the SPI master completes, the master rises the level on the SS line. If the level stays high for the time set in the timeout parameter, a DLN adapter-slave generates the DLN_SPI_SLAVE_EVENT_IDLE
event. If the SS line stays in the high level less than the required idle timeout, the event does not occur.
To configure the timeout parameter, use the DlnSpiSlaveSetIdleEventTimeout() function. The DlnSpiSlaveSetIdleEventTimeout() function allows to check the current value of this parameter.
Use the DlnSpiSlaveEnableIdleEvent() function to enable generating DLN_SPI_SLAVE_EVENT_IDLE
events. To disable this event, use the DlnSpiSlaveDisableIdleEvent() function. The DlnSpiSlaveIsIdleEventEnabled() function allows to check whether this event is enabled.
The default configuration for the SPI slave port is as 8-bit SPI slave with CPOL=0 and CPHA=0 transmission parameters. By default, no events are generated.
Using the SPI slave functions allows you to change and check the current SPI slave configuration, to control data transmission.
The SPI slave functions include the following:
General port information:
Retrieves the number of SPI slave ports available in the DLN adapter.
Assigns the selected port to the SPI slave module.
Releases the selected SPI slave port.
Retrieves whether the selected port is assigned to the SPI slave module.
Configuration functions:
Specifies idle timeout for releasing the SS line.
Retrieves the idle timeout setting.
Specifies the data frame size for the selected SPI slave port.
Retrieves the current frame size for the selected SPI slave port.
Retrieves the supported frame sizes.
Specifies transmission parameters (CPOL and CPHA) for the selected SPI slave port.
Retrieves the current transmission parameters (CPOL and CPHA) for the selected SPI slave port.
Retrieves the supported transmission parameters (CPOL and CPHA).
Specifies CPHA value for the selected SPI slave port.
Retrieves the current CPHA value for the selected SPI slave port.
Retrieves the supported CPHA values.
Specifies CPOL value for the selected SPI slave port.
Retrieves the current CPOL value for the selected SPI slave port.
Retrieves the supported CPOL values.
Reply functions:
Clears the buffer and makes the current reply the first in the queue.
Puts the current reply to the end of the queue.
Specifies actions if the reply buffer size exceeds the size of the buffer received by the master.
Retrieves the current reply configuration.
Retrieves the supported reply modes.
Specifies actions if the reply buffer size is less than the size of the buffer received by the master.
Retrieves the current for reply shortage action settings.
Retrieves the supported reply shortage actions.
Event configuration:
Enables generating events when the level on the SS line rises.
Disables generating events when the level on the SS line rises.
Retrieves the current configuration for generating events when the level on the SS line rises.
Enables generating events when the buffer is full.
Disables generating events when the buffer is full.
Retrieves the current configuration for generating events when the buffer is full.
Specifies the buffer size.
Retrieves the current buffer size.
Enables generating events when the slave idles for the configured time.
Disables generating events when the slave idles for the configured time.
Retrieves the current configuration for generating events when the slave idles for the configured time.
Specifies the timeout value.
Retrieves the current timeout value.
Retrieves the minimum timeout value.
Retrieves the maximum timeout value.
The dln_spi_slave.h
file declares the SPI Salve Interface functions.
The DlnSpiSlaveGetPortCount()
function retrieves the total number of SPI slave ports available at your DLN-series adapter.
The DlnSpiSlaveEnable()
function activates the specified SPI slave port at your DLN-series adapter.
The DlnSpiSlaveDisable()
function deactivates the specified SPI slave port on your DLN adapter.
The DlnSpiSlaveIsEnabled()
function retrieves information whether the specified SPI slave port is active or not.
The DlnSpiSlaveSetSSIdleTimeout()
function sets SS idle timeout. For details, read SS Idle Timeout.
The DlnSpiSlaveGetSSIdleTimeout()
function retrieves the current value of SS idle timeout.
The DlnSpiSlaveSetFrameSize()
function sets the size of a single SPI data frame.
The DlnSpiSlaveGetFrameSize()
function retrieves the current size setting for SPI data frames.
The DlnSpiSlaveGetSupportedFrameSizes()
function returns all supported frame size values.
The DlnSpiSlaveSetMode()
function sets SPI transmission parameters (CPOL and CPHA). For more information, read Clock Phase and Polarity.
The DlnSpiSlaveGetMode()
function retrieves the current transmission parameters (CPOL and CPHA) for the specified SPI slave port. For details, read Clock Phase and Polarity.
The DlnSpiSlaveGetSupportedModes()
function retrieves all supported SPI slave modes.
The DlnSpiSlaveSetCpha()
function allows to set the clock phase (CPHA) value.
The DlnSpiSlaveGetCpha()
function retrieves the current value of clock phase (CPHA).
The DlnSpiSlaveGetSupportedCphaValues()
function retrieves all supported CPHA (clock phase) values.
The DlnSpiSlaveSetCpol()
function allows to set the clock polarity (CPOL) value.
The DlnSpiSlaveGetCpol()
function retrieves the current value of clock polarity (CPOL).
The DlnSpiSlaveGetSupportedCpolValues()
function retrieves all supported CPOL (clock polarity) values.
The DlnSpiSlaveLoadReply()
function loads data (loads a number of bytes to reply buffer) to be transmitted to an SPI-master device. This function clears the buffer and makes the current reply the first in the queue.
The DlnSpiSlaveEnqueueReply()
function adds a buffer to queue.
The DlnSpiSlaveSetReplyMode()
function sets SPI slave reply mode.
The DlnSpiSlaveGetReplyMode()
function retrieves the current SPI slave reply mode.
The DlnSpiSlaveGetSupportedReplyModes()
function retrieves the supported SPI slave reply modes.
The DlnSpiSlaveSetReplyShortageAction()
function sets the reply shortage action value. When the master sends a data block that is larger than the loaded reply, this function specifies how to fill empty bytes (repeat the reply bytes or send zeroes).
The DlnSpiSlaveGetReplyShortageAction()
functions retrieves the current value of reply shortage action.
The DlnSpiSlaveGetSupportedShortageActions()
function retrieves supported shortage action values.
The DlnSpiSlaveEnableSSRiseEvent()
function activates event on SS rising edge.
The DlnSpiSlaveDisableSSRiseEvent()
function deactivates SS rise events.
The DlnSpiSlaveIsSSRiseEventEnabled()
function retrieves information whether the SS rise events are active or not.
The DlnSpiSlaveEnableEvent()
function activates SPI slave buffer full event.
The DlnSpiSlaveDisableEvent()
function deactivates SPI slave buffer full event.
The DlnSpiSlaveIsEventEnabled()
function retrieves information whether the SPI slave events are active or not.
The DlnSpiSlaveSetEventSize()
function sets the event buffer size.
The DlnSpiSlaveGetEventSize()
function retrieves value of current event buffer size.
The DlnSpiSlaveEnableIdleEvent()
function activates the SPI slave idle event.
The DlnSpiSlaveDisableIdleEvent()
function deactivates the SPI slave idle event.
The DlnSpiSlaveIsIdleEventEnabled()
function activates the SPI slave idle event.
The DlnSpiSlaveSetIdleEventTimeout()
function sets idle event timeout.
The DlnSpiSlaveGetIdleEventTimeout()
function retrieves the current value of idle event timeout.
The DlnSpiSlaveGetMinIdleEventTimeout()
function retrieves the minimum value of idle event timeout.
The DlnSpiSlaveGetMaxIdleEventTimeout()
function retrieves the maximum value of idle event timeout.