SPI

Perform SPI (Serial Peripheral Interface) data transfers with devices connected to a Lager Box. 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`	Lager Box 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`	Lager Box 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`	Lager Box 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`	Lager Box 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`	Lager Box 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 DIO pins (default `FIO0-FIO3`: CS, CLK, MOSI, MISO)	Firmware auto CS; GPIO writes for `--keep-cs`	56 bytes per transfer; see the T7 clock note below
LabJack U3	Configurable DIO pins (default `FIO4-FIO7`: CS, CLK, MISO, MOSI)	Firmware auto CS, active-low only	50 bytes per transfer; about 5.4 kHz to 71.4 kHz; see below
Aardvark USB	Fixed MOSI/MISO/SCK/SS	Hardware or manual	Up to 8 MHz
FT232H	Configurable	MPSSE-based	FTDI MPSSE SPI

LabJack T7 clock: a request of 800 kHz or more runs at about 800 kHz. The T7 firmware fails a multi-byte transfer at most rates between about 1 kHz and 800 kHz. For a multi-byte transfer, the driver therefore runs a request in that range at about 1 kHz and prints a warning once. A single-byte transfer, and a request at or below about 1 kHz, use the requested rate.

LabJack U3

A U3 runs SPI through a firmware command of the U3, not through LJM. SPI on a U3 needs U3 hardware version 1.21 or later. Pins: the default channel FIO4-FIO7 assigns the pins in the order CS, CLK, MISO, MOSI. That order is different from the T7 order, which is CS, CLK, MOSI, MISO. For other pins, create the net with lager nets add and the options --cs, --sck, --mosi and --miso. FIO0-FIO3 cannot carry SPI. The EIO and CIO lines are on the DB15 connector of the U3. Limits:

A transfer is at most 50 bytes: 50 words at an 8-bit word size, 25 words at 16 bits, or 12 words at 32 bits.
The clock runs from about 5.4 kHz to 71.4 kHz, and the box never runs it faster than the request. A request outside that range is clamped.
config prints the rate that the hardware uses. When that rate differs from the request, it prints the request in brackets:

SPI configured: mode=0, freq=49959Hz (requested 50000Hz), word_size=8, bit_order=msb, cs_active=low, cs_mode=auto

A net with no stored frequency runs at the maximum rate. On such a net, config shows the default request, (requested 1000000Hz). The CLI does not show a warning for a clamped clock, so read the rate in the config output. Chip select: the U3 firmware drives CS low for each transfer and releases it at the end. It has no polarity control and no hold control. The box refuses --cs-active high. In auto CS mode, the box also refuses --keep-cs. For an active-high device, or to hold CS across transfers, create the SPI net without CS and drive CS from a gpio net. A net without CS uses manual CS mode.

# SPI net without CS: SCK=FIO5, MISO=FIO6, MOSI=FIO7
lager nets add FLASH spi custom <U3_ADDRESS> --sck FIO5 --miso FIO6 --mosi FIO7 --box my-lager-box

# gpio net that drives CS
lager nets add FLASH_CS gpio FIO4 <U3_ADDRESS> --box my-lager-box

# CS stays low across both transfers
lager gpo FLASH_CS low --box my-lager-box
lager spi FLASH write 0x03001000 --box my-lager-box
lager spi FLASH read 32 --box my-lager-box
lager gpo FLASH_CS high --box my-lager-box

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)

In auto CS mode, the T7 firmware asserts and releases CS for each transfer
With --keep-cs, the driver drives CS with GPIO writes instead
Verify the cs_pin in the net configuration matches your wiring

Refused Options (LabJack U3)

--cs-active high is refused on a U3. Use a net without CS and a gpio net for CS.
--keep-cs is refused in auto CS mode on a U3. Use the same method.
A transfer of more than 50 bytes is refused. Split it into smaller transfers.

Notes

Default SPI net can be set with lager defaults add --spi-net NETNAME
LabJack T7 runs at about 800 kHz for a request of 800 kHz or more. A multi-byte transfer with a request between about 1 kHz and 800 kHz runs at about 1 kHz
LabJack U3 runs from about 5.4 kHz to 71.4 kHz, and config prints the rate that the hardware uses
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

LabJack U3

Net Configuration

Output Formats

Examples

Troubleshooting

No Response from Device

Garbled Data

CS Pin Not Working (LabJack T7)

Refused Options (LabJack U3)

Notes

See Also

​Syntax

​Arguments

​Options

​Subcommands

​config

​transfer

​read

​write

​Hex Data Formats

​Fill Value Format

​Frequency Format

​Supported Hardware

​LabJack U3

​Net Configuration

​Output Formats

​Examples

​Troubleshooting

​No Response from Device

​Garbled Data

​CS Pin Not Working (LabJack T7)

​Refused Options (LabJack U3)

​Notes

​See Also

Syntax

Arguments

Options

Subcommands

`config`

`transfer`

`read`

`write`

Hex Data Formats

Fill Value Format

Frequency Format

Supported Hardware

LabJack U3

Net Configuration

Output Formats

Examples

Troubleshooting

No Response from Device

Garbled Data

CS Pin Not Working (LabJack T7)

Refused Options (LabJack U3)

Notes

See Also