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.

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"`
`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

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")

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
Aardvark I2C/SPI	Dedicated USB SPI adapter with GPIO bit-bang

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
Aardvark uses GPIO bit-bang mode; actual speed is limited by USB round-trip time regardless of frequency_hz
Configuration changes persist to saved_nets.json for subsequent commands
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

Write to SPI Flash

16-bit Word Mode

Supported Hardware

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

​Write to SPI Flash

​16-bit Word Mode

​Supported Hardware

​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

Write to SPI Flash

16-bit Word Mode

Supported Hardware

Notes