The Bus Pirate universal serial interface

overview450

All future updates will be on the Bus Pirate project page.

Interfacing a new IC can be a hassle. Breadboarding a circuit, writing code, hauling out the programmer, or maybe even prototyping a PCB. We never seem to get it right on the first try.

The ‘Bus Pirate’ is a universal bus interface that talks to most chips from a PC serial terminal, eliminating a ton of early prototyping effort when working with new or unknown chips. Many serial protocols are supported at 0.6-5.5volts, more can be added.

  • 1-Wire
  • I2C
  • SPI
  • JTAG
  • Asynchronous serial
  • MIDI
  • PC keyboard
  • 2- and 3-wire libraries with bitwise pin control

We added other stuff we need, like,

  • 0-6volt measurement probe
  • 1hz-40MHz frequency measurement
  • 1kHz – 4MHz pulse-width modulator, frequency generator
  • On-board multi-voltage pull-up resistors
  • On-board 3.3volt and 5volt power supplies with software reset
  • Macros for common operations
  • Bus traffic sniffer (SPI)
  • A bootloader for easy firmware updates

Since this has been such a useful tool for us, we cleaned up the code, documented the design, and released it here with specs, schematic, and source code.

Hardware and firmware

bpv2goii bpv2a
Hardware v.2go Hardware v.2a
bpv0hw2201 1a220
Hardware v.0 Hardware v.1

The latest firmware and hardware designs can be checked-out from Google Code SVN, or you can browse the SVN repository online.

Supported protocols: 1-Wire, UART, I2C, SPI, JTAG, raw 2 wire, raw 3 wire, MIDI, PC keyboard, HD44780 LCDs.

Protocol and device tutorials

See syntax descriptions below: 1-Wire, UART, I2C, SPI, JTAG, raw 2 wire, raw 3 wire, MIDI, PC keyboard, HD44780 LCDs.

Roadmap and wish lists

Check out the Google Code page for the latest roadmap and wish list.

Pinout descriptions

Pin location diagrams: v0a, v1a, v2a, v2g0.

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.
B Set PC side serial port speed.
O Data display format (DEC, HEX, BIN, or raw).
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.
M Set bus mode (1-Wire, SPI, I2C, JTAG, UART, etc).
L Set LSB/MSB first in applicable modes.
P Pull-up resistors (V0,V2+ hardware). Power supply configuration. Deprecated. (v1 hardware).
V Power supply voltage report (v1+ hardware only).
I Hardware/firmware version information.

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.

Dallas/Maxim 1-Wire Protocol

1-Wire requires a single data line (SDA) and a ground connection. The Bus Pirate pin is high-impedance and requires a 2K-10K 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)

Serial protocol UART

The serial UART is hardware-based, and operates at 3.3volts (normal pins) or 0-5.5volts (high-impedance 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 high-impedance 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 (new in v0h)

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 (high-impedance 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 high-impedance 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

The raw 2 wire library is similar to I2C but includes bitwise pin control. Requires two pins (SDA/SCL) and a ground connection. High-impedance 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

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

This library interfaces PC keyboards.

Macro Description
0 Macro menu
1 Live keyboard monitor (v0h+)

—-

The Bus Pirate pinout, menu, and command tables are released into the public domain.

This program and hardware is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Hack a Day serves up fresh hacks each day, every day from around the web as well as hacking related news.

Send us your hacks










     



Hacks

Resources