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`	Per-call config overrides (e.g., `{"frequency_hz": 400000}`)

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`	Per-call config overrides (e.g., `{"frequency_hz": 400000}`)

`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`	Per-call config overrides (e.g., `{"frequency_hz": 400000}`)

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

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