See the latest version in the documentation wiki.

The Bus Pirate’s new binary modes provide a consistent, logical way to script actions from Python, Perl, etc. We already introduced the new binary bitbang and SPI modes, today we’ll document the binary I2C mode. Binary I2C will be in the v2.6 firmware release, for now you can grab the v2.6 nightly compile.

We want your scripts! If you script something for any of the new modes, in any language, we’d like to host it in the example scripts folder. We’ll send Bus Pirate probe cable kits to two authors of Bus Pirate binary mode scripts posted by the end of next week (October 24th, 2009).

Binary I2C mode specification follows after the break.

Binary I2C mode command table

• 00000000 – Exit to bitbang mode, responds “BBIOx”
• 00000001 – Mode version string (I2C1)
• 00000010 – Send I2C start bit
• 00000011 – Send I2C stop bit
• 00000100 – I2C read byte
• 00000110 – Send I2C ACK bit
• 00000111 – Send I2C NACK bit
• 00001111 – Start bus sniffer
• 0001xxxx – Bulk transfer, send 1-16 bytes (0=1byte!)
• 0100wxyz – Configure peripherals w=power, x=pullups, y=AUX, z=CS
• 011000xx – Set I2C speed, 3=~400kHz, 2=~100kHz, 1=~50kHz, 0=~5kHz

Enter binary I2C mode by first entering bitbang mode, then send 0×02 to enter I2C mode.

Most I2C mode commands are a single byte. Commands generally return 1 for success, 0 for failure.

00000000 – Exit to bitbang mode, responds “BBIOx”

This command resets the Bus Pirate into raw bitbang mode from the user terminal. It also resets to raw bitbang mode from raw I2C mode, or any other protocol mode. This command always returns a five byte bitbang version string “BBIOx”, where x is the current bitbang protocol version (currently 1).

00000001 – Display mode version string, responds “I2Cx”

Once in binary I2C mode, send 0×01 to get the current mode version string. The Bus Pirate responds ‘I2Cx’, where x is the raw I2C protocol version (currently 1). Get the version string at any time by sending 0×01 again. This command is the same in all binary modes, the current mode can always be determined by sending 0×01.

00000010 – I2C start bit

Send an I2C start bit. Responds 0×01.

00000011 – I2C stop bit

Send an I2C stop bit. Responds 0×01.

00000100 – I2C read byte

Reads a byte from the I2C bus, returns the byte. You must ACK or NACK each byte manually!

00000110 – ACK bit

Send an I2C ACK bit after reading a byte. Tells a slave device that you will read another byte. Responds 0×01.

00000111 – NACK bit

Send an I2C NACK bit after reading a byte. Tells a slave device that you will stop reading, next bit should be an I2C stop bit. Responds oxo1.

00001111 – Start bus sniffer

Sniff traffic on an I2C bus.

• [/]  – Start/stop bit
• \ – escape character precedes a data byte value
• +/-  – ACK/NACK

Sniffed traffic is encoded according to the table above. Data bytes are escaped with the ‘\’ character. Send a single byte to exit, Bus Pirate responds 0×01 on exit.

0001xxxx – Bulk I2C write, send 1-16 bytes (0=1byte!)

Bulk I2C allows multi-byte writes. The Bus Pirate expects xxxx+1 data bytes. Up to 16 data bytes can be sent at once. Note that 0000 indicates 1 byte because there’s no reason to send 0.

BP replies 0×01 to the bulk I2C command. After each data byte the Bus Pirate returns the ACK (0×00) or NACK (0×01) bit from the slave device.

0100wxyz – Configure peripherals w=power, x=pullups, y=AUX, z=CS

Enable (1) and disable (0) Bus Pirate peripherals and pins. Bit w enables the power supplies, bit x toggles the on-board pull-up resistors, y sets the state of the auxiliary pin, and z sets the chip select pin. Features not present in a specific hardware version are ignored. Bus Pirate responds 0×01 on success.

Note: CS pin always follows the current HiZ pin configuration. AUX is always a normal pin output (0=GND, 1=3.3volts).

NOTE: due to a typo this was previously command 0110.

0110000x – Set I2C speed, 1=high (50kHz) 0=low (5kHz)

011000xx – Set I2C speed, 3=~400kHz, 2=~100kHz, 1=~50kHz, 0=~5kHz (updated in v4.2 firmware)

The last bit of the speed command determines the I2C bus speed. Binary mode currently uses the software I2C library, though it may be configurable in a future update. Startup default is high-speed. Bus Pirate responds 0×01 on success.

NOTE: due to a typo this was previously command 0100.

See the latest version in the documentation wiki.

There’s two new binary I/O libraries in the v2.3 Bus Pirate firmware. Raw bitbang mode provides direct control over the Bus Pirate pins and hardware using a simple single-byte protocol. We discussed the new raw SPI mode yesterday.

Hopefully the raw access modes inspire some interesting new Bus Pirate tools using PC software. There’s already a patch for AVRDude AVR programmer in the works.

Full documentation of the raw bitbang binary I/O mode after the break.

Commands

• 00000000 – Reset, responds “BBIO1″
• 00000001  – Enter binary SPI mode, responds “SPI1″
• 00000010 – Enter binary I2C mode, responds “I2C1″
• 00000011 – Enter binary UART mode, responds “ART1″
• 00000100 – Enter binary 1-Wire mode, responds “1W01″
• 00000101 – Enter binary raw-wire mode, responds “RAW1″
• 0000xxxx – Reserved for future raw protocol modes
• 00001111 – Reset Bus Pirate (returns to user terminal)
• 00010000 – Short binary mode self-test
• 00010001 – Long test (requires jumpers between +5 and Vpu, +3.3 and ADC)
• 00010010 – Setup pulse-width modulation (requires 5 byte setup)
• 00010011 – Clear/disable PWM
• 00010100 – Take voltage probe measurement (returns 2 bytes)
• 010xxxxx  – Set pins as input(1) or output(0), responds with read
• 1xxxxxxx  – Set pins high (1) or low (0), responds with read

The bitbang protocol uses a single byte for all commands. The default start-up state is pin input (HiZ).

00000000 – Reset, responds “BBIO1″

This command resets the Bus Pirate into raw bitbang mode from the user terminal. It also resets to raw bitbang mode from raw SPI mode, or any other protocol mode. This command always returns a five byte bitbang version string “BBIOx”, where x is the current protocol version (currently 1).

Some terminals send a NULL character (0×00) on start-up, causing the Bus Pirate to enter binary mode when it wasn’t wanted. To get around this, you must now enter 0×00 at least 20 times to enter raw bitbang mode.

Note: The Bus Pirate user terminal could be stuck in a configuration menu when your program attempts to enter binary mode. One way to ensure that you’re at the command line is to send <enter> at least 10 times, and then send ‘#’ to reset. Next, send 0×00 to the command line 20+ times until you get the BBIOx version string.

00000001  – Enter binary SPI mode, responds “SPI1″

After entering bitbang mode, you can enter other binary protocol modes. Binary SPI mode is documented here.

00000010 – Enter binary I2C mode, responds “I2C1″

Binary I2C mode is documented here.

00000011 – Enter binary UART mode, responds “ART1″

Binary UART mode is documented here.

00000100 – Enter binary 1-Wire mode, responds “1W01″

Binary 1-Wire mode is documented here.

00000101 – Enter binary raw-wire mode, responds “RAW1″

Binary raw-wire mode is documented here.

00001111 – Reset Bus Pirate

The Bus Pirate responds 0×01 and then performs a complete hardware reset. The hardware and firmware version is printed (same as the ‘i’ command in the terminal), and the Bus Pirate returns to the user terminal interface. Send 0×00 20 times to enter binary mode again.

Note: there may be garbage data between the 0×01 reply and the version information as the PIC UART initializes.

0001000x – Bus Pirate self-tests

Binary self tests are documented here. Available only in v2go and v3 hardware.

00010010 – Setup pulse-width modulation (requires 5 byte setup)

Configure and enable pulse-width modulation output in the AUX pin. Requires a 5 byte configuration sequence. Responds 0×01 after a complete sequence is received. The PWM remains active after leaving binary bitbang mode!

Equations to calculate the PWM frequency and period are in the PIC24F output compare manual. Bit 0 and 1 of the first configuration byte set the prescaler value. The Next two bytes set the duty cycle register, high 8bits first. The final two bytes set the period register, high 8bits first.

00010011 – Clear/disable PWM

Clears the PWM, disables PWM output. Responds 0×01.

00010100 – Take voltage probe measurement (returns 2 bytes)

Take a measurement from the Bus Pirate voltage probe. Returns a 2 byte ADC reading, high 8bits come first. To determine the actual voltage measurement: (ADC/1024)*3.3volts*2; or simply (ADC/1024)*6.6.

010xxxxx  – Configure pins as input(1) or output(0): AUX|MOSI|CLK|MISO|CS

Configure pins as an input (1) or output(0). The pins are mapped to the lower five bits in this order:

AUX|MOSI|CLK|MISO|CS.

The Bus pirate responds to each direction update with a byte showing the current state of the pins, regardless of direction. This is useful for open collector I/O modes.

Note: updated to correct order on 16/JAN/10

1xxxxxxx   – Set on (1) or off (0): POWER|PULLUP|AUX|MOSI|CLK|MISO|CS

The lower 7bits of the command byte control the Bus Pirate pins and peripherals. Bitbang works like a player piano or bitmap. The Bus Pirate pins map to the bits in the command byte as follows:

1|POWER|PULLUP|AUX|MOSI|CLK|MISO|CS

The Bus pirate responds to each update with a byte in the same format that shows the current state of the pins.

Note: updated to correct order on 16/JAN/10

Key Points

• Send 0×00 to the user terminal 20 times to enter the raw binary bitbang mode.
• Send 0×0F to exit raw bitbang mode and reset the Bus Pirate.
• Other raw protocol modes are accessible from within bitbang mode, 0×00 always returns to raw bitbang mode and prints the version string.
• There is a slight settling delay between pin updates, currently about 5us.

Updates

• Here’s a test script in Perl.

See the latest version in the documentation wiki.

Raw SPI is a new mode that provides high-speed access to the Bus Pirate SPI hardware. It was developed in conjunction with Michal Ludvig, so that AVRDude can use the  Bus Pirate to program AVR microcontrollers and EEPROMs.

Firmware v2.3 includes two new raw I/O modes that give computer software and scripts direct access to the Bus Pirate hardware. Hopefully this opens the door to a whole new class of Bus Pirate applications, like chip programmers. In this post we describe the raw SPI access mode. We’ll describe the raw bitbang mode in a few days. The protocol is documented below the break.

Raw SPI mode command table

• 00000000 – Enter raw bitbang mode, reset to raw bitbang mode
• 00000001 – SPI mode/rawSPI version string (SPI1)
• 00000010 – CS low (0)
• 00000011 – CS high (1)
• 00001101 – Sniff all SPI traffic
• 00001110 – Sniff when CS low
• 00001111 – Sniff when CS high
• 0001xxxx – Bulk SPI transfer, send 1-16 bytes (0=1byte!)
• 0100wxyz – Configure peripherals, w=power, x=pullups, y=AUX, z=CS
• 01100xxx – Set SPI speed, 30, 125, 250khz; 1, 2, 2.6, 4, 8MHz
• 1000wxyz – SPI config, w=output type, x=idle, y=clock edge, z=sample

Commands are a single byte, except bulk SPI transfers. The Bus Pirate responds to SPI write commands with the data read from the SPI bus during the write. Most other commands return 0×01 for success, or 0×00 for failure/unknown command.

Key points

• Send the raw byte value 0×00 into the user command prompt 20 times to enter bitbang mode.
• Enter 0×01 in bitbang mode to enter raw SPI mode.
• Return to raw bitbang mode from raw SPI mode by sending 0×00 one time.
• Operations that write a byte to the SPI bus also return a byte read from the SPI bus.
• Hex values shown here, like 0×00, represent actual byte values; not typed ASCII entered into a terminal.
• Other values are shown as 8bit binary numbers. Here’s a binary->decimal->hex converter.

Commands

00000000 – Enter raw bitbang mode, reset to raw bitbang mode

This command has two purposes. First, send it to the command line interface 20 times to enter the raw bitbang binary mode. It’s also used to exit the raw SPI mode and return to raw bitbang mode.

Send the value 0×00 to the Bus Pirate command line interface 20 times to enter raw bitbang mode. The Bus Pirate replies ‘BBIOx’, where x is the raw bitbang version number (currently 1).

Once in raw SPI mode (see command 00000001), the 0×00 command returns to raw bitbang mode. Send 0×00 once to return to raw bitbang mode.

00000001 – Enter raw SPI mode, display version string

Once in raw bitbang mode, send 0×01 to enter raw SPI mode. The Bus Pirate responds ‘SPIx’, where x is the raw SPI protocol version (currently 1). Get the version string at any time by sending 0×01 again.

0000001x – CS high (1) or low (0)

Toggle the Bus Pirate chip select pin, follows HiZ configuration setting. CS high is pin output at  3.3volts, or HiZ. CS low is pin output at  ground. Bus Pirate responds 0×01.

00001101 – Sniff all SPI traffic, 0000111x – Sniff when CS low(0)/high(1) (updated in v5.1)

The SPI sniffer is implemented in hardware and should work up to 10MHz. It follows the configuration settings you entered for SPI mode. The sniffer can read all traffic, or filter by the state of the CS pin.

• [/]  – CS enable/disable
• \xy – escape character (\) precedes two byte values X (MOSI pin) and Y (MISO pin) (updated in v5.1)

Sniffed traffic is encoded according to the table above. The two data bytes are escaped with the ‘\’ character to help locate data in the stream.

Send ‘r’ to restart the sniffer without returning to SPI mode. Send any other byte to exit, Bus Pirate responds 0×01 on exit.

If the sniffer can’t keep with the SPI data, the MODE LED turns off and the sniff is aborted. (new in v5.1)

0001xxxx – Bulk SPI transfer, send/read 1-16 bytes (0=1byte!)

Bulk SPI allows direct byte reads and writes. The Bus Pirate expects xxxx+1 data bytes. Up to 16 data bytes can be sent at once, each returns a byte read from the SPI bus during the write.

Note that 0000 indicates 1 byte because there’s no reason to send 0. BP replies 0×01 to the bulk SPI command, and returns the value read from SPI after each data byte write.

0100wxyz – Configure peripherals w=power, x=pull-ups, y=AUX, z=CS

Enable (1) and disable (0) Bus Pirate peripherals and pins. Bit w enables the power supplies, bit x toggles the on-board pull-up resistors, y sets the state of the auxiliary pin, and z sets the chip select pin. Features not present in a specific hardware version are ignored. Bus Pirate responds 0×01 on success.

Note: CS pin always follows the current HiZ pin configuration. AUX is always a normal pin output (0=GND, 1=3.3volts).

01100xxx -  SPI speed

000=30kHz, 001=125kHz, 010=250kHz, 011=1MHz, 100=2MHz, 101=2.6MHz, 110=4MHz, 111=8MHz

This command sets the SPI bus speed according to the values shown. Default startup speed is 000 (30kHz).

1000wxyz – SPI config, w=HiZ/3.3v, x=CKP idle, y=CKE edge, z=SMP sample

This command configures the SPI settings. Options and start-up defaults are the same as the user terminal SPI mode. w= pin output HiZ(0)/3.3v(1), x=CKP clock idle phase (low=0), y=CKE clock edge (active to idle=1), z=SMP sample time (middle=0). The Bus Pirate responds 0×01 on success.

Default raw SPI startup condition is 0010. HiZ mode configuration applies to the SPI pins and the CS pin, but not the AUX pin. See the PIC24FJ64GA002 datasheet and the SPI section[PDF] of the PIC24 family manual for more about the SPI configuration settings.

0010xxxx, 0011yyyy – Enter SPI data byte in nibbles, read SPI byte Deprecated in v5.1

Data bytes can also be entered in two nibbles using this pair of commands. 0011yyyy loads the upper 4 bits of a data byte. 0010xxxx loads the lower 4 bits of the data byte, and writes it to the SPI bus. The bus write returns a byte read.

A byte is transmitted over SPI each time the low bits are sent. Be sure to send the upper bits first, then send the lower bits to complete the data and transmit it. If the upper four bits are the same as the previous byte, then you can increase speed by sending just the lower four bits.

Entering the upper 4 bits returns 1 for success, or 0 for failure. Entering the low bits returns a byte read from the SPI bus.