SPI bulk data interface
Warning
v0.2.x firmware is supported for EVK PCBA >= Rev2.
Calumino's Gen3 processing module serves thermal frames, computer vision detections, computer vision foreground, and metadata over a bulk data Serial Peripheral Interface (SPI).
The processing module is a SPI slave that only transmits data, it does not receive data.
The bulk data can be configured by using the processing module's command and control Inter-Integrated Circuit (I2C) interface.
Warning
<= v0.2.0 firmware does not yet support an I2C interface for configuration of the SPI bulk data interface.
Configuration
Pins
| # | Name | Type | Description |
|---|---|---|---|
| PB2 | MISO |
Digital output | Serial data output. |
| PB3 | MOSI |
Digital input | Serial data input. Unused. |
| PB4 | SCLK |
Digital input | Serial clock input. |
| PB5 | CS |
Digital input | Chip select; active low. |
| PB6 | DATA_RDY |
Digital output | Data ready indicator; active low. |
| PB7 | RST |
Digital input | Transaction finished interrupt (route to CS) |
Mode and timing
Note
Switching characteristics and timimg requirements are provided in Himax's WE2 datasheet.
| Mode | CPHA | CPOL |
|---|---|---|
| 0 | 0 | 0 |
The minimum SCLK period is 100ns (max frequency 10MHz).
Data packet
The data provided in a transmission is a single contiguous packet of each section shown below.
Each section a 2 byte CRC using the CRC-16-CCITT (XModem) algorithm calculated on the contents of that section (not including the CRC). Each section can be selectively turned on and off by using the command and control I2C interface. The fixed byte size of each section is shown below.
| Section | Size (Bytes) |
|---|---|
| Version | 4 |
| Thermal frame (excl. CRC) | 600 |
| Thermal frame CRC | 2 |
| Metadata (excl. CRC) | 256 |
| Metadata CRC | 2 |
| CV foreground (excl. CRC) | 600 |
| CV foreground CRC | 2 |
| CV detections (excl. CRC) | 714 |
| CV detections CRC | 2 |
| Total (incl. CRC) | 2182 |
The API reference defines ctype structs for the SPI packet (SpiPacket) and its subsections (e.g. SpiThermalPacket). The SPI packet structure is as follows:
| Field | Type | Description |
|---|---|---|
| version | uint32 | SPI packet version (see SPI_PACKET_VERSION) |
| thermal_frame | int16[300] | Thermal image pixels |
| crc | uint16 | CRC for thermal_frame section |
| metadata | uint32[64] | Register map metadata |
| crc | uint16 | CRC for metadata section |
| cv_foreground | int16[300] | CV foreground image |
| crc | uint16 | CRC for cv_foreground section |
| cv_detections | struct[21] | Array of CvDetection structs |
| crc | uint16 | CRC for cv_detections section |
The CvDetection struct contains:
| Field | Type | Description |
|---|---|---|
| id | uint8 | Detection ID |
| label | uint8 | Detection label (0=object, 1=human) |
| temperature_centre_location_x | uint8 | X location of temperature centre |
| temperature_centre_location_y | uint8 | Y location of temperature centre |
| frames_since_motion | uint32 | Frames since last movement |
| peak_temperature | float | Highest temperature |
| foot_position_estimate_x | float | Estimated ground X position |
| foot_position_estimate_y | float | Estimated ground Y position |
| displacement | float | Displacement in pixels since last frame |
| speed | float | Speed in pixels per second |
| angle | float | Angle of movement in degrees (0° - 360°) |
Data retrieval
The processing module prepares the data SPI TX FIFO with data as configured by the command and control I2C interface.
When this occurs, the DATA_RDY pin will be asserted low to trigger data retrieval for at least 10us.
Retrieve data by asserting CS low and clocking out as many bytes as ctypes.sizeof(SpiPacket) or size of I2C configured data sections, then deasserting CS high.
Warning
CS must be deasserted high at the end of a read in order for the processing module to safely reset the SPI TX FIFO. Do not keep CS asserted low.
DATA_RDY then deasserts high.
The processing module will reset the SPI TX FIFO at the end of each transaction after CS is desasserted high.
Therefore, if a CRC error occurs, or if the read bytes != ctypes.sizeof(SpiPacket), simply retrieve data again before FRDY next goes high (at which point the old data is lost).
Imagine the contents of the SPI TX FIFO are [0x00, 0x01, 0x02, ... 0xFE, 0xFF].
If the read bytes < ctypes.sizeof(SpiPacket), then DATA_RDY will stay asserted until a subsequent transaction ends that has read all >= ctypes.sizeof(SpiPacket). The subsequent transaction will contain the same data repeated.
If the read bytes > ctypes.sizeof(SpiPacket), then DATA_RDY will deassert, and all bytes extra bytes read are copies of the last byte. The subsequent transaction will contain the same data repeated.