Serial Protocol Debugging With Ubuntu & Bus Pirate v4

Back in the day, developing serial protocols was a cat-and-mouse game of write some code for host processor, tweak your serial peripheral and repeat, adding some logic analyser sauce as necessary.  These days logic analysers and even DSOs will decode a wide variety of serial protocols for one- or more-wire hardware architectures.  Still, fast logic analysers and fancy protocol-savvy scopes are pricey.

Enter the Bus Pirate. The Bus Pirate is an open hardware design for a USB-connected, self-contained serial protocol host.  It even has a basic logic analyser capability.  The really clever decision in the design is that the USB interface is a standard USB-to-serial device that has huge compatibility across a wide range of OSes that you might use on your development workstation. Version 4 of the Bus Pirate is a bit bleeding edge at the time of writing, but that hasn’t deterred our friends in Shenzen from knocking one out.  The V4 Bus Pirate USB interface is CDC-ACM standard implemented right on the PIC of the gadget. Rather than design some arcane, new protocol for the Bus Pirate-to-workstation interface, the Bus Pirate presents a simple, stable, text-menu interface that can be controlled manually using a simple serial terminal emulator app or is eminently scriptable.

I bought my Bus Pirate (version 4) from China via eBay.  It came with a neat little plastic enclosure, some probe clips, a(nother) USB cable and some ribbon jumper cable.  It was a few dollars more than the bare device that you can get direct from the original developer, Dangerous Prototypes, for around US$40 including shipping. A fringe benefit of buying from China is that they almost always write a customs declaration label the value of anything they ship as sub-US$20 ;-).

Driving the Bus Pirate From Ubuntu

If you’ve read this far, I’m guessing you’re one of the Good Guys and you’re running Linux (and probably Ubuntu) on your workstation. The rest of this post will have little interest to you if you are running Windows on your workstation (although you do have my deepest sympathies).

When I first plugged the Bus Pirate in I didn’t see any blinkenlights on the gadget which was a little disconcerting – thoughts of a return to the eBay Resolution Centre came to mind.  I checked back on the Dangerous Prototypes site and the standard v4 (and earlier) Bus Pirates have 4 LED’s – one of which is permanently on as long as it’s connected to the workstation USB port.  So, Shenzen 0 – Dangerous Prototypes 1; cost-saving those 3 LED’s out is not cool.

You can use any serial terminal program you like to connect to the Bus Pirate using 115200 8N1 (if you have read this far I presume that you know I mean 115200 bps, 8 data bits, no parity and one stop bit, right?).  You can use yakuake, picocom, GtkTerm, Micicom… …there are almost as many serial terminal programs as text editors.  Here’s what worked for me:

gtkterm -s 115200 -p /dev/ttyACM0 &

Hit carriage return and you should see  a friendly


prompt.  The prompt on the Bus Pirate indicates the mode and when powered up the Bus Pirate is in a high-impedance / nothing powered, nothing connected mode.  Hence ‘HiZ’. When you select a protocol mode (e.g. I2C), the prompt changes to reflect that.

Hit ? and return to get help on the commands.  Being a little wary of an eBay-direct-from-China version (not a ‘rip-off’ – this is open hardware, after all), I hit i to get the version info and ~ to do a self-test:

Bus Pirate v4
Firmware v6.1 r1676
DEVID:0x1019 REVID:0x0004 (24FJ256GB106 UNK)
Disconnect any devices
Connect (ADC to +3.3V)
Space to continue
... etc. etc.
MODE, VREG, and USB LEDs should be on!
Any key to exit
Found 0 errors.

Looks good. Even the Cyclops blinkenlight is on. Worth $40 already.

Attach a Device – The Nokia 5110 LCD Module

Let’s talk to a serial device.  I have a Nokia 5110 LCD in my modules bin – it’s the only hardware with the word ‘Nokia’ on it that I’d buy these post-Windows-Phone-apocalypse days.  The display itself is actually a Philips PCD8544.  It’s an SPI kind of interface and here’s how I connected it to the Bus Pirate:

5.0V -> VCC
CS -> CE

To set up the Bus Pirate v4 I selected SPI mode with m then 5 for SPI.  Then I chose the following options: 30kHz (would probably work faster), clock idle low, clock edge active to idle, input sample phase middle (doesn’t make any difference since we don’t read any data from the display anyway), CS active low (/CS), output H=3.3V & L=GND. Then I powered up the peripheral with the W command.  You can do a quick check that there aren’t any supplies shorted with the v command.  A handy way to power up with a reset pulse and appropriate delays would be the Bus Pirate v4 command line:


The ‘w’ (lower case) switches power off, the ‘%’ does a one millisecond delay and the ‘k’ and ‘c’ are used to change which AUX output is controlled with the ‘a’ and ‘A’ commands – in this case allowing control of the AUX1 output that we are using to drive the reset on the display.

Then I initialised the display with the following:

a[0x21 0xBF 0x14 0x20 0x0c]

The ‘a’ sets the AUX output from the Bus Pirate to low which puts the LCD into command mode – i.e. data that it receives will be interpreted as commands. The ‘[‘ activates Chip Select (CS output of the Bus Pirate) and ‘]’ deactivates it.  The hex data in between gets sent in SPI protocol through MOSI and clocked on CLK.  Checking the data sheet for the display, 0x21 => use the extended command set (set H bit=1), 0xbf => set the LCD output voltage (contrast) to maximum, 0x14 => LCD bias to 1:48, 0x20 = > use the basic command set again (H = 0) and 0x0c selects the normal (as opposed to inverse, etc.) mode for LCD operation.

Then move the cursor to the top-left:

a[0x80 0x40]

Now to write a couple of characters. Note the ‘A’ to set the D/C to data mode, i.e. what is clocked in should be used for the display buffer. Note how the 5110 display characters are built up, in this case with 8-pixel-high strips, each character needing 5 of these strips to make a 5-pixel-wide by 8-pixel-tall character. (It’s one of the standard criticisms of this display that the pixels aren’t individually addressable.)

A[0x7c 0x04 0x18 0x04 0x78 0x20 0x40 0x44 0x3d 0x00]

The result here should be my initials ‘mj’ in the top-left of the display.



You can see how the Bus Pirate can get you up and running with a new serially-connected peripheral pretty quickly.  You can get started with configuring the peripheral in no time to suss out your initialisation and wiring.  The next level would undoubtedly be to drive the Bus Pirate from a script so that you can develop some richer tests for your peripheral without quite so much pain since the device (that I have) doesn’t have much memory for the command history.