SPI

Perform full-duplex SPI (Serial Peripheral Interface) communication with devices connected to a Lager Box.

Import

from lager import Net, NetType

Methods

Method	Description
`config()`	Configure SPI bus parameters
`read()`	Read words from a device (sends fill bytes)
`read_write()`	Simultaneous full-duplex read and write
`transfer()`	Transfer with automatic padding/truncation
`write()`	Write words to a device (discards response)
`get_config()`	Get raw net configuration

Method Reference

`Net.get(name, type=NetType.SPI)`

Get an SPI net by name.

from lager import Net, NetType

spi = Net.get('MY_SPI_NET', type=NetType.SPI)

Parameters:

Parameter	Type	Description
`name`	`str`	Name of the SPI net
`type`	`NetType`	Must be `NetType.SPI`

Returns: SPI Net instance

`config(mode, bit_order, frequency_hz, word_size, cs_active, cs_mode)`

Configure SPI bus parameters. Only explicitly-provided parameters are changed; omitted parameters retain their stored values. config() changes the driver in the running script. It does not write the values to saved_nets.json. To store a configuration on the net, use lager spi NET config from the CLI.

spi.config(mode=0, frequency_hz=1_000_000)
spi.config(mode=3, bit_order="lsb", word_size=16)
spi.config(cs_mode="manual")

Parameter	Type	Description
`mode`	`int` or `None`	SPI mode 0-3 (see SPI Modes table below)
`bit_order`	`str` or `None`	`"msb"` (most significant bit first) or `"lsb"`
`frequency_hz`	`int` or `None`	Clock frequency in Hz
`word_size`	`int` or `None`	Bits per word: `8`, `16`, or `32`
`cs_active`	`str` or `None`	Chip select polarity: `"low"` or `"high"`. A LabJack U3 refuses `"high"`
`cs_mode`	`str` or `None`	`"auto"` (hardware CS) or `"manual"` (user-managed GPIO)

SPI Modes

Mode	CPOL	CPHA	Clock Idle	Sample Edge
0	0	0	Low	Rising
1	0	1	Low	Falling
2	1	0	High	Falling
3	1	1	High	Rising

`read(n_words, fill, keep_cs, output_format)`

Read data from an SPI device. Sends fill bytes while receiving data (full duplex).

data = spi.read(n_words=4)
data = spi.read(n_words=4, fill=0x00)

Parameter	Type	Description
`n_words`	`int`	Number of words to read
`fill`	`int`	Fill value sent while reading (default `0xFF`)
`keep_cs`	`bool`	Keep CS asserted after transfer (default `False`)
`output_format`	`str`	`"list"` (default), `"hex"`, `"bytes"`, or `"json"`

Returns: list[int] - Received words as integers (when output_format="list")

`read_write(data, keep_cs, output_format)`

Perform simultaneous full-duplex SPI read and write. Sends data while simultaneously receiving the response.

# Send JEDEC Read ID command and read 3 response bytes
response = spi.read_write([0x9F, 0x00, 0x00, 0x00])
manufacturer_id = response[1]
device_id = (response[2] << 8) | response[3]

Parameter	Type	Description
`data`	`list[int]`	Words to transmit
`keep_cs`	`bool`	Keep CS asserted after transfer (default `False`)
`output_format`	`str`	`"list"` (default), `"hex"`, `"bytes"`, or `"json"`

Returns: list[int] - Received words (same length as transmitted data)

`transfer(n_words, data, fill, keep_cs, output_format)`

Perform SPI transfer with automatic padding or truncation. If data is shorter than n_words, it is padded with the fill value. If longer, it is truncated.

# Send 1-byte command, read 3 response bytes (4 total)
response = spi.transfer(n_words=4, data=[0x9F])
# data [0x9F] is padded to [0x9F, 0xFF, 0xFF, 0xFF]

Parameter	Type	Description
`n_words`	`int`	Total number of words to transfer
`data`	`list[int]` or `None`	Words to transmit (padded/truncated to `n_words`)
`fill`	`int`	Fill value for padding (default `0xFF`)
`keep_cs`	`bool`	Keep CS asserted after transfer (default `False`)
`output_format`	`str`	`"list"` (default), `"hex"`, `"bytes"`, or `"json"`

Returns: list[int] - Received words

`write(data, keep_cs)`

Write data to an SPI device, discarding the response. Convenience method for write-only operations.

# Send Write Enable command
spi.write([0x06])

# Send Page Program with address and data
spi.write([0x02, 0x00, 0x00, 0x00, 0xDE, 0xAD, 0xBE, 0xEF])

Parameter	Type	Description
`data`	`list[int]`	Words to transmit
`keep_cs`	`bool`	Keep CS asserted after transfer (default `False`)

`get_config()`

Get the raw net configuration dictionary.

cfg = spi.get_config()
print(cfg['name'])
print(cfg['params'])

Returns: dict - Full net configuration including name, role, instrument, and params

Output Formats

The output_format parameter controls how data is returned. Hex formatting is word-size-aware:

Format	Return Type	8-bit Example	16-bit Example
`"list"`	`list[int]`	`[222, 173]`	`[57005]`
`"hex"`	`str`	`"de ad"`	`"dead"`
`"bytes"`	`str`	`"222 173"`	`"57005"`
`"json"`	`dict`	`{"data": [222, 173]}`	`{"data": [57005]}`

Examples

Read SPI Flash JEDEC ID

from lager import Net, NetType

spi = Net.get('flash_spi', type=NetType.SPI)
spi.config(mode=0, frequency_hz=1_000_000)

# JEDEC Read ID: send 0x9F, read 3 response bytes
response = spi.read_write([0x9F, 0x00, 0x00, 0x00])
print(f"Manufacturer: 0x{response[1]:02x}")
print(f"Device ID: 0x{(response[2] << 8) | response[3]:04x}")

Read Flash Memory

from lager import Net, NetType

spi = Net.get('flash_spi', type=NetType.SPI)
spi.config(mode=0, frequency_hz=1_000_000)

# Read 32 bytes starting at address 0x001000
# Command: 0x03 (Read), followed by 3-byte address
response = spi.transfer(
    n_words=4 + 32,
    data=[0x03, 0x00, 0x10, 0x00],
)
# First 4 bytes are command echo; data starts at index 4
data = response[4:]
print(f"Read {len(data)} bytes: {' '.join(f'{b:02x}' for b in data)}")

Multi-Part Transaction with keep_cs

A LabJack U3 in auto CS mode refuses keep_cs=True. On a U3, use the manual CS example below.

from lager import Net, NetType

spi = Net.get('flash_spi', type=NetType.SPI)

# Part 1: Send address with CS held low
spi.write([0x03, 0x00, 0x10, 0x00], keep_cs=True)

# Part 2: Read data while CS is still asserted
data = spi.read(n_words=32, keep_cs=False)
print(f"Read {len(data)} bytes")

Manual Chip Select on a LabJack U3

A U3 drives CS low for each transfer and releases it at the end. To hold CS across transfers, or to drive an active-high CS, use an SPI net without CS and a GPIO net for CS. An SPI net without CS uses manual CS mode.

from lager import Net, NetType

spi = Net.get('flash_spi', type=NetType.SPI)   # no CS pin on this net
cs = Net.get('flash_cs', type=NetType.GPIO)

cs.output(0)                                   # assert CS (active low)
spi.write([0x03, 0x00, 0x10, 0x00])
data = spi.read(n_words=32)
cs.output(1)                                   # release CS

Write to SPI Flash

from lager import Net, NetType

spi = Net.get('flash_spi', type=NetType.SPI)
spi.config(mode=0, frequency_hz=1_000_000)

# Step 1: Write Enable
spi.write([0x06])

# Step 2: Page Program at address 0x001000
payload = [0xDE, 0xAD, 0xBE, 0xEF]
spi.write([0x02, 0x00, 0x10, 0x00] + payload)

# Step 3: Wait for write to complete (poll status register)
import time
while True:
    status = spi.read_write([0x05, 0x00])
    if not (status[1] & 0x01):  # WIP bit cleared
        break
    time.sleep(0.01)

print("Write complete")

16-bit Word Mode

from lager import Net, NetType

spi = Net.get('dac_spi', type=NetType.SPI)
spi.config(mode=1, word_size=16, frequency_hz=500_000)

# Send 16-bit DAC command (channel A, gain 1x, active, value 0x0800)
spi.write([0x3800])

# Read back 16-bit status register
status = spi.read_write([0x0000])
print(f"Status: 0x{status[0]:04x}")

Supported Hardware

Adapter	Description
LabJack T7	Uses GPIO pins (FIO/EIO) for CLK, MOSI, MISO, and CS
LabJack U3	Uses DIO pins for CS, CLK, MISO, and MOSI (default `FIO4-FIO7`, in that order)
Aardvark I2C/SPI	Dedicated USB SPI adapter with GPIO bit-bang
FTDI FT232H / FT2232H / FT4232H	MPSSE-based SPI; channel selected per net

Multi-channel FTDI adapters

An FTDI net takes its channel from params.interface on the net record, accepting A-D or 0-3. Set it with lager nets add --interface. A net with no interface uses channel A, the only choice on a single-channel FT232H.

Part	Channels	Usable for SPI
FT232H	1 (A)	A
FT2232H	2 (A, B)	A, B
FT4232H	4 (A-D)	A, B

SPI runs over the FTDI part’s MPSSE engine, and on an FT4232H only channels A and B have one. lager nets add refuses C or D for an SPI net. A net record edited by hand with C or D fails when the net opens, and the error names the channel. See Nets for how channels are assigned across net types on one chip.

LabJack U3

SPI on a U3 needs U3 hardware version 1.21 or later.
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. A larger transfer raises an error.
The clock runs from about 5.4 kHz to 71.4 kHz, and it is never faster than frequency_hz. A request outside that range is clamped, with a warning on the standard error output of the script.
A net with no stored frequency_hz runs at the maximum rate.
cs_active="high" raises an error. keep_cs=True raises an error in auto CS mode.
FIO0-FIO3 cannot carry SPI. The driver raises an error for a net that uses them.

See SPI for the pin order and for how to create a U3 net with other pins.

Notes

Net must be configured as NetType.SPI
All SPI operations are full duplex; data is sent and received simultaneously
write() performs a full-duplex transfer but discards the received data
keep_cs=True holds the chip select line asserted between calls for multi-part transactions
transfer() pads short data arrays with the fill value or truncates long arrays to n_words
LabJack T7 supports up to 56 bytes per transaction and a maximum of approximately 800 kHz. A multi-byte transfer with a request between about 1 kHz and 800 kHz runs at about 1 kHz
LabJack U3 supports up to 50 bytes per transaction, from about 5.4 kHz to 71.4 kHz
Aardvark uses GPIO bit-bang mode; actual speed is limited by USB round-trip time regardless of frequency_hz
config() applies to the running script only. lager spi NET config stores the configuration in saved_nets.json
LSB-first mode (bit_order="lsb") uses software bit reversal on LabJack T7

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

Import

Methods

Method Reference

`Net.get(name, type=NetType.SPI)`

`config(mode, bit_order, frequency_hz, word_size, cs_active, cs_mode)`

SPI Modes

`read(n_words, fill, keep_cs, output_format)`

`read_write(data, keep_cs, output_format)`

`transfer(n_words, data, fill, keep_cs, output_format)`

`write(data, keep_cs)`

`get_config()`

Output Formats

Examples

Read SPI Flash JEDEC ID

Read Flash Memory

Multi-Part Transaction with keep_cs

Manual Chip Select on a LabJack U3

Write to SPI Flash

16-bit Word Mode

Supported Hardware

Multi-channel FTDI adapters

LabJack U3

Notes

​Import

​Methods

​Method Reference

​Net.get(name, type=NetType.SPI)

​config(mode, bit_order, frequency_hz, word_size, cs_active, cs_mode)

​SPI Modes

​read(n_words, fill, keep_cs, output_format)

​read_write(data, keep_cs, output_format)

​transfer(n_words, data, fill, keep_cs, output_format)

​write(data, keep_cs)

​get_config()

​Output Formats

​Examples

​Read SPI Flash JEDEC ID

​Read Flash Memory

​Multi-Part Transaction with keep_cs

​Manual Chip Select on a LabJack U3

​Write to SPI Flash

​16-bit Word Mode

​Supported Hardware

​Multi-channel FTDI adapters

​LabJack U3

​Notes

Import

Methods

Method Reference

`Net.get(name, type=NetType.SPI)`

`config(mode, bit_order, frequency_hz, word_size, cs_active, cs_mode)`

SPI Modes

`read(n_words, fill, keep_cs, output_format)`

`read_write(data, keep_cs, output_format)`

`transfer(n_words, data, fill, keep_cs, output_format)`

`write(data, keep_cs)`

`get_config()`

Output Formats

Examples

Read SPI Flash JEDEC ID

Read Flash Memory

Multi-Part Transaction with keep_cs

Manual Chip Select on a LabJack U3

Write to SPI Flash

16-bit Word Mode

Supported Hardware

Multi-channel FTDI adapters

LabJack U3

Notes