Categories

Bus Pirate I2C guide

See the latest version in the documentation wiki.

Bus: I2C (eye-squared-see or eye-two-see)
Connections: two pins (SDA/SCL) and ground
Output types: open drain/open collector
Pull-up resistors: pull-ups always required (2K – 10K ohms)
Maximum voltage: 5.5volts (5volt safe)

I2C is a common 2-wire bus for low speed interfaces.

Syntax Description
A/a/@ Toggle auxiliary pin. Capital “A” sets AUX high, small “a” sets to ground. @ sets aux to input (high impedance mode) and reads the pin value.
D/d Measure voltage on the ADC pin (v1+ hardware only).
W/w Capital ‘W’ enables the on-board power supplies. Small ‘w’ disables them. (v1+ hardware only).
{ or [ Issue I2C start condition.
] or } Issue I2C stop condition.
R or r Read one byte, send ACK. (r:1…255 for bulk reads)
0b Write this binary value, check ACK. Format is 0b00000000 for a byte, but partial bytes are also fine: 0b1001.
0h/0x Write this HEX value, check ACK. Format is 0h01 or 0×01. Partial bytes are fine: 0xA. A-F can be lower-case or capital letters.
0-255 Write this decimal value, check ACK. Any number not preceded by 0x, 0h, or 0b is interpreted as a decimal value.
, Value delimiter. Use a coma or space to separate numbers. Any combination is fine, no delimiter is required between non-number values: {0xa6,0, 0 16 5 0b111 0haF}.
& Delay 1uS. (&:1…255 for multiple delays)
(#) Run macro, (0) for macro list
Macro Description
0 Macro menu
1 7bit address search. Find all connected devices by brute force.
2 I2C snooper (alpha testing, unlisted) v2.1+

Configuration options

Speed – I2C has three speed options:~50kHz, ~100kHz, and ~400kHz.

HiZ>m<<<open the mode menu
1. HiZ

4. I2C

(1) >4<<<choose I2C mode
Set speed:
1. 50KHz
2. 100KHz
3. 400kHz
(1) >1<<<choose I2C speed
I2C READY
I2C>

Pull-up resistors

I2C is an open-collector bus, it requires pull-up resistors to hold the clock and data lines high and create the data ‘1’. I2C parts don’t output high, they only pull low, without pull-up resistors there can never be a ‘1’. This will cause common errors such as the I2C address scanner reporting a response at every address. Read more about open collector/open drain bus types, and the Bus Pirate’s on-board pull-up resistors.

ACK/NACK management

These examples read and write from the RAM of a DS1307 RTC chip.

I2C> [ 0xd1 rrrr]
I2C START CONDITION
WRITE: 0xD1 GOT ACK: YES<<<read address
READ: 0×07 ACK <<<sent ACK[
READ: 0x06 ACK
READ: 0x05 ACK
READ: 0x04 NACK <<<last read before STOP,  sent NACK
I2C STOP CONDITION
I2C>

I2C read operations must be ACKed or NACKed by the host (the Bus Pirate). The Bus Pirate automates this, but you should know a few rules about how it works.

The I2C library doesn’t ACK/NACK a read operation until the following command. If the next command is a STOP (or START) the Bus Pirate sends a NACK bit. On all other commands it sends an ACK bit. The terminal output displays the (N)ACK status.

I2C> [0xd1 r:5]
I2C START CONDITION
WRITE: 0xD1 GOT ACK: YES
BULK READ 0×05 BYTES:
0×07 ACK 0×06 ACK 0×05 ACK 0×04 ACK 0×03 NACK
I2C STOP CONDITION
I2C>

Nothing changes for write commands because the slave ACKs to the Bus Pirate during writes. Here’s an example using the bulk read command (r:5).

I2C>[0xd1 r <<<setup and read one byte
I2C START CONDITION
WRITE: 0xD1 GOT ACK: YES
READ: 0x07 *(N)ACK PENDING <<<no ACK sent yet
I2C>r<<<read another byte
ACK <<<ACK for previous byte
READ: 0x06 *(N)ACK PENDING <<<no ACK yet
I2C>] <<<STOP command
NACK <<<next command is STOP, so NACK
I2C STOP CONDITION
I2C>

A consequence of the delayed ACK/NACK system is that partial transactions will leave read operations incomplete.

Here, we setup a read operation ([0xd1) and read a byte (r). Since the Bus Pirate has no way of knowing if the next operation will be another read (r) or a stop condition (]), it leaves the ninth bit hanging. The warning “*(N)ACK PENDING” alerts you to this state.

Our next command is another read (r), so the Bus Pirate ACKs the previous read and gets another byte. Again, it leaves the (N)ACK bit pending until the next command.

The final command is STOP (]). The Bus Pirate ends the read with a NACK and then sends the stop condition.

I2C address search scanner macro

I2C>(1)<<<search for I2C addresses
Searching 7bit I2C address space.
Found devices at:
0xD0(0×68W) 0xD1(0×68R)
I2C>

The address scanner sends every possible I2C address and looks for ACKnowledgments. The scanner displays raw bus byte addresses (0xd0, 0xd1) and the 7bit I2C read (R) and write (W) addresses.

I2C Bus Sniffer macro

The I2C sniffer is implemented in software and seems to work up to 70kHz. It’s still very beta, improvements are probably possible.

  • [/]  – Start/stop bit
  • +/-  – ACK/NACK

I2C start and stop bits are represented by the normal Bus Pirate syntax.

I2C>(2)
I2C bus sniffer, press any key to exit
[0x40-][0x40-0x40-0x30-0x56-0x77-]
I2C>

Sniffed data values are always HEX formatted in user mode. Press any key to exit the sniffer.