This guide explains the Bus Pirate I/O pins, describes each menu available from the Bus Pirate terminal, and documents the syntax functions for each protocol library.
The Bus Pirate I/O pins try to be consistent across all libraries, the same pins are used for similar functions. Unused pins are usually in a safe high-impedance state. Modes not shown in the above diagram are similar to other libraries: MIDI=UART; raw2wire=HD44780=PC keyboard=I2C; raw3wire=SPI.
Master-out slave-in (MOSI) is the primary data pin, it’s used for bi-directional data transfer in protocols like I2C and 1-Wire, and as data-out from the Bus Pirate in uni-directional protocols like SPI and asynchronous serial (UART).
Clock is always a clock-out signal from the Bus Pirate, except in the PC keyboard library where the keyboard provides a clock signal to the Bus Pirate.
Master-in slave-out (MISO) is used with protocols that have a dedicated data-input, such as SPI and UART.
Chip select (CS) is an output used to activate the serial interface in SPI-like protocols. Use the auxiliary pin config menu (c) to get manual control of the CS pin through the auxiliary pin commands (a, A, @).
The auxiliary pin (AUX) can be used as an output or input from the Bus Pirate terminal interface with the A, a, and @ commands. It’s useful for protocols that require an additional signal, such as a reset.
A detailed explanation of each Bus Pirate mode follows the break.
Skip to protocol: 1-Wire, UART, I2C, SPI, JTAG, raw 2 wire, raw 3 wire, MIDI, PC keyboard, HD44780 LCDs.
I/O header pin descriptions
| Pin name |
Description (Bus Pirate is the master) |
| MOSI | Master data out, slave in (SPI, JTAG), Serial data (1-Wire, I2C, KB), TX* (UART) |
| CLK | Clock signal (I2C, SPI, JTAG, KB) |
| MISO | Master data in, slave out (SPI, JTAG) RX (UART) |
| CS* | Chip select (SPI), TMS (JTAG) |
| AUX | Auxiliary IO, frequency probe, pulse-width modulator |
| ADC | Voltage measurement probe (max 6volts) |
| Vpu | Voltage input for on-board pull-up resistors (0-5volts). |
| +3.3v | +3.3volt switchable power supply |
| +5.0v | +5volt switchable power supply |
| GND | Ground, connect to ground of test circuit |
Notes: * TX moved from CS to MOSI in firmware v0g.
Menus
Menu options are single character commands that don’t involve data transfers. Enter the character, followed by <enter>, to access the menu. Menus apply to most modes. Some menus are unavailable in some modes, bit order is not configurable for hardware modules.
| Menu | Description |
| ? | Help menu with latest menu and syntax options. |
| I | Hardware/firmware version information. Microcontroller version (firmware v2.1+). |
| M | Set bus mode (1-Wire, SPI, I2C, JTAG, UART, etc). |
| B | Set PC side serial port speed. |
| O | Data display format (DEC, HEX, BIN, or raw). |
| V | Power supply voltage report (v1+ hardware only). |
| F | Measure frequency on the AUX pin. |
| G | Frequency generator/PWM on the AUX pin. |
| C | Toggle AUX control between AUX and CS/TMS pins. |
| L | Set LSB/MSB first in applicable modes. |
| P | Pull-up resistors (V0,V2+ hardware). Power supply configuration. Deprecated (v1 hardware). |
| ~ | Perform a self-test (firmware v2.0+). |
| # | Reset (firmware v2.0+). |
Syntax and macros
A simple syntax is used to communicate with chips over a bus. Syntax characters represent generic functions, such as ‘R’ to read a byte of data, that apply to all bus types. Each protocol is addressed individually below.
Skip to: 1-Wire, UART, I2C, SPI, JTAG, raw 2 wire, raw 3 wire, MIDI, PC keyboard, HD44780 LCDs.
1-Wire
1-Wire requires a single data line (SDA) and a ground connection. The Bus Pirate pin is an open collector and requires a 1K-2K pull-up resistor, maximum 5.5volts (5volt safe).
| 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 [ | 1-Wire bus reset. |
| ] or } | – |
| R or r | Read one byte. (r:1…255 for bulk reads) |
| 0b | Write this binary value. Format is 0b00000000 for a byte, but partial bytes are also fine: 0b1001. |
| 0h/0x | Write this HEX value. 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. 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 |
| Bitwise | |
| ^ | One clock tick, use data state from previous – or _ operation. (^:1…255 for multiple clock ticks) |
| / or \ | – |
| - or _ | Send 1-Wire 1 (-) or 0 (_) bit. |
| ! | Read one bit with clock. |
| . | – |
| Macro | Description |
| 0 | Macro menu |
| 1-50 | Reserved for device address shortcuts. |
| 51 | READ ROM (0×33) *for single device bus |
| 85 | MATCH ROM (0×55) *followed by 64bit address |
| 204 | SKIP ROM (0xCC) *followed by command |
| 236 | ALARM SEARCH (0xEC) |
| 240 | SEARCH ROM (0xF0) |
Asynchronous serial
The serial UART is hardware-based, and operates at 3.3volts (normal pins) or 0-5.5volts (open collector pins with 2K-10K pull-up resistors). Requires two data pins (RX/TX) and a ground connection.
| 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). |
| [ | Open UART, discard received bytes. |
| { | Open UART, display data as it arrives asynchronously. |
| ] or } | Close UART. |
| R or r | Check UART for byte, or fail if empty. (r:1…255 for bulk reads) |
| 0b | Write this binary value. Format is 0b00000000 for a byte, but partial bytes are also fine: 0b1001. |
| 0h/0x | Write this HEX value. 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. 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 |
MIDI
MIDI is a command set used by electronic (music) instruments. It travels over a standard serial UART configured for 31250bps/8/n/1. The MIDI library functions like the asynchronous serial (UART) library.
MIDI is a ring network, each node has an input and output socket. Each node passes messages to the next in the ring. The input and outputs are opto-isolated. The signaling is at 5volts, 5ma (current-based signaling). An adapter is required: example 1, example 2.
I2C
I2C requires two pins (SDA/SCL) and a ground connection. The Bus Pirate pins are open collector and require 2K-10K pull-up resistors, maximum 5.5volts (5volt safe).
| 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) |
Serial Peripheral Interface
SPI requires four pins (MOSI/MISO/CLOCK/CS) and a ground connection. SPI is hardware-based, and operates at 3.3volts (normal pins) or 0-5.5volts (open collector pins with a 2K-10K pull-up resistor, maximum 5.5volts).
| 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). |
| [ | Chip select (CS) active (low). |
| { | CS active (low), show the SPI read byte after every write. |
| ] or } | CS disable (high). |
| R or r | Read one byte by sending dummy byte (0xff). (r:1…255 for bulk reads) |
| 0b | Write this binary value. Format is 0b00000000 for a byte, but partial bytes are also fine: 0b1001. |
| 0h/0x | Write this HEX value. 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. 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 | SPI bus sniffer with configurable CS filter. |
JTAG
JTAG is actually a protocol over SPI. This library performs common JTAG functions, manages the JTAG state machine, and includes a XSVF-based JTAG programmer. 3.3volt I/O, or open collector pins for 0-5volt interfacing (use 2K-10K pull-up resistors, maximum 5.5volts).
| 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). |
| [ | Move JTAG state machine (SM) to INSTRUCTION register. Last bit of byte writes is delayed until leaving the INSTRUCTION register. |
| { | Move JTAG SM to DATA register. |
| ] or } | Move JTAG SM to IDLE register. |
| R or r | Read one byte. (r:1…255 for bulk reads) |
| 0b | Write this binary value. Format is 0b00000000 for a byte, but partial bytes are also fine: 0b1001. |
| 0h/0x | Write this HEX value. 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. 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 |
| Bitwise | |
| ^ | Send one clock tick. (^:1…255 for multiple clock ticks) |
| / or \ | Toggle clock level high (/) and low (\). Includes clock delay (100uS). |
| - or _ | Toggle data state high (-) and low (_). Includes data setup delay (20uS). |
| ! | Read one bit with clock. |
| . | Read data pin state (no clock). |
| Macro | Description |
| 0 | Macro menu |
| 1 | Reset chain |
| 2 | Probe chain |
| 3 | XSVF player. JTAG programmer. |
Raw 2 wire general purpose library
The raw 2 wire library is similar to I2C, but it doesn’t handle acknowledge bits. This library has bitwise pin control. Requires two pins (SDA/SCL) and a ground connection. Open collector pins for 0-5volt interfacing (use 2K-10K pull-up resistors, maximum 5.5volts), or optional 3.3volt I/O mode.
| 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-style start condition. |
| ] or } | Issue I2C-style stop condition. |
| R or r | Read one byte. (r:1…255 for bulk reads) |
| 0b | Write this binary value. Format is 0b00000000 for a byte, but partial bytes are also fine: 0b1001. |
| 0h/0x | Write this HEX value. 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. 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 |
| Bitwise | |
| ^ | Send one clock tick. (^:1…255 for multiple clock ticks) |
| / or \ | Toggle clock level high (/) and low (\). Includes clock delay (100uS). |
| - or _ | Toggle data state high (-) and low (_). Includes data setup delay (20uS). |
| ! | Read one bit with clock. |
| . | Read data pin state (no clock). |
| Macro | Description |
| 0 | Macro menu |
| 1 | ISO7813-3 ATR for smart cards, parses reply bytes. |
| 2 | ISO7813-3 parse only (provide your own ATR command). |
Raw 3 wire general purpose library
The raw 3 wire library is like SPI, but includes bitwise pin control. Requires four pins (MOSI/MISO/CLOCK/CS) and a ground connection. 3.3volt I/O, or open collector pins for 0-5volt interfacing (use 2K-10K pull-up resistors, maximum 5.5volts).
| 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). |
| [ | Chip select (CS) active (low). |
| { | CS active (low), show the SPI read byte after every write. |
| ] or } | CS disable (high). |
| R or r | Read one byte by sending dummy byte (0xff). (r:1…255 for bulk reads) |
| 0b | Write this binary value. Format is 0b00000000 for a byte, but partial bytes are also fine: 0b1001. |
| 0h/0x | Write this HEX value. 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. 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 |
| Bitwise | |
| ^ | Send one clock tick. (^:1…255 for multiple clock ticks) |
| / or \ | Toggle clock level high (/) and low (\). Includes clock delay (100uS). |
| - or _ | Toggle data state high (-) and low (_). Includes data setup delay (20uS). |
| ! | Read one bit with clock. |
| . | Read data pin state (no clock). |
HD44780 Character LCD interface library
The LCD library interfaces common HD44780 LCD character displays. The Bus Pirate doesn’t have enough pins to interface the LCD directly, so the library uses a PCF8574 I2C I/O expander (see our adapter board).
| 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 [ | RS low. Next read/write is a COMMAND. |
| ] or } | RS high. Next read/write is TEXT/DATA. |
| R or r | Read one byte (r:1…255 for bulk reads). |
| 0b | Write this binary value. Format is 0b00000000 for a byte, but partial bytes are also fine: 0b1001. |
| 0h/0x | Write this HEX value. 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. 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 | LCD reset. |
| 2 | Init LCD. |
| 3 | Clear LCD. |
| 4 | Cursor position ex:(4:0). |
| 5 | Write test text. |
| 6 | Write :number test numbers ex:(6:80). |
| 7 | Write :number test characters ex:(7:80). |
| 8 | Insert text at cursor. |
PC keyboard interface library
This library interfaces PC keyboards. A PC keyboard operates at 5volts, and has it’s own internal pull-up resistors to 5volts. The keyboard issues a clock signal that drives all transactions, the library includes a time-out (v0h+?) so the Bus Pirate won’t freeze if the keyboard doesn’t respond.
| Macro | Description |
| 0 | Macro menu |
| 1 | Live keyboard monitor (v0h+) |
—-
The Bus Pirate pinout, menu, and command tables are released into the public domain. Based on the public domain Bus Pirate documentation at Hack a Day.
Tags: Bus Pirate, protocol
No comments
Comments feed for this article