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

​
Syntax

lager i2c [NETNAME] [OPTIONS] [SUBCOMMAND]

​
Arguments

ArgumentDescription
NETNAMEI2C net name (optional if default is set via lager defaults add --i2c-net)

​
Options

OptionDescription
--box BOXLagerbox 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]
OptionDescription
--box BOXLagerbox name or IP address
--frequency FREQClock frequency (e.g., 100k, 400k, 1M)
--pull-ups on|offEnable/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]
OptionDescriptionDefault
--box BOXLagerbox name or IP address
--start ADDRStart address in hex0x08
--end ADDREnd address in hex0x77
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]
ArgumentDescription
NUM_BYTESNumber of bytes to read (0 or more)
OptionDescriptionDefault
--box BOXLagerbox name or IP address
--address ADDRDevice address in hex (e.g., 0x48)Required
--frequency FREQClock frequency override (e.g., 100k, 400k)
--format FORMATOutput format: hex, bytes, jsonhex
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]
ArgumentDescription
DATAHex data to write (e.g., 0x0A03, 0a 03, 0a,03)
OptionDescriptionDefault
--box BOXLagerbox name or IP address
--address ADDRDevice address in hex (e.g., 0x48)Required
--data-file PATHFile containing binary data to write
--frequency FREQClock frequency override
--format FORMATOutput format: hex, bytes, jsonhex
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]
ArgumentDescription
NUM_BYTESNumber of bytes to read (0 or more)
OptionDescriptionDefault
--box BOXLagerbox name or IP address
--address ADDRDevice address in hex (e.g., 0x48)Required
--data DATAHex data to write before reading (e.g., register address)
--data-file PATHFile containing data to write before reading
--frequency FREQClock frequency override
--format FORMATOutput format: hex, bytes, jsonhex
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:
FormatExampleParsed As
Prefixed continuous0x0a03[0x0a, 0x03]
Unprefixed continuous0a03[0x0a, 0x03]
Space-separated0a 03[0x0a, 0x03]
Comma-separated0a,03[0x0a, 0x03]
Single byte0x0a[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:
FormatExampleValue
Hex prefixed0x4872
Hex unprefixed4872
Decimal7272

​
Frequency Format

Clock frequencies accept numeric values with optional suffixes:
FormatExampleValue
Plain Hz100000100 kHz
kHz suffix100k100 kHz
MHz suffix1M1 MHz
Hz suffix400000hz400 kHz

​
Supported Hardware

AdapterPinsPull-upsNotes
LabJack T7Configurable FIO pins (e.g., FIO4/FIO5)External only~450 kHz max (throttle=0)
Aardvark USBFixed SDA/SCLInternal (switchable)Up to 800 kHz
FT232HConfigurableExternal onlyMPSSE-based I2C

​
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

FormatDescription
hexSpace-separated hex bytes (e.g., 0a 03 ff)
bytesRaw byte values
jsonJSON 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
  • Confirm device power supply is connected

​
Bus Errors

  • LabJack T7: The first transaction after connection may return a bus error; this is normal and handled 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 operates at ~450 kHz regardless of requested frequency due to hardware limitations
  • 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