GRiSP SPI API.

Serial Peripheral Interface (SPI) is a synchronous serial communication protocol, where a single controller device can control many responder devices. With this API, the GRiSP board acts as a controller and any connected device is a responder.

SPI has four lines: clock, MOSI, MISO and chip select. MOSI is the data line from the controller device to the responder devices. MISO is the data line from the responder devices to the controller device. The controller device is regulating the communication speed and synchronization by controlling the chip select and clock lines.

Chip Select

By default, if the bus aliases spi1 or spi2 is used with open/1 the chip select pin is automatically configured to the default SPI slot chip select pin. When using open/2 the chip select pin can be any GPIO pin (grisp_gpio).

Clock

The clock line in SPI is a digital I/O line that pulses at a certain frequency. The default SPI clock frequency in GRiSP is 0.1 MHz.

The clock line polarity and phase should be configured by setting the mandatory clock mode option (clock/0) for each message. A polarity of low means the clock line is idling at 0 and a polarity of high means the clock line is idling at 1. The phase denotes at which edge of the clock pulse the actual protocol values should be written and read. A phase of leading means that the controller and responder devices should read or write values as the pulse starts. A phase of trailing means the devices should read or write values as the current pulse ends.

The settings for the clock line is specific per device and needs to be consulted from the official specification of the device.

Request & Response

From the controller point of view, requests are always written to the MOSI line and response data is always read from the MISO line.

Because SPI is synchronous, for every request byte sent a response byte is always received. Many responder devices respond silently with zeroes until a request is fully received, then send their response while ignoring the rest of the bytes being received. Other devices can start sending data already before the controller has finished sending a request, and even reply with data while the controller is writing its own data.

This module provides two message formats. One format (message_raw/0) returns the full response, all byaes received from the responder device including ones sent during the initial request.

The other format (message_simple/0) automatically pads the request so that response bytes can be received, and strips the response of an initial number of bytes. This makes it simpler to communicate with responder devices that wait for a fully received request before replying.