SPI

Perform SPI (Serial Peripheral Interface) data transfers with devices connected to a Lagerbox. SPI is a synchronous serial protocol using four lines: SCLK (clock), MOSI (master out), MISO (master in), and CS (chip select).

Syntax

lager spi [NETNAME] [OPTIONS] [SUBCOMMAND]

Arguments

Argument	Description
`NETNAME`	SPI net name (optional if default is set via `lager defaults add --spi-net`)

Options

Option	Description
`--box BOX`	Lagerbox name or IP address

When invoked without a subcommand, lists SPI nets on the box (or shows configuration for the specified net).

Subcommands

`config`

Configure SPI bus parameters. Settings persist across subsequent commands.

lager spi NETNAME config [OPTIONS]

Option	Description
`--box BOX`	Lagerbox name or IP address
`--mode 0\|1\|2\|3`	SPI mode (clock polarity and phase)
`--frequency FREQ`	Clock frequency (e.g., `1M`, `500k`, `5M`)
`--bit-order msb\|lsb`	Bit order: MSB first or LSB first
`--word-size 8\|16\|32`	Word size in bits
`--cs-active low\|high`	Chip select active polarity
`--cs-mode auto\|manual`	CS assertion mode: `auto` (hardware) or `manual` (user-managed GPIO)

SPI Modes:

Mode	CPOL	CPHA	Description
0	0	0	Clock idle low, data sampled on rising edge
1	0	1	Clock idle low, data sampled on falling edge
2	1	0	Clock idle high, data sampled on falling edge
3	1	1	Clock idle high, data sampled on rising edge

Examples:

# Configure SPI mode 0 at 5MHz
lager spi MY_SPI config --mode 0 --frequency 5M

# Set 16-bit word size with LSB-first
lager spi MY_SPI config --word-size 16 --bit-order lsb

# Use manual CS mode (for Aardvark with separate GPIO for CS)
lager spi MY_SPI config --cs-mode manual

`transfer`

Perform a full-duplex SPI transfer. Sends data while simultaneously receiving response. If provided data is shorter than NUM_WORDS, the remaining words are padded with the fill value. If longer, data is truncated.

lager spi NETNAME transfer NUM_WORDS [OPTIONS]

Argument	Description
`NUM_WORDS`	Number of words to transfer

Option	Description	Default
`--box BOX`	Lagerbox name or IP address
`--data DATA`	Hex data to transmit (e.g., `0x9f01`)
`--data-file PATH`	File containing data to transmit
`--fill VALUE`	Fill value for padding	`0xFF`
`--mode 0\|1\|2\|3`	SPI mode override
`--frequency FREQ`	Clock frequency override
`--bit-order msb\|lsb`	Bit order override
`--word-size 8\|16\|32`	Word size override
`--cs-active low\|high`	CS polarity override
`--keep-cs`	Keep CS asserted after transfer	`false`
`--format FORMAT`	Output format: `hex`, `bytes`, `json`	`hex`

Examples:

# Read device ID: send 0x9F command, read 3 response bytes (4 words total)
lager spi MY_SPI transfer --data 0x9f 4

# Send data at 5MHz
lager spi MY_SPI transfer --data "01 02 03 04" --frequency 5M 4

# Output as JSON
lager spi MY_SPI transfer --data 0x9f 4 --format json

# Keep CS asserted for multi-part transfer
lager spi MY_SPI transfer --data 0x03 --keep-cs 1

`read`

Read data from an SPI slave device. Sends fill bytes while clocking in the response.

lager spi NETNAME read NUM_WORDS [OPTIONS]

Argument	Description
`NUM_WORDS`	Number of words to read

Option	Description	Default
`--box BOX`	Lagerbox name or IP address
`--fill VALUE`	Fill byte sent while reading	`0xFF`
`--mode 0\|1\|2\|3`	SPI mode override
`--frequency FREQ`	Clock frequency override
`--bit-order msb\|lsb`	Bit order override
`--word-size 8\|16\|32`	Word size override
`--cs-active low\|high`	CS polarity override
`--keep-cs`	Keep CS asserted after transfer	`false`
`--format FORMAT`	Output format: `hex`, `bytes`, `json`	`hex`

Examples:

# Read 5 bytes from SPI slave
lager spi MY_SPI read 5

# Read with 0x00 fill instead of default 0xFF
lager spi MY_SPI read 5 --fill 0x00

# Read 4 words at 16-bit word size
lager spi MY_SPI read 4 --word-size 16

`write`

Write data to an SPI slave device. Performs a full-duplex transfer and displays the received response.

lager spi NETNAME write DATA [OPTIONS]

Argument	Description
`DATA`	Hex data to write (e.g., `0x9f01020304`)

Option	Description	Default
`--box BOX`	Lagerbox name or IP address
`--mode 0\|1\|2\|3`	SPI mode override
`--frequency FREQ`	Clock frequency override
`--bit-order msb\|lsb`	Bit order override
`--word-size 8\|16\|32`	Word size override
`--cs-active low\|high`	CS polarity override
`--keep-cs`	Keep CS asserted after transfer	`false`
`--format FORMAT`	Output format: `hex`, `bytes`, `json`	`hex`

Examples:

# Send JEDEC ID command and read response
lager spi MY_SPI write 0x9f01020304

# Write with mode override
lager spi MY_SPI write 0x0102 --mode 3

# Write and keep CS low for continued transfer
lager spi MY_SPI write 0x03000000 --keep-cs

Hex Data Formats

Data arguments accept multiple hex formats. Parsing behavior depends on word size: 8-bit word size (default):

Format	Example	Parsed As
Prefixed continuous	`0x9f01`	`[0x9f, 0x01]`
Unprefixed continuous	`9f01`	`[0x9f, 0x01]`
Space-separated	`9f 01 02`	`[0x9f, 0x01, 0x02]`
Comma-separated	`9f,01,02`	`[0x9f, 0x01, 0x02]`

16-bit or 32-bit word size:

Format	Example	Parsed As
Continuous	`0x1234`	`[0x1234]`
Space-separated	`0x1234 0x5678`	`[0x1234, 0x5678]`

Values are validated against the configured word size range.

Fill Value Format

The --fill option accepts hex or decimal values:

Format	Example	Value
Hex prefixed	`0xff`	255
Hex unprefixed	`ff`	255
Decimal	`255`	255

Frequency Format

Clock frequencies accept numeric values with optional suffixes:

Format	Example	Value
Plain Hz	`1000000`	1 MHz
kHz suffix	`500k`	500 kHz
MHz suffix	`5M`	5 MHz
Hz suffix	`1000000hz`	1 MHz

Supported Hardware

Adapter	Pins	CS Control	Notes
LabJack T7	Configurable FIO pins (e.g., FIO0-FIO3)	Manual GPIO	~450 kHz max (throttle=0); CS managed via GPIO writes
Aardvark USB	Fixed MOSI/MISO/SCK/SS	Hardware or manual	Up to 8 MHz
FT232H	Configurable	MPSSE-based	FTDI MPSSE SPI

Net Configuration

SPI nets are configured in saved_nets.json on the box. Example net record:

{
  "name": "my_spi",
  "role": "spi",
  "instrument": "labjack_t7",
  "pin": "FIO0-FIO3",
  "params": {
    "cs_pin": 0,
    "clk_pin": 1,
    "mosi_pin": 2,
    "miso_pin": 3,
    "mode": 0,
    "frequency_hz": 1000000,
    "word_size": 8,
    "bit_order": "msb"
  }
}

For Aardvark adapters:

{
  "name": "my_spi",
  "role": "spi",
  "instrument": "aardvark",
  "pin": "SPI0",
  "params": {
    "mode": 0,
    "frequency_hz": 1000000,
    "word_size": 8,
    "bit_order": "msb"
  }
}

Output Formats

Format	Description
`hex`	Space-separated hex values (e.g., `9f 01 02`)
`bytes`	Raw byte values
`json`	JSON object with data array and metadata

Examples

# List all SPI nets on a box
lager spi --box my-lager-box

# Show configuration for a specific net
lager spi MY_SPI --box my-lager-box

# Configure SPI mode and speed
lager spi MY_SPI config --mode 0 --frequency 5M

# Read flash JEDEC ID (send 0x9F command, read 3 bytes)
lager spi MY_SPI transfer --data 0x9f 4

# Read 256 bytes from flash
lager spi MY_SPI read 256

# Write a command byte
lager spi MY_SPI write 0x06

# Multi-step transfer with CS held low
lager spi MY_SPI write 0x03 --keep-cs
lager spi MY_SPI read 4

Troubleshooting

No Response from Device

Verify MOSI, MISO, SCLK, and CS wiring
Check SPI mode matches the device datasheet
Confirm CS polarity (--cs-active low for most devices)
Try reducing frequency with --frequency 100k

Garbled Data

Verify SPI mode (CPOL/CPHA) matches the device
Check bit order (MSB vs LSB first)
Ensure word size matches the device protocol

CS Pin Not Working (LabJack T7)

LabJack T7 uses manual GPIO-based CS control
The driver automatically asserts/deasserts CS via GPIO writes
Verify the cs_pin in the net configuration matches your wiring

Notes

Default SPI net can be set with lager defaults add --spi-net NETNAME
LabJack T7 operates at ~450 kHz regardless of requested frequency due to hardware limitations
SPI is full-duplex: data is always sent and received simultaneously
Use --keep-cs for multi-part transactions that require CS to stay asserted
Configuration set via config persists across subsequent transfer/read/write commands

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Arguments

Options

Subcommands

`config`

`transfer`

`read`

`write`

Hex Data Formats

Fill Value Format

Frequency Format

Supported Hardware

Net Configuration

Output Formats

Examples

Troubleshooting

No Response from Device

Garbled Data

CS Pin Not Working (LabJack T7)

Notes

See Also

​Syntax

​Arguments

​Options

​Subcommands

​config

​transfer

​read

​write

​Hex Data Formats

​Fill Value Format

​Frequency Format

​Supported Hardware

​Net Configuration

​Output Formats

​Examples

​Troubleshooting

​No Response from Device

​Garbled Data

​CS Pin Not Working (LabJack T7)

​Notes

​See Also

Syntax

Arguments

Options

Subcommands

`config`

`transfer`

`read`

`write`

Hex Data Formats

Fill Value Format

Frequency Format

Supported Hardware

Net Configuration

Output Formats

Examples

Troubleshooting

No Response from Device

Garbled Data

CS Pin Not Working (LabJack T7)

Notes

See Also