Bus Pirate I2C

==Overview==
* '''Bus:''' [http://en.wikipedia.org/wiki/I2c I2C] (eye-squared-see or eye-two-see)
* '''Connections: '''two pins (SDA/SCL) and ground
* '''Output types: '''[http://hackaday.com/2009/07/01/mixed-voltage-interfacing-with-the-bus-pirate/ open drain/open collector]
* '''Pull-up resistors:''' [http://dangerousprototypes.com/2009/07/27/bus-pirate-practical-guide-to-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.

==Configuration options==

'' ''

''Speed ''- I2C has three speed options:~50kHz, ~100kHz, and ~400kHz.
<nl2br>HiZ&gt;m'''&lt;&lt;&lt;open the mode menu'''
1. HiZ
…
4. I2C
…
(1) &gt;4'''&lt;&lt;&lt;choose I2C mode'''
Set speed:
1. 50KHz
2. 100KHz
3. 400kHz
(1) &gt;1'''&lt;&lt;&lt;choose I2C speed'''
I2C READY
I2C&gt;</nl2br>
'''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 [http://hackaday.com/2009/07/01/mixed-voltage-interfacing-with-the-bus-pirate/ open collector/open drain bus types], and the Bus Pirate's [http://dangerousprototypes.com/2009/07/27/bus-pirate-practical-guide-to-pull-up-resistors/ on-board pull-up resistors].

==Syntax==

{| border="0"
|-
| 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
| 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.
|-
| 0x
| Write this HEX value, check ACK. Format is 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 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 0xaF}.
|-
| &amp;
| Delay 1uS. (&amp;:1…255 for multiple delays)
|-
| (#)
| Run macro, (0) for macro list
|}

{| border="0"
==Macro==
|-
| 0
| Macro menu
|-
| 1
| 7bit address search. Find all connected devices by brute force.
|-
| 2
| I2C snooper (alpha testing, unlisted) v2.1+
|}

===I2C address search scanner macro===
You can find the [http://en.wikipedia.org/wiki/I%C2%B2C I2C] address for most I2C-compatible chips in the datasheet. But what if you're working with an unknown chip, a dated chip with no datasheet, or you're just too lazy to look it up?

The [http://dangerousprototypes.com/bus-pirate-manual/ Bus Pirate] has a built-in address scanner that checks every possible I2C address for a response. This brute force method is a fast and easy way to see if any chips are responding, and to uncover undocumented access addresses.

I2C chips respond to a 7bit address, so up to 128 devices can share the same two communication wires. An additional bit of the address determines if the operation is a write to the chip (0), or a read from the chip (1).

We connected the Bus Pirate to the [http://dangerousprototypes.com/2009/07/30/prototype-bus-pirate-3eeprom-explorer-board/ 3EEPROM explorer board]. The 7bit base address for the 24LC/AA I2C EEPROM is 0101000 (0x50 in HEX). It answers at the write address 0101000<span style="text-decoration: underline;">'''0'''</span> (0xA0) and the read address 0101000<span style="text-decoration: underline;">'''1'''</span> (0xA1).
<nl2br>I2C&gt;(1)<span style="text-decoration: underline;">'''&lt;&lt;&lt;I2C search macro'''</span>
Searching 7bit I2C address space.
Found devices at:
0xA0(0x50 W) 0xA1(0x50 R)
I2C&gt;</nl2br>
Macro 1 in the I2C library runs the address scanner. The scanner displays the raw addresses the chip acknowledged (0xA0, 0xA1), and the 7bit address equivalent (0x50) with write or read bit indicators (W/R). Datasheets usually list the 7bit address, but the 8bit value is more recognizable on a logic analyzer, snooper, debugger, etc.

<nl2br>I2C> (1)
Searching I2C address space. Found devices at:
Warning: *Short or no pull-up
I2C></nl2br>
The scanner will find a chip at every address if there's no pull-up resistors on the I2C bus. This is a really common error. Since firmware v5.2 the scanner now checks for pull-ups, and exits with an error if the bus isn't pulled up.

===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.
<nl2br>I2C&gt;(2)
I2C bus sniffer, press any key to exit
[0x40-][0x40-0x40-0x30-0x56-0x77-]
I2C&gt;</nl2br>
Sniffed data values are always HEX formatted in user mode. Press any key to exit the sniffer.

'''Notes'''
The sniffer uses a 4096byte output [http://en.wikipedia.org/wiki/Circular_buffer ring buffer]. Sniffer output goes into the ring buffer and gets pushed to the PC when the UART is free. This should eliminate problems with dropped bytes, regardless of UART speed or display mode. A long enough stream of data will eventually overtake the buffer, after which output ends and the MODE LED turns off (v5.2+).

Any commands entered after the sniffer macro will be lost.

Pins that are normally output become inputs in sniffer node. MOSI and CLOCK are inputs in I2C sniffer mode.



==ACK/NACK management==

These examples read and write from the RAM of a DS1307 RTC chip.
<nl2br>I2C&gt; [0xd1 rrrr]
I2C START CONDITION
WRITE: 0xD1 GOT ACK: YES'''&lt;&lt;&lt;read address'''
READ: 0×07 ACK '''&lt;&lt;&lt;sent ACK'''[
READ: 0x06 ACK
READ: 0x05 ACK
READ: 0x04 NACK '''&lt;&lt;&lt;last read before STOP, sent NACK'''
I2C STOP CONDITION
I2C&gt;</nl2br>
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.
<nl2br>I2C&gt; [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&gt;</nl2br>
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).
<nl2br>I2C&gt;[0xd1 r '''&lt;&lt;&lt;setup and read one byte'''
I2C START CONDITION
WRITE: 0xD1 GOT ACK: YES
READ: 0x07 *(N)ACK PENDING '''&lt;&lt;&lt;no ACK sent yet'''
I2C&gt;r'''&lt;&lt;&lt;read another byte'''
ACK '''&lt;&lt;&lt;ACK for previous byte'''
READ: 0x06 *(N)ACK PENDING''' &lt;&lt;&lt;no ACK yet'''
I2C&gt;] '''&lt;&lt;&lt;STOP command'''
NACK '''&lt;&lt;&lt;next command is STOP, so NACK
''' I2C STOP CONDITION
I2C&gt;</nl2br>
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.

==Connections==