These are proposed commands and data formats for the global Bus Pirate commands. Things that should be available in every protocol mode. Please note that this is not a protocol, it’s a framework for interacting with the Bus Pirate in binary mode. The protocol will come later.
Test firmware
bus_pirate5_rev10-binmode-2.zip (185.3 KB)
This is tracking the binmode branch in github.
Test rig mode
BIN mode (currently mode 10) provides a loopback to the binary interface. The Bus Pirate command line and tools are available for debugging the binary interface without any clunky external software.
Return codes
Commands with no output currently return 0 for success or an error code (1+).
BM_RESET = 0,
Reset the Bus Pirate current mode to HiZ, reset all hardware (hopefully).
Note that in BIN mode, this resets the terminal back to HiZ.
BM_DEBUG_LEVEL, //1
Set debug level. Takes one argument:
- 0 - no debug output
- 1 - show debug output in the terminal
This handy setting prints debug info to the Bus Pirate terminal (not the binary port). It shows:
- The command received and the number of arguments it requires
- Output from the command used
- The command return code (0 success, else error)
BM_POWER_EN, //2
Enable the Bus Pirate power supply. 4 byte arguments:
- Voltage integer value (0-5)
- Voltage decimal value (0-99)
- Current limit mA high byte
- Current limit mA low byte
Set the current limit to 0xff 0xff for no current limit.
The power supply has some return codes:
- Fuse blew during power on, possible short or current limit too low
- Voltage level too low
BM_POWER_DIS, //3
Disable Bus Pirate power supply.
BM_PULLUP_EN, //4
Enable pull-ups.
BM_PULLUP_DIS, //5
Disable pull-ups
BM_LIST_MODES, //6
List available modes. Gives a comma separated list of available modes. Ends with 0x00 (null terminated string).
BM_CHANGE_MODE, //7
Not yet implemented. I think the thing to do is send the name of the mode (as printed above) so we’re not reliant on fixed numbers. Should probably make it case insensitive.
BM_INFO, //8
Reserved. Returns 1 for invalid command.
BM_VERSION_HW, //9
Currently returns the a null terminated string, but this will probably change to a 3 byte reply or something.
BM_VERSION_FW, //10
Currently returns the null terminated compile timestamp.
BM_BITORDER_MSB, //11 & BM_BITORDER_LSB, //12
Set bit order: MSB or LSB.
BM_AUX_DIRECTION_MASK, //13
Set IO pin to input or output. Will not effect pins currently assigned to a peripheral. Requires two argument bytes:
- Bit mask of pins to change
- Bit mask of the pin direction (1 = output, 0 = input)
This should probably have a companion function that returns the free IO pins, and maybe the functions assigned to any pins.
Edit: I fixed the wrong direction values shown above.
BM_AUX_READ, //14
Return a byte with the current state of the 8 IO pins.
BM_AUX_WRITE_MASK, //15
Write to IO pins. Does not effect pins currently assigned to a hardware peripheral. Requires 2 byte arguments:
- Bit mask of pins to write
- Bit mask of the value to write to those pins
Edit: also fixed the incorrect output state number.
BM_ADC_SELECT, //16
Select the ADC channel to read. Requires one argument
- ADC channel according to the list below.
HW_ADC_MUX_BPIO7, //0
HW_ADC_MUX_BPIO6, //1
HW_ADC_MUX_BPIO5, //2
HW_ADC_MUX_BPIO4, //3
HW_ADC_MUX_BPIO3, //4
HW_ADC_MUX_BPIO2, //5
HW_ADC_MUX_BPIO1, //6
HW_ADC_MUX_BPIO0, //7
HW_ADC_MUX_VUSB, //8
HW_ADC_MUX_CURRENT_DETECT, //9
HW_ADC_MUX_VREG_OUT, //10
HW_ADC_MUX_VREF_VOUT, //11
CURRENT_SENSE //12
Channels 0-11 are measured through the analog mux and are divided by 2. Channel 12 measures the current sense, which is not divided.
BM_ADC_READ, //17
Read from the currently selected ADC channel, return actual voltage. Returns 2 bytes:
- Voltage integer value
- Voltage decimal value
Note that the return values are not ASCII text, and have already been adjusted to account for the divide by 2 for analog mux channels.
BM_ADC_RAW, //18
Read from the currently selected ADC channel, return the raw ADC value (2 bytes).
Channels 0-11 are measured through the analog mux and are divided by 2. Channel 12 measures the current sense, which is not divided. The raw uncompensated values are returned.
BM_PWM_EN, //19
Enable a PWM at specified frequency in Hz. Six argument bytes:
- IO pin (0-7)
2-5. 32 bit value of frequency in Hz
- Duty cycle in percent (0-100%)
I would like to return the actual frequency, but it needs to be balanced against the return codes. I’ll probably repurpose the raw command to fetch the actual frequency.
Return codes:
- Pin out of range
- Pin in use/not available (also if the adjacent slice is used)
- Frequency out of range
BM_PWM_DIS, //20
Disable PWM. Requires one argument byte: IO pin number. Return codes:
- Pin out of range
- PWM not active on specified IO pin
BM_PWM_RAW, //21
Enable PWM with raw register values. Not recommended as it will vary by system. Requires 7 argument bytes:
- IO pin number (0-7)
- 12 bit PWM divider value (2 bytes)
- 16 bit PWM top value (2 bytes)
- 16 bit PWM duty cycle value (2 bytes)
Return codes:
- Pin out of range
- Pin in use/not available (also if the adjacent slice is used)
BM_FREQ, //22
Not implemented. Measure frequency on pin, return value in Hz.
BM_FREQ_RAW, //23
Not implemented. Return raw frequency measurement.
BM_BOOTLOADER, //24
Jump to bootloader. Does not currently return 0x00 because of reasons.
BM_RESET_BUSPIRATE, //25
Reset the Bus Pirate. Does not currently return 0x00 because of reasons.
BM_PRINT_STRING, //26
Print a string to the Bus Pirate terminal. The string must be terminated with 0x00.
Potential additional commands
//self test
//disable all interrupt
//enable all interrupt
//LEDs?
//SUMP logic analyzer mode?
