i2c - I2C Bus Operations

Description

The i2c command performs I2C bus transactions including reading, writing, and scanning for devices. It provides low-level I2C communication capabilities.

Syntax

i2c --channel <channel_name> [options]

Required Options

Option	Short	Description
`--channel`	`-c`	I2C channel name to use for the transaction

Optional Options

Option	Short	Description
`--address`	`-a`	7-bit I2C device address (prefix with 0x for hex)
`--write`	`-w`	Perform write operation
`--read`	`-r`	Perform read operation
`--scan`	`-s`	Scan I2C bus for devices
`--length`	`-l`	Number of bytes to read (default: 1)
`--data`	`-d`	Data bytes to send (space-separated)

Examples

Scan I2C Bus

i2c --channel "I2C_BUS_1" --scan

Write Single Byte

i2c -c "I2C_BUS_1" -a 0x50 -w -d 0x00

Write Multiple Bytes

i2c -c "I2C_BUS_1" -a 0x50 -w -d 0x00 0xFF 0xAA 0x55

Read Single Byte

i2c -c "I2C_BUS_1" -a 0x50 -r -l 1

Read Multiple Bytes

i2c -c "I2C_BUS_1" -a 0x50 -r -l 16

Write Then Read (Combined Transaction)

i2c -c "I2C_BUS_1" -a 0x50 -w -r -l 4 -d 0x00

Decimal Address and Data

i2c -c "I2C_BUS_1" -a 80 -w -d 0 255

Operation Types

The command supports these I2C operations:

Operation	Flags	Description
Scan	`--scan`	Detect all devices on bus
Send	`--write`	Write data only
Receive	`--read`	Read data only
SendReceive	`--write --read`	Write then read (restart)

Output Format

Sent: 0x00 0xFF
Received: 0x12 0x34 0x56 0x78
Transaction took 3.45 ms

Output Colors

Dark Cyan: Sent data
Dark Magenta: Received data
Blue: Transaction timing

I2C Scan Output

When scanning, the command returns all addresses that ACK:

Sent:
Received: 0x50 0x51 0x68
Transaction took 234.56 ms

Address Format

Addresses can be specified in multiple formats:

Format	Example	Decimal Value
Hexadecimal	`0x50`	80
Hexadecimal	`0x48`	72
Decimal	`80`	80
Decimal	`72`	72

Note: Always use 7-bit addresses (not 8-bit with R/W bit).

Data Format

Data bytes can be specified in multiple formats:

Format	Example
Hexadecimal	`0xFF 0x00 0xAA`
Decimal	`255 0 170`
Mixed	`0xFF 0 0xAA`

Use Cases

Detect Devices

# Scan entire bus
i2c -c "I2C_MAIN" -s

Read EEPROM

# Set address pointer
i2c -c "I2C_MAIN" -a 0x50 -w -d 0x00 0x00

# Read 256 bytes
i2c -c "I2C_MAIN" -a 0x50 -r -l 256

Write Configuration Register

# Write CONFIG register
i2c -c "I2C_MAIN" -a 0x48 -w -d 0x01 0xA0

Read Sensor Data

# Combined transaction (register read)
i2c -c "I2C_MAIN" -a 0x48 -w -r -l 2 -d 0x00

Verify Device Presence

# Quick check if device responds
i2c -c "I2C_MAIN" -a 0x50 -s

Transaction Timing

Typical transaction times:

Operation	Typical Time
Single byte write	2-5 ms
Single byte read	2-5 ms
Bus scan	200-500 ms
16-byte read	5-15 ms
256-byte read	50-150 ms

Error Handling

Common errors:

No option supplied: Must specify scan, read, or write
Address required: Read/write operations need device address
Channel not found: Verify I2C channel name
NACK: Device didn't acknowledge (wrong address or device error)
Timeout: Bus or device not responding
Not connected: Run init command first

I2C Specifications

Speed: Depends on hardware (typically 100kHz or 400kHz)
Address Range: 0x08 to 0x77 (7-bit addresses)
Reserved Addresses: 0x00-0x07, 0x78-0x7F
Maximum Length: Hardware dependent (typically 256 bytes)

Best Practices

Always scan first: Verify devices before read/write
Check timing: Monitor transaction duration
Use correct address: Verify 7-bit address in datasheet
Start simple: Test with single bytes before multi-byte
Handle errors: Check NACK/timeout conditions

Advanced Examples

Sequential Read

# Read temperature sensor
i2c -c "I2C_MAIN" -a 0x48 -w -r -l 2 -d 0x00

Bulk Write

# Program configuration
i2c -c "I2C_MAIN" -a 0x20 -w -d 0x10 0x20 0x30 0x40

Device Identification

# Read ID registers
i2c -c "I2C_MAIN" -a 0x68 -w -r -l 4 -d 0xFA

Notes

Requires an active connection (use init first)
Some devices require specific timing (delays between transactions)
Clock stretching support depends on hardware
Multi-master bus may cause collisions
Consider using high-level module interfaces for complex devices