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

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]
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 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]
0×07 ACK 0×06 ACK 0×05 ACK 0×04 ACK 0×03 NACK

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

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)

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 bus sniffer, press any key to exit

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

Join the Conversation


  1. Hi Ian,
    While bulk reading I2C, by specifying ‘starting register address’ and making use of ‘repeated start bit’ I am missing first 8 bytes. I mean when I read from 0 then it gives the data from 8th byte.

    What I wrote :
    [0xA0 0x0 0x48 0x69 0x20 0x49 0x32 0x43 0x20 0x66 0x72 0x6F 0x6D 0x20 0x42 0x75 0x73 ]
    WRITE: 0xA0 ACK
    WRITE: 0x00 ACK
    WRITE: 0x48 ACK
    WRITE: 0x69 ACK
    WRITE: 0x20 ACK
    WRITE: 0x49 ACK
    WRITE: 0x32 ACK
    WRITE: 0x43 ACK
    WRITE: 0x20 ACK
    WRITE: 0x66 ACK
    WRITE: 0x72 ACK ??? >>This is where my reading starts<

    What I get back:
    [0xA0 0x0 [0xA1 r:15]
    WRITE: 0xA0 ACK
    WRITE: 0x00 ACK <>
    I2C START BIT <>
    WRITE: 0xA1 ACK
    READ 0x0F BYTES:
    0x72 ACK 0x6F ACK 0x6D ACK 0x20 ACK 0x42 ACK 0x75 ACK 0x73 ACK 0x66 ACK 0x0D ACK 0x0E ACK 0x0F ACK 0x10 ACK 0x11 ACK 0x12 ACK 0x13 NACK

    Am I missing something here ?

  2. When I am reading data from I2C, if I ask the Bus Pirate V3 to read a byte and there is no more data for it to read, it says ACK and just hangs. Is there a way to abort instead of unplugging it from the USB?

      1. Hi Ian,
        It is a SparkFun Model,
        Bus Pirate v3
        Firmware v3.0
        DEVID:0x0447 REVID:0x3043 (B5)

        I will try updating the firmware.

  3. I had the same problem as Jon, SparkFun v3 fw v3.0 it would hang on I2C reads in hardware mode but ok in software mode. I followed the upgrade to v4.1 and the mode choice goes away. Hang problem seems to be fixed for me. It is worth going through the update process.
    After a few hours of playing with some NXP chips, now I actually understand I2C.

Leave a comment

Leave a Reply to Ian Cancel reply

Your email address will not be published. Required fields are marked *

Notify me of followup comments via e-mail. You can also subscribe without commenting.