I2C

Perform I2C (Inter-Integrated Circuit) data transfers with devices connected to a Lager Box. I2C is a synchronous serial protocol using two lines: SDA (data) and SCL (clock).

Syntax

lager i2c [NETNAME] [OPTIONS] [SUBCOMMAND]

Arguments

Argument	Description
`NETNAME`	I2C net name (optional if default is set via `lager defaults add --i2c-net`)

Options

Option	Description
`--box BOX`	Lager Box name or IP address

When invoked without a subcommand, lists I2C nets on the box (or shows configuration for the specified net).

Subcommands

`config`

Configure I2C bus parameters. Settings persist across subsequent commands.

lager i2c NETNAME config [OPTIONS]

Option	Description
`--box BOX`	Lager Box name or IP address
`--frequency FREQ`	Clock frequency (e.g., `100k`, `400k`, `1M`)
`--pull-ups on\|off`	Enable/disable internal pull-ups (Aardvark only)

Examples:

# Set I2C clock to 400kHz with internal pull-ups
lager i2c MY_I2C config --frequency 400k --pull-ups on

# Set clock to 100kHz (standard mode)
lager i2c MY_I2C config --frequency 100k

`scan`

Scan the I2C bus for connected devices. Probes each address and reports those that respond with an ACK.

lager i2c NETNAME scan [OPTIONS]

Option	Description	Default
`--box BOX`	Lager Box name or IP address
`--start ADDR`	Start address in hex	`0x08`
`--end ADDR`	End address in hex	`0x77`

The default range 0x08-0x77 excludes reserved I2C addresses. Examples:

# Scan default address range
lager i2c MY_I2C scan --box my-lager-box

# Scan specific range
lager i2c MY_I2C scan --start 0x20 --end 0x27

`read`

Read bytes from an I2C device.

lager i2c NETNAME read NUM_BYTES [OPTIONS]

Argument	Description
`NUM_BYTES`	Number of bytes to read (0 or more)

Option	Description	Default
`--box BOX`	Lager Box name or IP address
`--address ADDR`	Device address in hex (e.g., `0x48`)	Required
`--frequency FREQ`	Clock frequency override (e.g., `100k`, `400k`)
`--format FORMAT`	Output format: `hex`, `bytes`, `json`	`hex`

Examples:

# Read 4 bytes from device at address 0x48
lager i2c MY_I2C read 4 --address 0x48

# Read 2 bytes with JSON output
lager i2c MY_I2C read 2 --address 0x48 --format json

# Read with frequency override
lager i2c MY_I2C read 4 --address 0x48 --frequency 100k

`write`

Write bytes to an I2C device.

lager i2c NETNAME write DATA [OPTIONS]

Argument	Description
`DATA`	Hex data to write (e.g., `0x0A03`, `0a 03`, `0a,03`)

Option	Description	Default
`--box BOX`	Lager Box name or IP address
`--address ADDR`	Device address in hex (e.g., `0x48`)	Required
`--data-file PATH`	File containing binary data to write
`--frequency FREQ`	Clock frequency override
`--format FORMAT`	Output format: `hex`, `bytes`, `json`	`hex`

Provide data either as the DATA argument or via --data-file, but not both. Examples:

# Write register address 0x0A followed by value 0x03
lager i2c MY_I2C write 0x0A03 --address 0x48

# Write using space-separated hex bytes
lager i2c MY_I2C write "0a 03" --address 0x48

# Write from a binary file
lager i2c MY_I2C write --data-file config.bin --address 0x48

`transfer`

Write then read in a single I2C transaction using a repeated start condition. This is the standard pattern for reading registers: write the register address, then read the register value without releasing the bus.

lager i2c NETNAME transfer NUM_BYTES [OPTIONS]

Argument	Description
`NUM_BYTES`	Number of bytes to read (0 or more)

Option	Description	Default
`--box BOX`	Lager Box name or IP address
`--address ADDR`	Device address in hex (e.g., `0x48`)	Required
`--data DATA`	Hex data to write before reading (e.g., register address)
`--data-file PATH`	File containing data to write before reading
`--frequency FREQ`	Clock frequency override
`--format FORMAT`	Output format: `hex`, `bytes`, `json`	`hex`

Examples:

# Read 2 bytes from register 0x0A on device 0x48
lager i2c MY_I2C transfer 2 --address 0x48 --data 0x0A

# Read temperature from a sensor (register 0x00, 2 bytes)
lager i2c MY_I2C transfer 2 --address 0x76 --data 0x00

# Read with JSON output
lager i2c MY_I2C transfer 4 --address 0x48 --data 0x0A --format json

Hex Data Formats

Data arguments accept multiple hex formats:

Format	Example	Parsed As
Prefixed continuous	`0x0a03`	`[0x0a, 0x03]`
Unprefixed continuous	`0a03`	`[0x0a, 0x03]`
Space-separated	`0a 03`	`[0x0a, 0x03]`
Comma-separated	`0a,03`	`[0x0a, 0x03]`
Single byte	`0x0a`	`[0x0a]`

All values must be within byte range (0x00-0xFF).

Address Format

I2C addresses are 7-bit values (0x00-0x7F). You can specify addresses in hex or decimal:

Format	Example	Value
Hex prefixed	`0x48`	72
Hex unprefixed	`48`	72
Decimal	`72`	72

Frequency Format

Clock frequencies accept numeric values with optional suffixes:

Format	Example	Value
Plain Hz	`100000`	100 kHz
kHz suffix	`100k`	100 kHz
MHz suffix	`1M`	1 MHz
Hz suffix	`400000hz`	400 kHz

Supported Hardware

Adapter	Pins	Pull-ups	Notes
LabJack T7	Configurable DIO pins (default `FIO4-FIO5`: SDA, SCL)	External only	56 bytes per transfer; about 130 Hz to 450 kHz
LabJack U3	Configurable DIO pins (default `FIO6-FIO7`: SDA, SCL)	External only; the U3 has none	50 bytes written and 52 bytes read per transfer; about 10 kHz to 150 kHz
Aardvark USB	Fixed SDA/SCL	Internal (switchable)	Up to 800 kHz
FT232H	Configurable	External only	MPSSE-based I2C

The LabJack T7 maps the requested frequency to a clock throttle, up to about 450 kHz. If the T7 firmware refuses the computed throttle, the driver runs at the maximum rate and prints a warning.

LabJack U3

A U3 runs I2C through a firmware command of the U3, not through LJM. I2C on a U3 needs U3 hardware version 1.21 or later. The U3 is a bus master only. Pins: the default channel FIO6-FIO7 assigns SDA to FIO6 and SCL to FIO7. For other pins, create the net with lager nets add and the options --sda and --scl. FIO0-FIO3 cannot carry I2C. The EIO and CIO lines are on the DB15 connector of the U3. Pull-ups: the U3 has no pull-up resistors. Connect external resistors from SDA and from 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, and config prints pull_ups=n/a (external resistors required). Limits:

A transfer writes at most 50 bytes and reads at most 52 bytes.
The clock runs from about 10 kHz to 150 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, with the request in brackets when the two differ:

I2C configured: freq=96835Hz (requested 100000Hz), pull_ups=n/a (external resistors required)

The CLI does not show a warning for a clamped clock, so read the rate in the config output. Errors: the U3 checks the acknowledgement of the address and of each byte that it writes. An error names the first byte that the device refused:

No ACK from device at 0x48. Check the address, that the device is powered, and that SDA and SCL have external pull-up resistors -- a U3 has none.
Device at 0x48 acknowledged its address but NAKed data byte 1 of 2 (AckArray 0x00000006).

A write of 31 bytes or more reports only that a byte was refused, not which byte.

Net Configuration

I2C nets are configured in saved_nets.json on the box. Example net record:

{
  "name": "my_i2c",
  "role": "i2c",
  "instrument": "labjack_t7",
  "pin": "FIO4-FIO5",
  "params": {
    "sda_pin": 4,
    "scl_pin": 5,
    "frequency_hz": 100000,
    "pull_ups": false
  }
}

For Aardvark adapters:

{
  "name": "my_i2c",
  "role": "i2c",
  "instrument": "aardvark",
  "pin": "I2C0",
  "params": {
    "frequency_hz": 400000,
    "pull_ups": true
  }
}

Output Formats

Format	Description
`hex`	Space-separated hex bytes (e.g., `0a 03 ff`)
`bytes`	Raw byte values
`json`	JSON object with data array and metadata

Examples

# List all I2C nets on a box
lager i2c --box my-lager-box

# Show configuration for a specific net
lager i2c MY_I2C --box my-lager-box

# Configure bus speed and pull-ups
lager i2c MY_I2C config --frequency 400k --pull-ups on

# Scan for devices
lager i2c MY_I2C scan

# Read WHO_AM_I register from an accelerometer
lager i2c MY_I2C transfer 1 --address 0x68 --data 0x75

# Write configuration to a sensor
lager i2c MY_I2C write 0x2003 --address 0x76

# Read 6 bytes of sensor data
lager i2c MY_I2C read 6 --address 0x76

Troubleshooting

No Devices Found on Scan

Verify SDA and SCL wiring
Check that pull-up resistors are present (4.7k typical for 100kHz)
For Aardvark: try --pull-ups on to enable internal pull-ups
For LabJack U3: fit external pull-up resistors. The U3 has none, and without them a scan finds no devices
Confirm device power supply is connected

Bus Errors

LabJack T7: The first transaction after connection can return a bus error. This is normal, and the driver handles it automatically
Try reducing frequency with --frequency 100k
Check for bus contention (multiple masters)

NACK Errors

Verify the device address (some datasheets show 8-bit shifted addresses)
Ensure the device is powered and not in reset
Check for address conflicts with other devices on the bus

Notes

Default I2C net can be set with lager defaults add --i2c-net NETNAME
LabJack T7 runs from about 130 Hz to 450 kHz. LabJack U3 runs from about 10 kHz to 150 kHz
config prints the clock rate that a LabJack U3 uses, which can differ from the request
Aardvark adapters support internal pull-ups that can be toggled via config --pull-ups
The transfer command uses I2C repeated start for atomic write-then-read operations

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Arguments

Options

Subcommands

`config`

`scan`

`read`

`write`

`transfer`

Hex Data Formats

Address Format

Frequency Format

Supported Hardware

LabJack U3

Net Configuration

Output Formats

Examples

Troubleshooting

No Devices Found on Scan

Bus Errors

NACK Errors

Notes

See Also

​Syntax

​Arguments

​Options

​Subcommands

​config

​scan

​read

​write

​transfer

​Hex Data Formats

​Address Format

​Frequency Format

​Supported Hardware

​LabJack U3

​Net Configuration

​Output Formats

​Examples

​Troubleshooting

​No Devices Found on Scan

​Bus Errors

​NACK Errors

​Notes

​See Also

Syntax

Arguments

Options

Subcommands

`config`

`scan`

`read`

`write`

`transfer`

Hex Data Formats

Address Format

Frequency Format

Supported Hardware

LabJack U3

Net Configuration

Output Formats

Examples

Troubleshooting

No Devices Found on Scan

Bus Errors

NACK Errors

Notes

See Also