E-Sharp Helpcenter
E-Sharp Helpcenter
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