I2C

Read, write, and scan I2C (Inter-Integrated Circuit) devices connected to a Lager Box.

Import

from lager import Net, NetType

Methods

Method	Description
`config()`	Configure I2C bus parameters
`scan()`	Scan bus for connected devices
`read()`	Read bytes from a device
`write()`	Write bytes to a device
`write_read()`	Write then read in a single transaction (repeated start)
`get_config()`	Get raw net configuration

Method Reference

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

Get an I2C net by name.

from lager import Net, NetType

i2c = Net.get('MY_I2C_NET', type=NetType.I2C)

Parameters:

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

Returns: I2C Net instance

`config(frequency_hz, pull_ups)`

Configure I2C bus parameters. Only explicitly-provided parameters are changed; omitted parameters retain their stored values.

i2c.config(frequency_hz=400_000)
i2c.config(frequency_hz=100_000, pull_ups=True)

Parameter	Type	Description
`frequency_hz`	`int` or `None`	Clock frequency in Hz (e.g., 100000, 400000). `None` keeps stored value
`pull_ups`	`bool` or `None`	Enable/disable internal pull-ups (Aardvark only). `None` keeps stored value

`scan(start_addr, end_addr)`

Scan the I2C bus for connected devices.

devices = i2c.scan()
print(f"Found: {[hex(a) for a in devices]}")

Parameter	Type	Description
`start_addr`	`int`	First 7-bit address to probe (default `0x08`)
`end_addr`	`int`	Last 7-bit address to probe (default `0x77`)

Returns: list[int] - List of 7-bit addresses that responded with ACK

`read(address, num_bytes, output_format, overrides)`

Read bytes from an I2C device.

data = i2c.read(address=0x48, num_bytes=2)
temp = (data[0] << 8) | data[1]

Parameter	Type	Description
`address`	`int`	7-bit device address (`0x00`-`0x7F`)
`num_bytes`	`int`	Number of bytes to read
`output_format`	`str`	`"list"` (default), `"hex"`, `"bytes"`, or `"json"`
`overrides`	`dict` or `None`	Config overrides (e.g., `{"frequency_hz": 400000}`). They stay in effect for later calls on the net

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

`write(address, data, overrides)`

Write bytes to an I2C device.

i2c.write(address=0x48, data=[0x0A, 0x03])

Parameter	Type	Description
`address`	`int`	7-bit device address (`0x00`-`0x7F`)
`data`	`list[int]`	Bytes to write
`overrides`	`dict` or `None`	Config overrides (e.g., `{"frequency_hz": 400000}`). They stay in effect for later calls on the net

`write_read(address, data, num_bytes, output_format, overrides)`

Write then read in a single I2C transaction using a repeated start condition. This is the standard pattern for reading device registers.

# Read 2-byte temperature register at address 0x00
temp_bytes = i2c.write_read(address=0x48, data=[0x00], num_bytes=2)
temperature = (temp_bytes[0] << 8) | temp_bytes[1]

Parameter	Type	Description
`address`	`int`	7-bit device address (`0x00`-`0x7F`)
`data`	`list[int]`	Bytes to write before reading (typically a register address)
`num_bytes`	`int`	Number of bytes to read after writing
`output_format`	`str`	`"list"` (default), `"hex"`, `"bytes"`, or `"json"`
`overrides`	`dict` or `None`	Config overrides (e.g., `{"frequency_hz": 400000}`). They stay in effect for later calls on the net

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

`get_config()`

Get the raw net configuration dictionary.

cfg = i2c.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 on read() and write_read() controls how data is returned:

Format	Return Type	Example
`"list"`	`list[int]`	`[72, 118, 153]`
`"hex"`	`str`	`"48 76 99"`
`"bytes"`	`str`	`"72 118 153"`
`"json"`	`dict`	`{"data": [72, 118, 153]}`

Examples

Basic Device Read

from lager import Net, NetType

i2c = Net.get('my_i2c', type=NetType.I2C)

# Scan for devices
devices = i2c.scan()
print(f"Found devices at: {[hex(a) for a in devices]}")

# Read 2 bytes from device at 0x48
data = i2c.read(address=0x48, num_bytes=2)
print(f"Data: {data}")

Register Read/Write

from lager import Net, NetType

i2c = Net.get('my_i2c', type=NetType.I2C)

# Write configuration register
i2c.write(address=0x48, data=[0x01, 0x60, 0xA0])

# Read temperature register (write register addr, then read 2 bytes)
temp_bytes = i2c.write_read(address=0x48, data=[0x00], num_bytes=2)
raw = (temp_bytes[0] << 8) | temp_bytes[1]
celsius = raw / 256.0
print(f"Temperature: {celsius:.1f} C")

Bus Configuration

from lager import Net, NetType

i2c = Net.get('my_i2c', type=NetType.I2C)

# Configure for 400 kHz Fast Mode with pull-ups
i2c.config(frequency_hz=400_000, pull_ups=True)

# Scan a specific address range
devices = i2c.scan(start_addr=0x20, end_addr=0x7F)
for addr in devices:
    print(f"  0x{addr:02x}")

Multi-Device Setup

from lager import Net, NetType

i2c = Net.get('sensor_bus', type=NetType.I2C)
i2c.config(frequency_hz=100_000)

# Read from multiple sensors on the same bus
TEMP_SENSOR = 0x48
PRESSURE_SENSOR = 0x76

# Temperature (TMP102)
temp_raw = i2c.write_read(address=TEMP_SENSOR, data=[0x00], num_bytes=2)
temp_c = ((temp_raw[0] << 4) | (temp_raw[1] >> 4)) * 0.0625
print(f"Temperature: {temp_c:.1f} C")

# Pressure (BMP280) - read chip ID register
chip_id = i2c.write_read(address=PRESSURE_SENSOR, data=[0xD0], num_bytes=1)
print(f"BMP280 chip ID: 0x{chip_id[0]:02x}")

Per-Call Configuration Override

from lager import Net, NetType

i2c = Net.get('my_i2c', type=NetType.I2C)
i2c.config(frequency_hz=100_000)

# Most devices use standard mode
data = i2c.read(address=0x48, num_bytes=2)

# One device needs fast mode for this transaction
data = i2c.read(address=0x50, num_bytes=256,
                overrides={"frequency_hz": 400_000})

# The override stays in effect, so set the rate back for the next device
i2c.config(frequency_hz=100_000)

An override changes the net’s driver for the rest of the script, not only the one call. Set the value back with config() when the next transaction needs the old one. See #848.

Supported Hardware

Adapter	Description
LabJack T7	Uses GPIO pins (FIO/EIO) for SDA and SCL
LabJack U3	Uses DIO pins for SDA and SCL (default `FIO6` and `FIO7`)
Aardvark I2C/SPI	Dedicated USB I2C adapter with pull-up support
FTDI FT232H / FT2232H / FT4232H	MPSSE-based I2C; 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 I2C
FT232H	1 (A)	A
FT2232H	2 (A, B)	A, B
FT4232H	4 (A-D)	A, B

I2C 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 I2C 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

I2C on a U3 needs U3 hardware version 1.21 or later. The U3 is a bus master only.
The U3 has no pull-up resistors. Connect external resistors from SDA and SCL to VS; LabJack recommends 4.7 kΩ. Without them, every address sends a NAK and scan() returns an empty list.
pull_ups has no effect on a U3.
A transaction writes at most 50 bytes and reads at most 52 bytes. A larger transaction raises an error.
The clock runs from about 10 kHz to 150 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.
write() and write_read() check the acknowledgement of the address and of each byte. The error names the first byte that the device refused. For a write of 31 bytes or more, the error does not name the byte.
FIO0-FIO3 cannot carry I2C. The driver raises an error for a net that uses them.

See I2C for the pins and for how to create a U3 net with other pins.

Notes

Net must be configured as NetType.I2C
Addresses are 7-bit format (0x00-0x7F), not left-shifted
pull_ups only works on the Aardvark adapter; ignored on LabJack T7 and LabJack U3
write_read() uses a repeated start condition for atomic register reads
Default scan range (0x08-0x77) skips reserved addresses
Configuration changes persist to saved_nets.json for subsequent commands
LabJack T7 maps the requested frequency to a clock throttle, from about 130 Hz to 450 kHz
LabJack U3 runs from about 10 kHz to 150 kHz

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

Import

Methods

Method Reference

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

`config(frequency_hz, pull_ups)`

`scan(start_addr, end_addr)`

`read(address, num_bytes, output_format, overrides)`

`write(address, data, overrides)`

`write_read(address, data, num_bytes, output_format, overrides)`

`get_config()`

Output Formats

Examples

Basic Device Read

Register Read/Write

Bus Configuration

Multi-Device Setup

Per-Call Configuration Override

Supported Hardware

Multi-channel FTDI adapters

LabJack U3

Notes

​Import

​Methods

​Method Reference

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

​config(frequency_hz, pull_ups)

​scan(start_addr, end_addr)

​read(address, num_bytes, output_format, overrides)

​write(address, data, overrides)

​write_read(address, data, num_bytes, output_format, overrides)

​get_config()

​Output Formats

​Examples

​Basic Device Read

​Register Read/Write

​Bus Configuration

​Multi-Device Setup

​Per-Call Configuration Override

​Supported Hardware

​Multi-channel FTDI adapters

​LabJack U3

​Notes

Import

Methods

Method Reference

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

`config(frequency_hz, pull_ups)`

`scan(start_addr, end_addr)`

`read(address, num_bytes, output_format, overrides)`

`write(address, data, overrides)`

`write_read(address, data, num_bytes, output_format, overrides)`

`get_config()`

Output Formats

Examples

Basic Device Read

Register Read/Write

Bus Configuration

Multi-Device Setup

Per-Call Configuration Override

Supported Hardware

Multi-channel FTDI adapters

LabJack U3

Notes