Syntax Reference
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.
CS Select (0)
TX: 0x31
RX: 0x00 0x00 0x00 0x00 0x00
CS Deselect (1)
SPI>
This example syntax sends a bus start, the value 0x31, and then reads 5
bytes, followed by bus stop. Up to 255 characters of syntax may be
entered into the Bus Pirate terminal at once, press enter to execute the
syntax.
It's always best to use the latest firmware, especially in these early days of a new design. There will be continuous improvements and new features. See the upgrade guide for the simple drag and drop bootload process.
Execute syntax
Start a line with [, {, or > to tell the Bus Pirate to send data to an attached device.
[ or { Execute syntax with start
CS Select (0)
TX: 0x03
TX: 0
RX: 0x48 0x65 0x6C 0x6C 0x6F
CS Deselect (1)
SPI>
Start commands generate a start condition (I2C), open a UART, control chip select (SPI) and have similar "start" type functions in every mode. A line beginning with these characters is interpreted as syntax.
> Execute syntax (no start)
TX: 0x55 0xAA
SPI>
While the first two commands actually output something to the bus, this command tells the Bus Pirate to execute syntax without generating any output of its own.
The > command is used to send syntax without sending a start command to the bus.
Bus interaction syntax
A simple syntax manipulates the bus and interacts with chips.
Syntax has 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
CS Select (0)
SPI>
[ generally starts bus activity. In various modes it starts (I2C),
selects (SPI), resets (1-wire), or opens (UART).
] or } Bus stop condition
CS Deselect (1)
SPI>
] generally stops bus activity. In various modes it stops (I2C), deselects
(SPI), or closes (UART).
r Read byte
RX: 0x00
SPI>
r reads a byte from the bus. Use with the repeat command (r:1...255) for bulk reads.
The > before r tells the Bus Pirate we want to send data to the bus.
0b01 Write this binary value
TX: 0b00000001
SPI>
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
TX: 0x01
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 lowercase or uppercase letters.
0-255 Write this decimal value
TX: 1
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 prefix is required.
"abc" Write this ASCII string
TX: 'a' 0x61 'b' 0x62 'c' 0x63
Characters enclosed in " " are sent to the bus as their ASCII equivalent codes.
space Value delimiter
CS Select (0)
TX: 1
TX: 2
TX: 3
RX: 0x00
RX: 0x00
CS Deselect (1)
SPI>
Use a space to separate numbers.
No delimiter is required between non-number commands.
d/D Delay 1uS/MS
Delay: 1us
SPI> >d:10
Delay: 10us
SPI> >D
Delay: 1ms
SPI> >D:10
Delay: 10ms
SPI>
d delays 1us, D delays 1ms.
Use the repeat command for multiple delays.
: Repeat (e.g. r:10)
CS Select (0)
TX: 0x55 0x55
Delay: 2ms
RX: 0x00 0x00 0x00
CS Deselect (1)
SPI>
Many commands can be repeated by adding :, followed by the number of times to repeat. To read five bytes, enter r:5, etc.
The repeat values can also be HEX/DEC/BIN formatted.
. Partial read/write
TX: 0x0A.4
SPI>
Write/read partial bytes (where enabled by hardware) using the . option. 0x75.4 will write 0x5 (4 bits) to the bus.
RX: 0x05.4
SPI>
Read 4 bits from the bus.
TX: 0x0432.12
SPI>
Write 12 bits of 0x5432 to the bus.
TX: 0x0a.4 0x0a.4
SPI>
Partial write/reads can be combined with the repeat command.
v Measure voltage
Volts on IO1: 3.2V
Volts on IO2: 3.2V
Volts on IO3: 3.2V
SPI>
v.x measures the voltage on IO pin x.
a/A/@ Auxiliary pin control (low/HIGH/read)
IO1 set to OUTPUT: 0
UART> >A.1
IO1 set to OUTPUT: 1
UART> >@.1
IO1 set to INPUT: 0
UART>
Sometimes it's useful to control a pin directly when executing bus syntax. a.X, A.X and @.X set pin X low, high and input (HiZ). The @ command also reads and reports the pin state.
Syntax a/A/@ use the a.X notation, the syntax is followed by a . and the pin number to control. This is different than the commands a/A/@, which are followed by a space and the pin number to control.