SPI-QPID Protocol

The SPI-QPID protocol supports sending and receiving data over a Serial Peripheral Interface (SPI) connection using the Quanser QPID data acquisition card.

Syntax

spi-qpid://hostname:port?option=value,... % Use SPI channel "port" with specified options
    

Description

The SPI-QPID protocol supports sending and receiving data over an SPI connection. It is identified by using spi-qpid as the protocol name in a URI.

The hostname in the URI is ignored, if specified. The port is an unsigned integer indicating which SPI port to use. Port 0 is the first SPI port in the system.

The Quanser QPID card supports one SPI port, which is an SPI master. It does not support SPI slave functionality. The SPI port is identified as port 0.

The SPI protocol uses a master-slave paradigm. It is a synchronous protocol in which the master supplies the clock, often dubbed SCK, and the slave uses that clock. The master transmits data over the MOSI (master-out, slave-in) line at the same time as it receives data from the slave over the MISO (master-in, slave-out) line. Multiple slaves may be connected and are selected by the master using slave-select (SS) lines. However only one slave may transmit over the MISO line at a time, and each slave must tri-state its MISO line when its slave-select line is deasserted.

There are no read or write lines because the SPI protocol always sends and receives data at the same time over its full duplex connection. Whenever data is sent, the same amount of data is always received.

For example, the following sequence of operations is required to communicate over an SPI connection:

• send N bytes
• flush
• receive N bytes

Sending N bytes writes those bytes to the stream's send buffer. It may not flush the bytes to the underlying SPI communication channel. Hence, the flush is required to ensure that all the bytes were actually written to the SPI port.

When the N bytes are written to the SPI port, there will be N bytes that are automatically received at the same time and stored in the stream's receive buffer, even before the receive operation is performed!

Thus, when the receive operation is performed the data is already available in the receive buffer and the receive operation merely removes it from the buffer. No actual communication takes place during the receive operation.

A number of restrictions arise from this mode of operation. Firstly, data must always be sent before data can be received. It is not possible with the SPI protocol to simply receive data without sending data first. The Basic Stream blocks recognize protocols such as SPI that operate in this manner and handle the stream accordingly. Hence, the Basic Stream blocks may be used with the SPI protocol as may persistent streams.

The baud rate used by the SPI master is determined by the baud option of the URI. A typical baud rate is 1MHz. The Quanser QPID is theoretically capable of baud rates from 625 kHz to 80 MHz, although phase delays and signal distortion due to cabling can become an issue at the highest baud rates.

The number of bits transferred during each send and receive operation is programmable and is configured using the word option of the URI. Typical word lengths are 8 bits or 16 bits. The Quanser QPID card supports word lengths of 1 to 32 bits.

Data transmitted by QUARC over an SPI connection is not packed bit-wise. For example, if the word length is 12 bits then QUARC's SPI protocols take 16 bits at a time from the send buffer, transmits 12 bits and discards the remaining 4 bits. Hence, two 12-bit quantities are stored in 32 bits (4 bytes), not 24 bits (3 bytes).

This scheme makes it much easier to send and receive data over an SPI connection because no bit shifting and packing is required to prepare data to be sent, nor to to extract data received. Instead, standard data types may be used, even for word lengths other than 8, 16 or 32 bits.

For example, to send a series of 12-bit words, simply send a vector of 16-bit values (short integers) using the standard Stream API functions, such as stream_send_short_array. Twelve bits out of every 16-bit integer will be sent and 4 bits in each 16-bit integer will be left unused.

To receive a series of 12-bit words, simply receive a vector of 16-bit values (short integers) using the standard Stream API functions, such as stream_receive_short_array. The 12-bit quantities received will be sign-extended to 16 bits automatically.

The SPI-QPID protocol does not specify whether the most-significant bit (MSb) or least-significant bit (LSb) is transmitted or received first during an SPI transfer. Hence, the SPI-QPID protocol allow this bit order to be configured. Use the lsb option in the URI to program the bit order of the SPI transfer. Set it to true to send and receive the LSb first. Omit the option or set it to false to send and receive the MSb first.

The polarity of the SCK clock is also generally configurable as either active-high or active-low and the phase of the clock may also typically be programmed. The phase determines the clock edge on which data is placed on the MISO or MOSI line, and the clock edge on which data is sampled. The following figure depicts the different configurations of clock polarity and phase.

The clock polarity is specified in the URI using the polarity option. The polarity is active-high by default. Set the polarity to one to make the clock active-low. Set it to zero or omit the option for an active-high SCK.

The clock phase is determined by the phase option in the URI. If the phase is zero (the default), then data is supplied by the SPI master on the MOSI line on the trailing/even edge of each clock pulse. Typically, an SPI master samples data from the MISO line on the leading/odd edge of the clock.

Slave devices sample the MOSI line on the leading/odd edge. To ensure that data is available on the first clock edge, the master supplies data on the MOSI line before the first clock edge.

If the phase is one then data is supplied by the SPI master on the MOSI line on the leading/odd edge of each clock pulse. Data is typically sampled by an SPI master from the MISO line on the trailing/even edge of the clock.

Slave devices sample the MOSI line on the trailing/even edge.

The operation of the slave-select (SS) line for each slave varies. Most devices require that the SS line be asserted during each word transferred over an SPI connection. In this sense the SS line operates as a chip select signal.

However, some devices treat the SS line more as a frame signal. In this case, the SS line remains asserted during a series of word transfers and indicates the size of an entire frame or packet of data.

The SPI-QPID protocol supports two options for differentiating between these two uses of the SS line.

The slave option is employed when the SS line should be asserted for each word transferred. Its value is an integer ranging from 52 to 56 inclusive, and indicates which digital I/O line to assert during SPI transfers for this URI. Channel 56 is the SS pin on the Quanser QPID terminal board.

The frame option is used when the SS line should be asserted for an entire frame, rather than for each word transferred. Similar to the slave option, its value is an integer ranging from 0 to 56 indicating which digital I/O line should be asserted as a slave-select during SPI transfers for this URI. The size of a frame is determined by the amount of data sent at one time by the Stream API functions. The amount of data is determined by the Stream API functions or blocks invoked and the size of the stream's send buffer.

While this sounds complicated, it is actually quite easy. For example, if the following sequence of operations is performed:

• send N words
• flush
• receive N words

then the frame will consist of N words, presuming the stream's send buffer is large enough to contain all N words. Thus, the SS line will be asserted at the beginning of the entire transfer and not deasserted until all N words have been transferred.

Limitations

Performance

Signal integrity issues can affect the maximum baud rate achievable. Check the signals on an oscilloscope if communications is failing at high rates (e.g. 10 MHz or higher). For example, at high rates the capacitance of the lines can slow down the signals and limit the baud rate attainable.

Also note that the baud rate refers to the number of bits transferred per second and not the number of bytes. The number of bytes per second is usually less than 1/8th of the baud rate due to the overhead (albeit small) of the protocol. The word length also affects the performance. Longer word lengths generally yield better performance.

QUARC Target Manager

The SPI protocol cannot be used for communicating with the target (via a target URI) because the SPI protocol does not allow multiple connections on the same port. Hence, qc_set_default_model_uri cannot be used to set a default SPI protocol for models. Instead, the model URI must be specified explicitly in the Code Generation/Interface/MEX file arguments option of the Configuration Parameters of the model as well as the target URI.

Multiple client connections

The SPI protocol will only accept a single client connection at a time on a given port. It does not support time-division multiplexing of multiple client connections over a single SPI port because doing so would require adding a header to the information packets sent over the port. QUARC communication protocols never add extra information to the data sent over the communication channel in order to allow QUARC to communicate with user applications, sensors and other devices which would not support QUARC-specific data packets.

Options

mode

The mode option is supported by the SPI-QPID protocol but must be set to "master". The slave mode is not supported by the hardware.

memsize

The memsize option determines the size of the buffer (in bytes) used for SPI transfers. This size determines the maximum number of bytes that can be transferred in one operation. It is not the same as the Stream API's send and receive buffers but is used in interfacing with kernel drivers that implement the SPI protocol. The SPI-QPID protocol uses a default buffer size of 8000 bytes.

baud

The baud option specifies the frequency of the SPI clock (SCK) in Hertz.

The baud rate determines the number of bits transferred per second, not the number of bytes. The default baud rate for the SPI-QPID protocol is 1 MHz. Baud rates may range from 625 kHz to 80 MHz. The actual baud rate obtained will be 80 MHz/N, where N=1..128.

word

This option indicates the word length used for SPI transfers. The word length is the number of bits involved in a single SPI transfer. It is typically 8 or 16 bits, but some devices require a different number of bits. For example, some analog-to-digital converters use 24-bit word lengths in which eight bits contain a register address and 16 bits contain the data to store in the converter's register.

The range of word lengths supported by the Quanser QPID card is between 1 and 32 bits inclusive.

lsb

This option determines whether the most-significant bit (MSb) or least-significant bit (LSb) is transmitted first. If this option is omitted then the MSb is transmitted and received first because that is typical of most devices.

Set this option to "true" or "1" to transmit (and receive) the LSb first. Set it to "false" or "0", or omit the option altogether, to transmit and receive the MSb first.

polarity

The polarity (CPOL) of the SPI clock (SCK) is configured using this option. The default polarity is active-high. Omit this option, or set it to "false" or "0" to program the clock polarity as active-high. Set the option to "true" or "1" for active-low clock polarity.

phase

The phase (CPHA) of the SPI clock (SCK) is programmed using this option. The default phase is trailing-edge phase. Omit this option, or set it to "false" or "0" to configure trailing-edge phase, in which data on the MOSI line is updated on the trailing edge of the SPI clock. For an active high SPI clock, the "trailing edge" is the falling edge of the clock. For an active low SPI clock, the "trailing edge" is the rising edge of the clock.

Set it to "true" or "1" for leading-edge phase, in which data on the MOSI line is updated on the leading edge of the SPI clock. For an active high SPI clock, the "leading edge" is the rising edge of the clock. For an active low SPI clock, the "leading edge" is the falling edge of the clock.

slave

The slave option determines the slave-select (SS) line used to select the SPI slave during each SPI transfer. It is an integer value ranging from 52 to 56 identifying the digital I/O line to be used as the slave-select line. A value of 56 indicates the SS line on the Quanser QPID terminal board. If the slave select line should delineate an entire frame of data rather than a single transfer, use the the frame option instead. If no SS line is required then simply omit the option. The SPI-QPID protocol allows one digital I/O line to be used as a slave-select and another digital I/O to be used as a frame signal at the same time.

frame

The frame option determines the slave-select (SS) line used to select the SPI slave during the transfer of entire frame. It is an integer value ranging from 0 to 56 identifying the digital I/O line to be used as the slave-select/frame signal. A value of 56 refers to the SS line on the Quanser QPID terminal board. If the slave-select line should be asserted for each word within a frame then use the slave option instead. If no SS line is required as a frame signal then simply omit the option. The SPI-QPID protocol allows one digital I/O line to be used as a slave-select and another digital I/O to be used as a frame signal at the same time.

middle

The middle option determines when the SPI-QPID protocol samples the data on the MISO line. If this option is omitted or set to false then the MISO line is sampled one full clock period after the corresponding bit is placed on the MOSI line. For example, if the master supplies bit 3 on the MOSI line on the trailing/even edge of the clock, then it will sample bit 3 from the slave from the MISO line on the next trailing/even edge of the clock. This behaviour differs from most SPI devices, but allows more time for data to arrive from the slave. It generally does not affect communications in any way except by allowing faster baud rates to be achieved.

To restore the typical SPI behaviour by sampling the MISO line on the opposite clock edge, set this option to true. In this case the SPI-QPID protocol samples the MISO line in the "middle" of the clock period. For instance, if the master supplies bit 3 on the MISO line on the trailing/even edge of the clock then it will sample bit 3 from the slave on the next leading/odd edge of the clock, as shown in the figure above.

Driver

The driver supporting the SPI-QPID protocol is called qrt_spi-qpid.

Targets

See Also

• Communications
• QUARC Communications Protocols
• Communications Using the C Language

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.