BasicPI Hat’s uses SPI in a full network with up to 8 Hat’s per Raspberry PI. Communication with a STM32 will clock at ca 15Mhz (Set on Raspberry PI). The protocol uses GPIO pin’s as chip select for critical messages, but will otherwise rely on each device to filter out it’s own messages on MOSI. This allows Raspberry PI to send on MOSI independent of what device that is sending on MISO.

This is possible since all information about sender and receiver is in the message header in the form of a hat/stream-id and MOSI can be filtered in software. The SPI Message format is illustrated below:

Chip Select on MISO is always done between two messages from a Hat. Raspberry PI will either detect a pad character meaning the Hat has nothing to send or wait for a message to complete if the device uses it’s time slot. Each active Hat have a 1ms time slot before Raspberry PI switch to another Hat. The device with Chip Select active will send a status message and either continue with messages in the queue or send pad’s if no messages is waiting.

The way this should work is that messages on MOSI are sent in the same sequence as they are inserted into the queue. Messages on MISO will be received as soon as the Hat receive chip select. ME will load balance chip select so that Hat’s with large MISO queues receive more sending time than Hat’s with empty Queues.

Layer 2 OSI Protocol

easyIPC implement a pragmatic Version of the OSI model and Smart SPI is a layer 2 protocol where the objective is to maintain a point to point link between Raspberry PI and it’s Hat’s. The protocols only responsibility is to maintain this link and transfer messages on a “guaranteed service” concept. “Guaranteed Service” means we will either transfer the message or report back that we are unable to.

Smart SPI have no knowledge about the messages it transport. The user messages have a stream ID larger than 0 that higher layers will use to identify both end-points. The nature of easyIPC means that only the end-points need to know the message content as layer 2&3 are part of the transport mechanism. This principle of pure transport layers are very important as it allow us to send new data from device to device without changes to the system.

Protocol Description

Smart SPI is a Layer 1 – 2 protocol using SPI to establish a direct communication link between Raspberry PI and Hat’s. SPI itself is a bit oriented full duplex protocol where the master control the speed by ticking a CLK signal. For every cycle on the clock we transfer a bit on both MOSI and MISO. Using SPI in 1:1 we only need GND, MOSI, MISO and CLK, but a CS (Chip Select) is needed for communication with several devices.

In a classic SPI design we would set a Chip Select pin and communicate with that device, select the next and communicate with that in a sequence.

All easyIPC aware Raspberry PI Hat’s use a technique called “Smart SPI” that implement several tricks to optimize SPI usage.

• The stream on MOSI include target address allowing 8 Hat’s to read the message and filter out the messages they want to see. This allows Linux to send continuous on SPI without doing a bit-bang on CS pins that would slow down sending.
• The message stream also include a Chip Select Message in software. As this is read by all Hat’s only the Hat selected will activate MISO. This allows the RPI driver to select MISO independent from MOSI stream.
• MISO Send algorithm will enable Hat’s in sequence and automatically switch to the next after 1ms or as soon as the Hat report 0 messages. Bit padding is supported on both MOSI and MISO to complete a message.

Start-Up Procedure

The Start-Up procedure consist of a sequence of operations that must be executed as the system is powering on. The Hat’s will at this time not know their own Hat-number and as such not be able to communicate using Smart SPI.

1. We Set Chip Select to 1 and send Device Identification Request with number “1”. The Hat that see it’s CS enabled will consume this message and set it’s id to 1. All others will ignore the message.
2. The Hat will respond with a short Device ID Response. This is a short message to tell the master that the device is active. Master will on a slower scheme attempt to send Device Identification request to device numbers that are not active to enable Hat’s at a later point. Device ID Response tell the Master that the device is active and ready to communicate using Smart SPI.

Normal operation

1. Once a full iteration through all 8 Hat’s are completed we start using Smart SPI. The Master will on regular intervals continue to send Device ID Request to Hat’s that’s not active. If a Hat fail to answer normal messaging it will be moved to Non-Active list until Master can perform a successfully ID request.

Note that the full start-up procedure for easyIPC consist of other sequences, but Smart SPI is a layer 2 link only responsible for sending/receiving between Raspberry PI and the Hat’s. See easyIPC for the higher level start-up procedure.

Smart SPI Message format

Length is a 8 bit unsigned integer that indicate the total length of the message in bytes. Minimum length value is 6 bytes since minimum payload is 1 byte. Payload length = Length-5.

DID (Device ID) is a physical address needed by layer 2 for message transfer. This is always the device ID. MOSI will contain the destination ID, MISO will contain the Source ID.

DID=0 is used for broadcast. Device 1-31 is a physical Device #.

SID (Stream ID) is the ID of a point to point stream. Stream 0 is always the device and layer 2 link. Stream is used for internal addressing on a node.

SEQ (Sequence Number) is a 1 byte number that start on 1 and wrap at 255. The value 0 is used for none-sequence. Each side in a Smart SPI need to remember the last messages sent and be able to repeat them on request. The receiver will verify that the SEQ increment with one, and if not issue a MessageMessage Repeat Request. MISO Switch Request also contain the last message received in case the last message was cut short. Sequence is unique per device and only intended to guarantee that all messages are transferred.

MID (Message ID) is actually the first byte in the payload. The meaning of the payload needs only be known by the stream end-points.

Payload is the actual message parameters/data.

CRC is a 2 byte CRC to ensure message integrity.

Device ID Request

Device ID Request is sent to a device that also will be selected by a Chip Select pin. Any device receiving this with CS set to 1 will accept this as it’s ID and respond with Device ID Response. The device will accept the address in the DID field as it’s address

The device ID procedure will send a Device ID Request on MOSI and then start padding with zero’s for a selected response time of x ms. The device needs to respond within this time or it will be marked as inactive and not included in the active iteration.

Master will attempt to re-connect to inactive devices ca once per sec.

Device ID Response

Device IS response is send by a device that receive Device ID request while chip select is active. This indicate that the device have received it’s address and established a link capable of communicating on Smart SPI.

Devices that fail to respond before Chip Select goes 0 (Zero) will be listed as inactive. SPI will always have a number of fixed slots that in theory is max 31, but the current limitation on Hat’s are 8.

Inactive Devices are listed separately and Master will use Idle time to attempt to re-connect to devices. See Device ID Request.

MISO Switch Request

MISO Switch Request is used to switch MISO Sender. All devices will set MISO to 3-state and stop communicating. The device currently sending will finish it’s current message and stop.

The Switch procedure contain a programmatic delay intended for the sending device to detect and abort it’s sending. Once that times out the new device will assume the MISO is available and start sending. Note that “response padding” in this case can be ordinary message stream.

MISO Switch Response

MISO Switch Response is sent after a delay needed to secure that the sending device stops. This is sent from the new device and indicate the current queue length. The next message is the first message in the queue.

Message Repeat Request

A repeat request is issued to repeat 1-2 missing messages. The response will either be messages repeated or a Message Repeat Reject if the sender is unable to repeat the messages.

Message Repeat Reject

Sent in response to a Message Repeat Request if one side is unable to repeat the messages. Can happen if the gap in sequence is to large.

Link Reset

Issued by both sides to reset sequence numbering. Used as a response to errors.