BBIO2 binary mode

There’s some scripts out there that support the BBIO1 binary interface, but the support is so old and variable I’m not sure emulating it has much value. The major targets are sigrok and flashrom. Sigroks windows SUMP driver is messed up, and flash rom still tries to parse ancient text from the terminal. Maybe also AVRdude?

I’m going to take this as license to build something new. BBIO1 is a mess because it was hacked together in stages and we just didn’t have many resources left in the PIC. It’s simple and easy to understand, but it’s inconsistent and overly involved.


  • Consistent control of all bus pirate features in every mode
  • Data first, always be sending data unless otherwise requested
  • Simple values - PWM, PSU, etc set with plain text values and the right dividers are calculated

Many wireless packet protocols use 0x7f as an escape character to indicate system commands. I think that’s the direction to go. If 7f is data, it’s escaped with 7f, otherwise commands follow. Maybe commands can be 7f with command byte and 4 data bytes (like sump commands).

Global commands

  • Change mode
  • Vreg enable (optional current limit)
  • pull ups
  • echo string to terminal
  • xon flow control ?
  • xoff flow control
  • setup mode. Possible get descriptor of mode setup options? Maybe speed and settings are separate commands?
  • LED control
  • LCD control (maybe a mode?)
  • pwm
  • measure freq
  • gpio aux stuff
  • pin direction
  • ADC measure (setup and get reading)
  • get current (plain text)
  • get pin voltage (plain text)
  • delay
  • silent (wether to acknowledge every command?)

Mode specific commands, like what we now call bus syntax in the user terminal

  • read
  • all non escaped data is write
  • start
  • stop
  • bulk read write (used by flashrom and avrdude)
  • scan for devices (I2C, 1wire)

7f 02 03 30 - command 2 set PSU at 3. 30 volts for example.

It would be cool to have a mode that debugs the binary interface from the UI. All least it would be convenient to me.

I’m going to target flashrom, avrdude, and asprogrammer. I saw dreg has an asprogrammer hack in his github. I’ll get a build server setup so we get auto compiles.

Any thoughts?

Hello Ian! Are you focusing more on the readability of the protocol or its integration with existing tools? If the last is your main focus , a suggestion would be that you could take into consideration use of Protocol Buffers as the transporting means. It would simplify a lot the development of new scripts in virtually any language and take from you the burden of developing your own.

1 Like

Thanks for the suggestion… I’m not familiar with protocol buffers. How does that work?

You could consider it to be a serialization method, such as COBS or even JSON. It is a quite popular format, created by Google, and has a lot of tooling available.

Using this method, we could define the protocol using .proto files, a human-readable file format similar to C headers where users could create clients in virtually language.

Eg.: Imagine you had defined the protocol as:


These are specific commands to change the state of the buspirate, their values and parameters.

syntax = "proto3";

package buspirate;

// Commands for altering the state of the Bus Pirate
message Command {
  required int32 version  = 1; // always good we do versioning
  oneof payload {
    ChangeModeCommand change_mode = 1;
    VregEnableCommand vreg_enable = 2;
   (...) we can include more as we go

message CommandResponse {
  oneof response {
    SuccessResponse response = 1;
    ErrorResponse response = 2;

message ChangeModeCommand {
  enum Mode {
    SPI = 0;
    I2C = 1;
    // other modes
  Mode mode = 1;

message VregEnableCommand {
  bool enable = 1;
  // Optional current limit, if applicable

message SuccessResponse {
   repeated uint32 message = 1
message ErrorResponse {
   repeated uint32 message = 1


These are queries used to request data from buspirate.

syntax = "proto3";

package buspirate;

// Queries for retrieving state from the Buspirate
message Query {
  oneof payload {
    GetCurrentQuery get_current = 1;
    GetPinVoltageQuery get_pin_voltage = 2;
    // Add other queries as needed

message GetFrequencyQuery {
  // Details for the query, if any are needed

message GetPinVoltageQuery {
  // Details for the query, if any are needed

// Responses to queries
message QueryResponse {
  oneof response {
    FrequencyResponse current = 1;
    PinVoltageResponse pin_voltage = 2;
    // Add other response types as needed

message frequencyResponse {
  float frequency = 1; // in hertz

message PinVoltageResponse {
  float voltage = 1; // Voltage in volts

With that, I could easily consume it using python as (after compiling it with protoc):

from buspirate_commands_pb2 import Command, ChangeModeCommand

# Create a Command message
cmd = Command()
cmd.version = 1  # Set the version
cmd.change_mode.mode = ChangeModeCommand.SPI  # Set to change mode to SPI

# Serialize the command to a byte string
cmd_bytes = cmd.SerializeToString()

# Now, cmd_bytes can be sent  over com port.

I would advise you to take a look at the nanopb project, it is a very lightweight implementation (less than 10kb size and requires less than 1kb ram memory). The best of all, it has a short permissive license, compatible with GPL.


Yes, protocol buffers would be a valid choice as base for a new binary mode.

If for some reason you decide against it and keep rolling your own protocol, then consider COBS instead of traditional escaping with something like 0x7f. This traditional escaping has a very bad worst case efficiency when the escape character is often part of the data to transmit and COBS is able to improve that.

Have a look at the wikipedia page for an explanation Consistent Overhead Byte Stuffing - Wikipedia

1 Like

Very nice, thank you both. That looks great.

Today I did a major rework of commands and command line arguments for the spi flash utility. The next step is the binary mode. I will check this out.