mode-guide

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

Dallas/Maxim 1-Wire Protocol

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 (0x33) *for single device bus
85 MATCH ROM (0x55) *followed by 64bit address
204 SKIP ROM (0xCC) *followed by command
236 ALARM SEARCH (0xEC)
240 SEARCH ROM (0xF0)

Asynchronous serial

Serial protocol UART

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

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

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

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

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

Raw 2 wire

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

Raw 3 wire

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

HD44780 LCD (v0h+)

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

PC keyboard

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.

Advertisements