Accordion Helpcenter
Auto Light Dark
Accordion Helpcenter
Auto Light Dark
Breadcrumbs

I2C command

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

Bash
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

Bash
i2c --channel "I2C_BUS_1" --scan

Write Single Byte

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

Write Multiple Bytes

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

Read Single Byte

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

Read Multiple Bytes

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

Write Then Read (Combined Transaction)

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

Decimal Address and Data

Bash
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

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

Read EEPROM

Bash
# 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

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

Read Sensor Data

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

Verify Device Presence

Bash
# 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

  1. Always scan first: Verify devices before read/write

  2. Check timing: Monitor transaction duration

  3. Use correct address: Verify 7-bit address in datasheet

  4. Start simple: Test with single bytes before multi-byte

  5. Handle errors: Check NACK/timeout conditions

Advanced Examples

Sequential Read

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

Bulk Write

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

Device Identification

Bash
# 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