Bus Pirate menu options guide

From DP

Jump to: navigation , search

This guide was last updated to firmware v5.6.

Menu options are single character commands that configure the Bus Pirate. Type a letter, followed by <enter>, to access the menu. Some options are unavailable in some modes and on some hardware.

A simple syntax is used to interact with chips. Syntax characters have the same general function in each bus mode, such as 'R' to read a byte of data.

Up to 256 characters of menu and syntax stuff can be entered into the Bus Pirate terminal at once, press enter to execute the syntax.

Contents

Menu options overview

Menu options are single character commands that configure the Bus Pirate. Press enter to show the command prompt if your terminal is blank.

HiZ> p
Command not used in this mode
HiZ>

Enter a command, followed by <enter>, to access the menu. Most configuration and option prompts have a default value shown in (). Press enter to select the default option. Some options are unavailable in some modes, for example bit order configuration and pull-up resistors.

Previous version guides: v2.1.

Configuration commands

? Help menu with latest menu and syntax options

Bpv52-help.png

Print a help screen with all available menu and syntax options in the current firmware and hardware.

I Hardware, firmware, microcontroller version information

HiZ> i
Bus Pirate v3a <<<hardware version
Firmware v5.2RC (r413) Bootloader v4.3 <<<firmware and bootloader version
DEVID:0x0447 REVID:0x3043 (B5) <<<PIC device ID and revision
http://dangerousprototypes.com <<<project webpage
HiZ>

The information menu displays the hardware, firmware, and microcontroller version.

*----------*
POWER SUPPLIES OFF
Voltage monitors: 5V: 0.0 | 3.3V: 0.0 | VPULLUP: 0.0 |
a/A/@ controls AUX pin
Normal outputs (H=V+, L=GND)
Pull-up resistors ON
MSB set: MOST sig bit first

* ----------*
RAW2WIRE>

If a bus mode is configured additional information about the configuration options is printed.

M Set bus mode (1-Wire, SPI, I2C, JTAG, UART, etc)

HiZ> m
1. HiZ
2. 1-WIRE
3. UART
4. I2C
5. SPI
6. 2WIRE
7. 3WIRE
8. KEYB
9. LCD
x. exit(without change)

(1)>

Select a bus mode. The command resets the Bus Pirate and immediately disables all pins, pull-up resistors, and power supplies.

The default mode is HiZ, a safe mode with all pins set to high-impedance and all peripherals disabled.

H Command history

SPI> h
1. h
2. [10 r:3]
3. m
4. i
x. exit

(0)> 2 <<<replay #2
CS ENABLED
WRITE: 0x0A
READ: 0x00 0x00 0x00
CS DISABLED
SPI>

The previous 10 commands can be replayed from the command history menu. Firmware v5.0+.

c/C Toggle AUX control between AUX and CS/TMS pins

3WIRE> c
a/A/@ controls AUX pin
3WIRE> C
a/A/@ controls CS/TMS pin
3WIRE>

Sometimes it's useful to control the CS pin from the user terminal. The c/C configures the a/A/@ commands to control the AUX or CS pins.

The current AUX pin configuration is displayed on the extended information screen.

l/L Set MSB/LSB first in applicable modes

3WIRE> l
MSB set: MOST sig bit first
3WIRE> L
MSB set: LEAST sig bit first
3WIRE>

The l/L command determines the bit order for reading and writing bytes in some bus modes. The bitorder command is available in all modes (firmware v5.3+).

The current bit order configuration is displayed on the extended information screen.

O Data display format (DEC, HEX, BIN, or raw)

HiZ> o
1. HEX
2. DEC
3. BIN
4. RAW

(1)>
Display format set
HiZ>

The Bus Pirate can display values as hexadecimal, decimal, binary, and a raw ASCII byte. Change the setting in the data display format menu (o). The default display format is HEX.

The RAW display mode sends values to the terminal as raw byte values without any text conversion. This is useful for ASCII serial interfaces. It can also be used to speed up the display of bus sniffers and other high-speed functions where converting raw bytes to text takes too much time. Adjust the display format in your serial terminal to see the raw values as HEX/DEC/BIN.

B Set PC side serial port speed

HiZ> b
Set serial port speed: (bps)
1. 300
2. 1200
3. 2400
4. 4800
5. 9600
6. 19200
7. 38400
8. 57600
9. 115200
10. BRG raw value

(9)>
Adjust your terminal
Space to continue
HiZ>

Adjust the speed of the serial port facing the computer (and USB->serial converter chip).

After choosing a speed you must adjust the serial terminal and press space to continue. The Bus Pirate will pause until the space key is pressed to verify that the terminal speed is correct.

(9)> 10
Enter raw value for BRG

(34)> 34
Adjust your terminal
Space to continue
HiZ>

Since v5.2 there is an option to set a custom baud rate with a raw BRG value. The value can be calculated according to the datasheet or with a utility (key constants: PIC24, 32MHz/16MIPS, BRGH=1).

  • 230400 baud is '16' (2.2% error)
  • 460800 baud is '8' (3.3% error)
  • 921600 baud is '3' (8.51% error)

One thing to note is that on some early PIC revisions (A3) the UART is weird and the exact values won't work. On these chips try a value +/-1.

~ Perform a self-test

HiZ> ~
Disconnect any devices
Connect (Vpu to +5V) and (ADC to +3.3V)
Space to continue

Perform a hardware self-test. Please see the Bus Pirate self-test guide. Firmware v2.0+, hardware v2go and v3 only.

# Reset

HiZ> #
Are you sure? y
RESET

Bus Pirate v3a
Firmware v5.2RC (r413) Bootloader v4.3
DEVID:0x0447 REVID:0x3043 (B5)
http://dangerousprototypes.com
HiZ>

Reset the Bus Pirate. Firmware v2.0+

$ Jump to bootloader

HiZ> $
Are you sure? y
BOOTLOADER

Enter the bootloader for a firmware update without connecting the PGC and PGD pins. Remember to disconnect your terminal program before the upgrade.

BL4+BL4+

Bootloader v4.3+ will respond with a version string if a key is pressed while it's active.

Bootloader v4+, firmware v4+. Bus Pirate upgrade instructions.

Utilities

w/W Power supplies (off/ON)

1-WIRE> w
POWER SUPPLIES OFF
1-WIRE> W
POWER SUPPLIES ON
1-WIRE>

Toggle the switchable 3.3volt and 5.0volt power supplies with the w/W command. Capital 'W' enables the supplies, lowercase 'w' disables them. The power supplies on the Bus Pirate v2go and v3 can supply up to 150mA. The current configuration is displayed on the extended information screen.

1-WIRE> v
Pinstates:

1.(BR)
2.(RD)
3.(OR)
4.(YW)
5.(GN)
6.(BL)
7.(PU)
8.(GR)
9.(WT)
0.(Blk)
GND
3.3V
5.0V
ADC
VPU
AUX
-
OWD
-
-
P
P
P
I
I
I
I
I
I
I
GND
3.34V
4.83V
0.00V
0.00V
L
L
L
L
L
1-WIRE>

Use the power supply voltage report (V) to see the current voltage at each power supply. The 5.0volt supply is powered by the 5.0volt USB supply, so it's normal for it to fall below 5.0volts under load.

V Power supply voltage report

1-WIRE> v
Pinstates:

1.(BR)
2.(RD)
3.(OR)
4.(YW)
5.(GN)
6.(BL)
7.(PU)
8.(GR)
9.(WT)
0.(Blk)
GND
3.3V
5.0V
ADC
VPU
AUX
-
OWD
-
-
P
P
P
I
I
I
I
I
I
I
GND
3.34V
5.00V
0.00V
0.00V
L
L
L
L
L
1-WIRE>

The voltage report shows the current state of all the Bus Pirate pins and peripherals.

The first line is the pin number, according to the silk screen on the v3 PCB, and the Seeed Studio probe wire color. The ADC and 3.3V pins are swapped on the v2go and the display is incorrect.

The second line is the pin function in the current bus mode. The power supplies (3.3v, 5.0v), ADC, Vpu, and AUX pins are available in all modes. The other four pins will differ depending on the mode. In 1-Wire mode only one pin is used, one wire data (OWD).

The third line shows the current direction of each pin. I is an input pin, O is an output pin, P is a power supply.

The fourth line shows the current state of each pin. A voltage measurement is displayed for analog pins. The current pin reading, H high and L low, is printed for each digital pins.

p/P Pull-up resistors

2WIRE> p
Pull-up resistors OFF
2WIRE> P
Pull-up resistors ON
Warning: no voltage on Vpullup pin<<<check voltage report
2WIRE>

p and P toggle the pull-up resistors off and on. V0,v2+ hardware.

The on-board pull-up resistors must be powered through the Vpullup pin of the IO header. A warning is displayed if there's no voltage on the Vpullup pin (v5.2+). Check the voltage report (V) and verify that Vpu is attached to a power supply. See the practical guide to Bus Pirate pull-up resistors for a simple introduction.

Select output type:
1. Open drain (H=Hi-Z, L=GND)
2. Normal (H=3.3V, L=GND)

(1)> 2
Ready.
2WIRE> P
WARNING: pins not open drain (HiZ)<<<warns of normal pin type
Pull-up resistors ON
2WIRE>

Pull-up resistors are generally used with open collector/open drain bus types. A warning is displayed when the pull-ups are enabled if the Bus Pirate is configured for normal pin output.

The current configuration is displayed on the extended information screen.

e pull-up voltage select

V4 hardware only

I2C>e
Select Vpu source
1) None or external
2) Onboard 3V3 Vreg
3) Onboard 5V Vreg
(1)>2
3V3 on-board pullup voltage enabled
I2C>

The voltage applied to the pull-up resistors can be toggled between 3.3volts, 5volts, and the Vpu pin of the IO header, using the e menu. This is available on v4 hardware only.

F Measure frequency on the AUX pin

2WIRE> f
Frequency on AUX pin: autorange 50,283 Hz
2WIRE>

Measures frequency from 0Hz to 40MHz on the AUX pin, the method is an actual 1 second tick count. If the frequency is lower than a few MHz, the Bus Pirate does an 'autorange' and measures the frequency again for an additional second.

G Frequency generator/PWM on the AUX pin

2WIRE> g
1KHz-4,000KHz PWM/frequency generator
Frequency in KHz
(50)> 2000
Duty cycle in %
(50)>
PWM active
2WIRE> g
PWM disabled
2WIRE>

Enable the frequency generator with g, then set frequency and duty cycle. Frequencies from 1kHz to 4MHz are possible. Use g again to disable the PWM.

Note that the resolution at 4MHz is only 1 bit. Anything other than 50% duty cycle will be 100% off or 100% on.

S Servo

1-WIRE>S
Position in degrees
(90)>20
Servo active
(x)>100
Servo active
(x)>30
Servo active
(x)>
1-WIRE>S
PWM disabled
1-WIRE>

S positions the servo arm to the desired angle, 0-180 degrees. The servo value can be updated as needed, press enter or x to exit. Use 'S' or 'g' again to disable the servo.

1-WIRE>S 90 %:5000 S 180
Servo active
DELAY 5000ms
Servo active
1-WIRE>

Example of multiple servo positions with delay

Firmware 5.5+

NOTE1: Most servos draw more current than the Bus Pirate can supply!! Use an external power supply instead.

=X Convert X to HEX/DEC/BIN number format

2WIRE> =0b110
0x06 = 6 = 0b00000110
2WIRE> =0xa
0x0A = 10 = 0b00001010
2WIRE> =12
0x0C = 12 = 0b00001100
2WIRE>

Base conversion command, available in all modes. Press '=' and enter any byte value to see the HEX/DEC/BIN equivalent. Firmware v2.1+

To change the Bus Pirate output display format see the O command.

|X Reverse bits in byte X

I2C> |0b10101010
0x55 = 85 = 0b01010101
I2C> |0b10000000
0x01 = 1 = 0b00000001
I2C> |1
0x80 = 128 = 0b10000000
I2C>

Reverse bit order in byte X. Displays the HEX/DEC/BIN value of the reversed byte. (Firmware v5.3+)

To change the Bus Pirate read/write bit order see the l/L command.

S BASIC script engine

2WIRE> s
2WIRE(BASIC)> list

65535 bytes.
Ready.
2WIRE(BASIC)>

Simple BASIC scripts can automate repetitive and tedious tasks. Firmware v5.0+. Bus Pirate BASIC script reference

d/D Measure from voltage probe (once/CONTINUOUS)

HiZ> d
VOLTAGE PROBE: 3.31V
HiZ> D

A lowercase d takes a measurement from the voltage measurement probe (ADC pin on the IO header).

HiZ> D
VOLTMETER MODE
Any key to exit
VOLTAGE PROBE: 3.30V

A capital D takes continuous measurements from the voltage probe, press any key to exit.

The Bus Pirate voltage probe can measure up to 6.0volts (max 6.6volts, but with some margin for error).

a/A/@ Control axillary pin (low/HIGH/read)

UART> A
AUX HIGH
UART> a
AUX LOW
UART> @
AUX INPUT/HI-Z, READ: 0
UART>

The axillary pin is a general purpose digital pin that can be controlled from the Bus Pirate terminal. Capital A makes it a 3.3volt output (25mA max). Lowercase a makes it sink to ground (25mA max). @ makes in an input and reads the current state (5volt maximum input).

a/A/@ can also be used to control the CS pin using the c/C commands.

Bus interaction commands

These commands actually manipulate the bus and interacts with chips. These commands have the same general function in each bus mode, such as 'R' to read a byte of data. See the individual bus mode guides for each protocol.

{ or [ Bus start condition.

I2C> [
I2C START BIT
I2C>

This command generally starts bus activity. In various modes it starts (I2C), selects (SPI), resets (1-wire), or opens (UART).

] or } Bus stop condition.

SPI> ]
CS DISABLED
SPI>

This command generally stops bus activity. In various modes it stops (I2C), deselects (SPI), or closes (UART).

r Read byte

I2C> r
READ: 0x00
I2C> r:3
READ: ACK 0x00 ACK 0x00 ACK 0x00
I2C>

r reads a byte from the bus. Use with the repeat command (r:1…255) for bulk reads.

0b01 Write this binary value

I2C> 0b1001
WRITE: 0x09 ACK
I2C> 0b1001:2
WRITE: 0x09 ACK 0x09 ACK
I2C>

Enter a binary value to write it to the bus.

Binary values are commonly used in electronics because the 1's and 0's correspond to register 'switches' that control various aspects of a device. Enter a binary number as 0b and then the bits. Padding 0's are not required, 0b00000001=0b1. Can be used with the repeat command.

0x01 Write this HEX value

SPI> 0x15
WRITE: 0x15
SPI> 0xfa:5
WRITE: 0xFA 0xFA 0xFA 0xFA 0xFA
SPI>

Enter a HEX value to write it to the bus.

Hexadecimal values are base 16 numbers that use a-f for the numbers 10-15, this format is very common in computers and electronics. Enter HEX values as shown above, precede the value with 0x or 0h. Single digit numbers don't need 0 padding, 0x01 and 0x1 are interpreted the same. A-F can be lower-case or capital letters.

0-255 Write this decimal value

SPI> 18
WRITE: 0x12
SPI> 13:5
WRITE: 0x0D 0x0D 0x0D 0x0D 0x0D
SPI>

Any number not preceded by 0x, 0h, or 0b is interpreted as a decimal value and sent to the bus.

Decimal values are common base 10 numbers. Just enter the value, no special designator is required.

"abc" Write this ASCII string

SPI> "abcd"
WRITE: "abcd"
SPI>

The ASCII values enclosed in "" are sent to the bus. Firmware v5.0+.

space/, Value delimiter

SPI> [1 2,3rr]
CS ENABLED
WRITE: 0x01
WRITE: 0x02
WRITE: 0x03
READ: 0x0A
READ: 0x0A
CS DISABLED
SPI>

Use a coma or space to separate numbers. Any combination is fine, no delimiter is required between non-number values.

&/% Delay 1uS/MS

SPI> &
DELAY 1us
SPI> &:10
DELAY 10us
SPI> %
DELAY 1ms
SPI> %:10
DELAY 10ms
SPI>

& delays 1us, % delays 1ms. Use the repeat command for multiple delays.

: Repeat (e.g. r:10)

SPI> &:10
DELAY 10us
SPI> r:0b10
READ: 0x00 0x00
SPI> 5:0x3
WRITE: 0x05 0x05 0x05
SPI>

Many Bus Pirate commands can be repeated by adding ': ' to a command, followed by the number of times to repeat the command. To read five byte, enter r:5, etc. The repeat values can be HEX/DEC/BIN.

; Partial (<16 bit) read/write (e.g. 0x55;3)

2WIRE> 0xaa;4
WRITE: 0x0A;4

Will write 0x0a (4 bits) to the bus.

2WIRE> 0xFFFF;12
WRITE: 0x0FFF;12

Will write 0x0FFF (12 bits) to the bus.

2WIRE> 0x55:4;2
WRITE: 0x01;2 0x01;2 0x1;2 0x01;2

Can be combined with the repeat command.

NOTE: works currently only with the raw2wire and raw3wire busses.

Bitwise bus commands

Bitwise commands are only available in certain bus modes.

^ Send one clock tick

2WIRE> ^
CLOCK TICK
2WIRE>

Send one clock tick. ^:1…255 for multiple clock ticks.

/ or \ Toggle clock level high (/) and low (\)

2WIRE> /\
CLOCK, 1
CLOCK, 0
2WIRE>

Set the clock signal high or low. Includes clock delay.

- or _ Toggle data state high (-) and low (_)

2WIRE> -_
DATA OUTPUT, 1
DATA OUTPUT, 0
2WIRE>

Set the data signal high or low. Includes data setup delay

! Read one bit with clock

2WIRE> !
READ BIT:
0 *pin is now HiZ
2WIRE>

Send one clock tick and read one bit from the bus.

On a bus with a bi-directional data line (raw2wire, 1-Wire), the data pin is left as a high-impedance input after this command.

. Read data pin state (no clock)

2WIRE> .
0 *pin is now HiZ
2WIRE>

Make the data pin an input and read, but do not send a clock. This can be used as /.\ to achieve the same thing as the ! command.

On a bus with a bi-directional data line (raw2wire, 1-wire), the data pin is left as a high-impedance input after this command.

Macros, user macros

Macros perform complex actions, like scanning for I2C addresses, interrogating a smart card, or probing a JTAG chain. Macros are numbers entered inside (). Macro (0) always displays a list of macros available in the current bus mode.

(0) List mode macros

I2C> (0)
0.Macro menu
1.7bit address search
2.I2C sniffer
I2C>

Macro (0) always displays a list of macros available in the current bus mode.

(#) Run macro

I2C>(1)<<<I2C search macro
Searching 7bit I2C address space.
Found devices at:
0xA0(0x50 W) 0xA1(0x50 R)
I2C>

Execute a macro by typing the macro number between ().

<x= > Assign user macro

I2C> <1=[0xa1 r:8]>
I2C>

5 user macros can be stored to automate common commands. Each position can store 32 chars (including space).

<0> List user macros

I2C> <0>
1. <[0xa1 r:8]>
2. <>
3. <>
4. <>
5. <>
I2C>

User macro <0> lists the currently stored use macros.

<#> Run user macro #

I2C> <1>
I2C> [0xa1 r:8]

Enter the macro number to recall the command. Press enter to execute.