See the latest version on the documentation wiki.
By popular demand, here’s a second part to the original Bus Pirate 101 tutorial. This time we walk through the Bus Pirate user interface and demonstrate some basic stuff like bus modes, power supplies, pull-up resistors, and number entry. Even if you’ve worked with the Bus Pirate for a while, you might learn some new tricks in this detailed use tutorial written by the primary developer.
Unboxing photo by Uwe Bannow, thanks!
Enter a bus mode
* Syntax error, type ? for help
No mode set, M for mode <<<not allowed in HiZ
The Bus Pirate always starts in high impedance mode (HiZ), a safe mode with all outputs disabled. It’s intended to protect any connected devices from conditions beyond their specifications. If your terminal is blank, press enter to see the command prompt. Type ‘?’ to see a complete list of menu options and syntax available for the current hardware and software.
HiZ>m <<<configure bus mode
(1) >4 <<< select I2C (option 4)
We’ll be using a 24AA I2C EEPROM (data storage chip) on the 3EEPROM explorer board to demonstrate some features. You don’t need the chip to follow along, you won’t damage anything by following the tutorial without a chip.
Press ‘M’ to configure a bus mode. Choose the I2C bus, configure it for software mode, high speed.
The on-board power supplies can be activated outside of HiZ mode.
I2C>w<<<power supplies off
POWER SUPPLIES OFF
Voltage monitors: 5V: 0.0 | 3.3V: 0.0 | VPULLUP: 0.0 |
I2C>W<<<power supplies on
POWER SUPPLIES ON
I2C>v<<<voltage monitor report
Voltage monitors: 5V: 4.9 | 3.3V: 3.2 | VPULLUP: 0.0 |
Capital ‘W’ activates the on-board supplies, small ‘w’ turns them off. Turn the power supplies on, then press v to show a power supply voltage report.
Note that W is syntax and not a menu option, it can be used with other syntax to toggle the power in the middle of complex bus operations.
Some bus types, such as I2C, require a resistor to create a ‘1’ on the bus. This is called an open collector or open drain bus. Without a pull-up resistor, the bus will only read ‘0’. Some bus modes are open collector only (1-Wire, I2C), most have an open collector option.
I2C>v <<<voltage monitor report
Voltage monitors: 5V: 4.9 | 3.3V: 3.2 | VPULLUP: 4.9 |
Connect the Vpu pin of the IO header to a voltage. The on-board pull-up resistors apply the voltage connected to the Vpu pin to the bus pins through 10Kohm resistors. Press v and verify that the Vpullup voltage shows the desired value.
I2C>p <<<configure pull-up resistors
1. Pull-ups off
2. Pull-ups on
(1) >2 <<<enable
Pull-up resistors ON
Press p to configure the on-board pull-up resistors, enable them. For more, see the practical guide to Bus Pirate pull-up resistors.
Macros are preprogrammed shortcuts. Some of the macros available include: smart card interrogation, I2C address scanners, JTAG chain probes, transparent UART bridges, LCD initialization, and bus sniffers.
I2C>(0)<<< show macro menu
1.7bit address search
I2C>(1)<<< macro 1, I2C address search
Searching 7bit I2C address space.
Found devices at:
0xA0(0x50 W) 0xA1(0x50 R)
Type (0) to get a list of macros in any mode. The macro number can be entered in any format, (0x00) and (0b0) are also valid macro entries.
I2C devices respond to a 7bit address. We could look up the address in the datasheet, but instead we’ll use the address scanner macro (1). The Bus Pirate scaned all possible addresses and found the chip at 0x50 (0xa0/0xa1).
If you don’t have an I2C chip attached for this tutorial, the Bus Pirate won’t find any I2C devices. If it finds devices at every address, make sure there’s powered pull-up resistors on the I2C bus pins.
Read more about the I2C address scan.
Number entry and formats
I2C>= <<<convert number formats
CONVERT (1) >10 <<<enter value in any format
Use the ‘=’ menu to convert between formats. Decimal 10 is equivalent to 0x0a (HEX) and 0b1010 (BIN). More about the value converter.
CONVERT (1) >0x0f
0x0f is a HEX formatted value. The leading 0 is optional for values less than 0x10, 0xf is also valid. HEX can also be entered as 0h0f, if that’s more familiar.
CONVERT (1) >0b11
0b11 is a binary 3. It can also be entered with or without leading 0s: 0b00000011, 0b011, etc. More about number entry and output display.
Most syntax can be repeated by appending ‘:’ and a repeat value, the repeat value can be in any number format.
WRITE: 0x02 , 0x03 TIMES ACK <<<‘0b10’ three times
0b10:0x03 uses the repeat command(:) to write 2 (0b10) to the I2C bus three times (:0x03).
I2C>[0xa1 r r r:3]
I2C START BIT
WRITE: 0xA1 ACK
READ: 0x0F ACK<<< read a single byte
READ: 0x0E ACK<<< read a single byte
READ 0x03 BYTES:<<< read multiple bytes
0x03 ACK 0x0E ACK 0x02 NACK
I2C STOP BIT
r is the generic command to read a single byte in all bus modes, it can also be repeated with the ‘:’ command (r:3). The Bus Pirate output is HEX formatted by default, but you can change it to binary or decimal from the output mode menu ‘o’.
When you’re done
(1) ><<<HiZ is the default
When you’re done, press ‘m’. The Bus Pirate immediately turns off all outputs, power supplies, and pull-up resistors, and prompts for a new mode. Choose 1 (or just press enter for the default option) to return to HiZ mode.
Taking it further
In Bus Pirate 101 we looked at the Bus Pirate hardware, installed the driver, and configured the serial terminal. In Bus Pirate 102 we entered a bus mode and demonstrated some basic commands.
There’s also an active Bus Pirate forum.