For months we’ve used our Bus Pirate universal serial interface tool to demonstrate electronics parts, so it’s only appropriate that the Bus Pirate get it’s own parts post. We recently had a Bus Pirate preorder, and today we received the pre-production Bus Pirate prototype from Seeed Studio. This prototype was mailed just a few days before preorder 1 started to ship, so those packages should start arriving any day.

Follow along as we unbox the prototype Bus Pirate, and connect it to a debugger to determine the PIC24FJ64GA002-I/SO revision that shipped with this board. Use this post to share your own Bus Pirate unboxing experience. Pictures and discussion after the break.

Most Bus Pirates will ship in a padded envelope (JPG), but ours came in a box with some PCBs for future projects and an AVR programmer.

Inside the box, the Bus Pirate is protected by a static dissipative bag. The Bus Pirate pin headers are stuck in foam to protect the packaging.

We ran a battery of functionality tests that covered USB, the user terminal, protocol libraries, power supplies, and pullup resistors. Everything passed our tests.

Next, we used a Microchip ICD2 debugger/programmer to make a backup of the firmware prior to doing a test upgrade/downgrade with the bootloader.

Connecting to MPLAB ICD 2
…Connected
Setting Vdd source to target
Target Device PIC24FJ64GA002 found, revision = Rev 0×3042
…Reading ICD Product ID
Running ICD Self Test
…Passed
MPLAB ICD 2 ready for next operation

All of our previous Bus Pirate version were built using Rev 0×3003 (A3) of the PIC 24FJ64GA002. Version A3 has a few issues, known as errata (PDF), one of which is a flaky hardware I2C module. These chips aren’t ‘defective’, they just have a few quirks like any complicated integrated circuit. The Bus Pirate firmware works around these issues using software techniques. Most desktop computer processors go through a similar stepping process.

Our Bus Pirate appears to have a B4 revision PIC (0×3042) that corrects some, but not all, of the errata from A3. This is no guarantee that every Bus Pirate will have a B4 PIC, preorder 1 and 2 are both sourced from multiple international vendors. Additionally, there’s no immediate benefit from having a B4 chip, someone will have to write software that takes advantage of the hardware. The next firmware update will print the PIC revision in the user terminal, check the nightly compiles if you’re anxious.

There is a revision B5 mentioned in the PIC errata. Some of these might find their way into preorder 2 boards.

Now that you’ve got your Bus Pirate, what do you do with it? We’ve got a bunch of part demonstrations to get you started.

Please leave a comment about your unboxing experience, and the devices you plan to interface.

Futaba makes vacuum florescent character displays that can be used as a drop-in replacement for common character LCDs. VFDs have a wider viewing angle, and generally look cooler.

Futaba’s character displays can be interfaced using the standard 8-bit or 4-bit parallel LCD interface, or a simple two-wire protocol. The protocol type is set by resistors on the back of the display, so it’s not particularly easy to change without a hot-air rework station. Today we’ll demonstrate a serially-interfaced VFD using the Bus Pirate.

Futuba VFD character LCD replacement (NA204SD02, $7.00). Datasheet (PDF).

We used our Bus Pirate universal serial interface to demonstrate the Futaba VFD, but the interface operations will be the same for any microcontroller implementation. The connections we made between the VFD and the Bus Pirate are shown in the table above.

We setup the Bus Pirate for raw2wire mode (menu M, 7) with open drain outputs (HiZ). The open drain outputs let us interface the 5volt VFD from the 3.3volt Bus Pirate using the on-board pull-up resistors (menu P, 2). Finally, we enabled the on-board power supply (capital ‘W’).

The VFD’s strobe pin is connected to the Bus Pirate CS pin.  The auxiliary pin doesn’t have it’s own pull-up resistor but CS does. CS is otherwise unused in raw2wire mode, so we reassigned the auxiliary commands to the CS pin (menu C,2).

Interfacing

The two-wire interface uses a straight-forward 16bit (2byte)  protocol (datasheet page 20). The LCD control bits (R/W, RS) go in the first byte, and eight data bits go in the second. All transactions start with strobe low and end with strobe high. Read operations are similar to writes, except the R/W bit is set and the second byte is read.

The Futaba VFD accepts all the standard HD44780 LCD commands (datasheet page 27), see these tables for a detailed description of each command. After a reset (power-up), the VFD expects the first command to be the function set command.

RAW2WIRE>@ <–start with strobe high
AUX HIGH IMP, READ: 1 <– aux pin (CS) is now input, pull-up resistor holds strobe high
RAW2WIRE>a 0b11111000 0b00111000 @ <–command
AUX LOW <–strobe low
WRITE: 0xF8 <–start byte (R/W=0, RS=0)
WRITE: 0×38 <–instruction byte (function set)
AUX HIGH IMP, READ: 1 <–strobe high
RAW2WIRE>

Function set configures the data interface length (bit 4), display lines (bit 3), and brightness/luminescence (bits 1,0).  Before we start we set the strobe pin high (@) in case it’s currently low. Then, we start the transaction by taking the strobe pin low (a), and send the first byte with the R/W and register select (RS) settings.

The second byte is the command. We set the data interface length to 8bits (bit 4 = 1), but in serial mode this is probably ignored. Our display has multiple lines (bit 3 = 1), and we set brightness to full (bits 1,0 = 0). The sequence concludes when the strobe pin returns high (@).

RAW2WIRE>a 0b11111000 0b00001111 @
AUX LOW <–strobe low
WRITE: 0xF8 <–start byte (R/W=0, RS=0)
WRITE: 0x0F <–instruction byte (display on/off control)
AUX HIGH IMP, READ: 1 <–strobe high
RAW2WIRE>

The display ON/OFF command enables the display (bit 3), toggles the cursor (bit 1), and blinks the cursor (bit 0). We enabled the display (bit 3 = 1) with a blinking cursor (bit 1,0 = 1) so it’s obvious that the display is working.

RAW2WIRE>a 0b11111000 0b10000000 @
AUX LOW <–strobe low
WRITE: 0xF8 <–start byte (R/W=0, RS=0)
WRITE: 0×80 <–instruction byte (DDRAM address set)
AUX HIGH IMP, READ: 1 <–strobe high
RAW2WIRE>

Before writing characters to the display we need to position the cursor by sending the DDRAM address set command (0b10000000) summed with the desired cursor position. We set the cursor to the first character on line 1.

The second character on line 1 is located at 0×01. To set this address we’d send 0b10000001 (0b10000000 +0b00000001).

Character display memory isn’t linear, the first line starts at 0×00, the second line starts on position 0×40, the third at 0×14, and the last line begins with position 0×54. Most displays have a similar configuration, here’s some tables for determining the layout of different character displays.

RAW2WIRE>a 0b11111010 0×48 0×61 0×63 0x6b 0×20 0×61 0×20 0×44 0×61 0×79 @
AUX LOW <–strobe low
WRITE: 0xFA <–start byte (R/W=0, RS=1)
WRITE: 0×48 <–ASCII letter ‘H’
…
WRITE: 0×79 <–ASCII letter ‘y’
AUX HIGH IMP, READ: 1 <–strobe high
RAW2WIRE>

Finally, we can enter some characters at the position set with the previous command. Characters are entered as their ASCII equivalent values. We displayed “Hack a Day” with proper capitalization.

Multiple characters can be entered at once, but because the memory space isn’t contiguous it’s necessary to manually position the cursor at the beginning of each new line. After writing the last position of line 1, the cursor will advance to the first character of line 3. Use another position command, 0b10010100, to set the cursor to the beginning of line 2 (0b10000000 + 0×14 = 0b10010100).

Like this post? Check out the parts posts you may have missed. Want to request a part post? Please leave your suggestions in the comments.

Hack a Day review disclosure: We bought the serial VFD demonstrated here on eBay, Futaba also sent us a sample with a parallel interface that we’ll demo later (shown here).

Macetech’s ShiftBrite is a high-power RGB LED coupled with an Allegro A6281 backpack. The A6281 uses three 10bit pulse-width modulators to mix millions of colors using the red, green, and blue elements in the RGB LED. Multiple modules can be chained together for bigger projects, like the ShiftBrite table.

Below the break we demonstrate a ShiftBrite module using the Bus Pirate. For a limited time you can get your own Bus Pirate, fully assembled and shipped worldwide, for only $30.

ShiftBrite RGB LED module (Macetech, $4.99). ShiftBrite datasheet and example code, Allegro A6281 datasheet (PDF).

The ShiftBrite module is a complete A6281 development board. It doesn’t require any extra parts, just a 5-9volt supply.

The A6281 is one of the most complete RGB LED driver ICs, but it’s only made in a tiny QFN package. The ShiftBrite is a good way to try the A6281 without soldering a small chip.

A bunch of A6281 modules can be chained together. Each module repeats all of the serial input signals on separate output pins, so the A6281 will work over long cable runs.

We used our Bus Pirate universal serial interface to demonstrate the ShiftBrite, but the command sequences will be the same for any microcontroller. We connected the Bus Pirate to the ShiftBrite as shown in the table above.

We setup the Bus Pirate for raw3wire mode (M, 8), and chose open drain outputs (Hi-Z) so we can interface the ShiftBrite at 5volts. The Bus Pirate can’t output 5volts directly, so we enabled the bus pull-up resistors (menu ‘p’ in v2) and attached the pull-up resistor voltage input pin to the 5volt supply. Finally, we enabled the on-board power supply (capital ‘W’).

Interfacing

The LED driver output is only active when the enable pin (EI) is held low.

RAW3WIRE>A <– capital ‘A’, EI pin high, output disabled
AUX HIGH
RAW3WIRE>a <– small ‘a’, EI pin low, output active
AUX LOW
RAW3WIRE>

We used the Bus Pirate’s auxiliary pin to toggle the A6281′s enable pin, but you could also bypass this feature by wiring EI directly to ground. A small ‘a’ in the Bus Pirate terminal takes the AUX/EI pin connection low, enabling the LED output.

Two commands update the A6281 settings. The configuration command controls dot correction and clock settings. The LED pulse-width modulator (PWM) command updates the three 10bit values that set the red, green, and blue channel brightness. Both commands are 32 bits (4 bytes) long, bit 30 selects the configuration or pulse-width modulator command. Refer to the chart above, or datasheet page 7.

The interface protocol is like SPI, but the master-input-slave-output pin is unused. Data is sent most significant bit first, starting with bit 31. Commands are sent by clocking 32 bits into the chip and then toggling the latch pin.

Before we can start mixing colors, we need to setup the A628a’s internal clock and write the dot correction values.

RAW3WIRE>0b01000111 0b11110001 0b11111100 0b01111111 ][
WRITE: 0x47 <--write 32bits of data
WRITE: 0xF1
WRITE: 0xFC
WRITE: 0x7F
CS DISABLED <--latch pin high
CS ENABLED <--latch pin low
RAW3WIRE>

We wrote the values in binary so it's easy to follow along in the table above. Remember that bit 31 is sent first, so the order of bits shown here is opposite of what is shown in the table.

The complete setup command is 32 bits (4 bytes) long. Bit 30 sets this as a configuration command (1). Bit 7 and 8 configure the clock source, value 00 configures the 800KHz internal oscillator (datasheet page 7). Three 7bit 'dot correction' values fine tune the LED color channels if you want to correct a wonky pixel in a large array (see the register locations in the table above). We set all the dot correction values to full (1111111). Several bits trigger test functions or don't have a purpose, these should be entered as 0.

After entering 32 bits, toggle the A6281 latch pin (][) to lock the data into the register. Now that the chip is configured and the output enabled, we can finally play with the LED.

RAW3WIRE>0b00111111 0b11111111 0b11111111 0b11111111 ][
WRITE: 0x3F
WRITE: 0xFF
WRITE: 0xFF
WRITE: 0xFF
CS DISABLED
CS ENABLED
RAW3WIRE>

First, turn all the colors to full. Bit 31 (0) is ignored, bit 30 (0) indicates a LED pulse-width modulator update command, and the remaining bits set all three channels to 100%.  The three PWM values control the output intensity of each color as follows: blue (bits 29:20), red (bits 19:10), and green (bits 9:0). Raise and lower the latch pin (][) to end the command.

Next, test each each color individually.

RAW3WIRE>0b00111111 0b11110000 0b00000000 0b00000000 ][
WRITE: 0x3F
WRITE: 0xF0
WRITE: 0x00
WRITE: 0x00
CS DISABLED
CS ENABLED
RAW3WIRE>

Bit 30 (0) signals an LED PWM update command, followed by a 100% setting for the blue channel (1111111111) and 0% settings for the red and green channels. When we toggle the latch pin (][) the new values are saved and the LED color changes to blue.

RAW3WIRE>0b00000000 0b00001111 0b11111100 0b00000000 ][
WRITE: 0x00
WRITE: 0x0F
WRITE: 0xFC
WRITE: 0x00
CS DISABLED
CS ENABLED
RAW3WIRE>

This time we'll set the LED to 100% red. Bit 30 (0) signals an LED PWM update command, followed by a 0% setting for the blue channel, a 100% setting for the red channel (1111111111), and a 0% setting for green.  When we toggle the latch pin (][) the LED color changes to red.

RAW3WIRE>0b00000000 0b00000000 0b00000011 0b11111111 ][
WRITE: 0x00
WRITE: 0x00
WRITE: 0x03
WRITE: 0xFF
CS DISABLED
CS ENABLED
RAW3WIRE>

Finally, we set the LED to 100% green. Bit 30 signals an LED PWM update, followed by 0% settings for the blue and red channels, and a 100% setting for the green channel (1111111111).  Toggle the latch pin (][) and the LED color changes to green.

Like this post? Check out the parts posts you may have missed. Want to request a part post? Please leave your suggestions in the comments.

Hack a Day review disclosure: Macetech gave us a couple free ShiftBrites at Maker Faire 2008.

Linear Technology’s LTC2631A-LZ8 is an 8bit digital to analog converter (DAC) with an I2C interface. This DAC can output 255 different voltages, spaced evenly between 0 and 2.5volts. We previously demonstrated the LTC2640 with a three-wire SPI interface, but this version is controlled with only two signal wires.

We used the Bus Pirate universal serial interface tool to work with the DAC, but the same basic principals apply to any custom implementation. The connections between the Bus pirate and the LTC2631A are outlined in the table. We powered the chip from the Bus Pirate’s 5volt supply, but it would also work fine at 3.3volts.

The I2C bus requires pull-up resistors on both bus wires. 5volts is supplied to the pull-up resistors by connecting a wire from the 5volt supply to the pull-up resistor input terminal. Close the jumpers on the clock and data lines to supply the external voltage to the pull-up resistors.

Now, setup the Bus Pirate for I2C mode and activate the on-board power supply.

HiZ>m<–select mode
1. HiZ
2. 1-WIRE
3. UART
4. I2C
…
9. PC AT KEYBOARD
MODE>4<–I2C mode
900 MODE SET
202 I2C READY
I2C>p<–setup power supply
W/w toggles 3.3volt supply?
1. NO
2. YES
MODE>1<–don’t use 3.3volts
W/w toggles 5volt supply?
1. NO
2. YES
MODE>2<–use 5volt supply
9xx SUPPLY CONFIGURED, USE W/w TO TOGGLE
9xx VOLTAGE MONITOR: 5V: 0.0 | 3.3V: 0.0 | VPULLUP: 0.0 |
I2C>W<–capital ‘W’ activates the supply
9xx 5VOLT SUPPLY ON
I2C>v<–check the voltage levels
9xx VOLTAGE MONITOR: 5V: 4.9 | 3.3V: 0.0 | VPULLUP: 5.0 |<–supply on
I2C>

After configuring the Bus Pirate, the voltage monitor shows that the 5volt supply is active (4.9volts). Additionally, the monitor shows that 5volts is connected to the pull-up resistor supply terminal (VPULLUP).

I2C>(0)<–list available macros
0.Macro menu
1.7bit address search
I2C>(1)<–search for I2C devices
xxx Searching 7bit I2C address space.
Found devices at:
0×40 0xE6<–got reply from these addresses
I2C>

The state of pin 1 and 8 determine the LTC2631A I2C address, according to the table on page 22 of the datasheet. Instead of looking up the address in the datasheet, we used the Bus Pirate’s I2C address search macro to scan the entire I2C address range. The DAC responds to the set address (0X40) and a global address (0xE6). The global address is useful for controlling multiple DACs simultaneously over the same I2C bus.

I2C>d [0x40 0b00110000 0xff 0] d
9xx VOLTAGE PROBE: 0.0VOLTS<–output is 0volts
210 I2C START CONDITION<–start transaction
220 I2C WRITE: 0×40 GOT ACK: YES<–DAC address
220 I2C WRITE: 0×30 GOT ACK: YES<–set DAC output command
220 I2C WRITE: 0xFF GOT ACK: YES<–set DAC to full (255)
220 I2C WRITE: 0×00 GOT ACK: YES<–don’t care, extra byte
240 I2C STOP CONDITION<–end transaction
9xx VOLTAGE PROBE: 2.5VOLTS<–output at full
I2C>

Now we’re ready to interface the DAC. An initial voltage measurement (d) shows that the DAC is currently outputting 0volts.

An I2C start condition ([) alerts connected I2C devices to listen for their address. The first byte is the address (0x40) that identifies the device we want to access. The next byte is the LTC2631A command to update the DAC output (0x30 or 0b00110000), followed by the output setting (0xff or 255, 100% output). The final byte doesn't matter for the 8bit DAC we're using, but carries additional data bits for higher resolution versions of the DAC. The transaction is completed by sending the I2C stop condition (]).

After updating the DAC to 100%, a voltage measurement (d) shows that the output is 2.5volts.

I2C>d [0x40 0x30 0 0] d
9xx VOLTAGE PROBE: 2.5VOLTS<–DAC at 100%
210 I2C START CONDITION
220 I2C WRITE: 0×40 GOT ACK: YES
220 I2C WRITE: 0×30 GOT ACK: YES
220 I2C WRITE: 0×00 GOT ACK: YES<–set DAC to 0
220 I2C WRITE: 0×00 GOT ACK: YES
240 I2C STOP CONDITION
9xx VOLTAGE PROBE: 0.0VOLTS<–DAC at 0%
I2C>

A similar command sequence sets the DAC output back to 0. A voltage measurement confirms that the DAC output is now 0volts.

For a complete list of DAC features and command codes, see the in-depth discussion of the LTC2640 SPI DAC at the end of the Bus Pirate version 1 how-to.

Are there any chips you’d like us to interface in future parts posts?

The Maxim DS2431 1K EEPROM is 1-Wire device that adds storage to a project using a single microcontroller pin. We previously interfaced a 1-wire thermometer, but this EEPROM is slightly different because it draws power directly from the 1-Wire bus. Grab the datasheet (PDF) and follow along while we read and write this simple 1-Wire memory.

DS2431 1-Wire 1K EEPROM (Digikey #DS2431+-ND, $1.67)

We used our Bus Pirate universal serial interface to demonstrate the DS2431 EEPROM, we covered the proper connections and configuration options in our previous 1-wire post. The DS2431 requires just two connections: ground (pin 1) and 1-Wire/power (pin 2).  Pin 3 remains unconnected. Like last time, we used a 2K pull-up resistor with the 1-Wire bus.

First, we use the Bus Pirate’s SEARCH ROM command to identify connected 1-Wire devices.

1-WIRE>(240) <–SEARCH ROM command macro
1WIRE ROM COMMAND: SEARCH (0xF0)
Found devices at:
Macro     1-WIRE address
1.0x2D 0×54 0xD2 0xEF 0×00 0×00 0×00 0x2B <–address
*DS2431 1K EEPROM <– type
2.0x2D 0xFE 0x8D 0×43 0×01 0×00 0×00 0×52
*DS2431 1K EEPROM
3.0x2D 0x2B 0xED 0xEF 0×00 0×00 0×00 0x7C
*DS2431 1K EEPROM
Found 0×03 devices.
The first 10 device IDs are available by MACRO, see (0).
1-WIRE>

The SEARCH ROM command reveals that there are 3 EEPROMs connected to the 1-Wire bus. The Bus Pirate stores the 64bit 1-wire addresses in macros so we don’t have to type it every time. We’ll work with the first device, identified by macro (1).

Writing to the DS2431 takes three steps:

• Write data to DS2431′s 8byte ‘scratch pad’ EEPROM buffer
• Verify the scratch pad contents and get the write access key
• Copy data from the scratch pad to the EEPROM for permanent storage.

Command 0x0f writes to the scratch pad. The scratch pad is an 8byte buffer that holds data prior to saving it permanently in the EEPROM.

1-WIRE>(85)(1) 0x0f 0×00 0×00 0 1 2 3 4 5 6 7 <–command
1WIRE BUS RESET OK
1WIRE WRITE ROM COMMAND: MATCH (0×55) *follow with 64bit address
1WIRE ADDRESS MACRO 1: 0x2D 0×54 0xD2 0xEF 0×00 0×00 0×00 0x2B
1WIRE WRITE: 0x0F <–write to scratch pad
1WIRE WRITE: 0×00 <–begin address byte 1
1WIRE WRITE: 0×00 <–begin address byte 2
1WIRE WRITE: 0×00 <–data
1WIRE WRITE: 0×01
1WIRE WRITE: 0×02
1WIRE WRITE: 0×03
1WIRE WRITE: 0×04
1WIRE WRITE: 0×05
1WIRE WRITE: 0×06
1WIRE WRITE: 0×07
1-WIRE>

The MATCH ROM macro, (85), isolates the the first device, (1). 0x0f is the command to write to the scratch pad, followed by the start address, 0 0. Finally, we send eight bytes of data to save in the scratch pad. The scratch pad is eight bytes long, and all eight bytes will be copied from the scratch pad to the EEPROM at once.

1-WIRE>(85)(1) 0xaa r:3 r:8 r:2 r:2 <–command
1WIRE BUS RESET OK
1WIRE WRITE ROM COMMAND: MATCH (0×55) *follow with 64bit address
1WIRE ADDRESS MACRO 1: 0x2D 0×54 0xD2 0xEF 0×00 0×00 0×00 0x2B
1WIRE WRITE: 0xAA <–read scratch pad
1WIRE BULK READ, 0×03 BYTES: <–access code
0×00 0×00 0×07
1WIRE BULK READ, 0×08 BYTES:<–verify our data
0×00 0×01 0×02 0×03 0×04 0×05 0×06 0×07
1WIRE BULK READ, 0×02 BYTES:<–inverse CRC
0×44 0×67
1WIRE BULK READ, 0×02 BYTES:<–all 1s from here
0xFF 0xFF
1-WIRE>

To copy data from the scratch pad to the EEPROM, we must first retrieve a three byte access code from the scratch pad with the command 0xaa.  The first three bytes are the access code (0×00 0×00 0×07), followed by the data contained in the scratch pad.

1-WIRE>(85)(1) 0×55 0×00 0×00 0×07
1WIRE BUS RESET OK
1WIRE WRITE ROM COMMAND: MATCH (0×55) *follow with 64bit address
1WIRE ADDRESS MACRO 1: 0x2D 0×54 0xD2 0xEF 0×00 0×00 0×00 0x2B
1WIRE WRITE: 0×55 <–copy to EEPROM command
1WIRE WRITE: 0×00<–access code (3 bytes)
1WIRE WRITE: 0×00
1WIRE WRITE: 0×07
1-WIRE>!!!! <–read bits
1WIRE READ BIT: 0
1WIRE READ BIT: 1 <–bits alternate, done
1WIRE READ BIT: 0
1WIRE READ BIT: 1
1-WIRE>

Command 0×55 with the correct access code will copy the scratch pad to the data EEPROM. Bit reads (!!!!) alternate between 0 and 1 when the copy completes.

1-WIRE>(85)(1) 0xf0 0×00 0×00 r:8 r:8
1WIRE BUS RESET OK
1WIRE WRITE ROM COMMAND: MATCH (0×55) *follow with 64bit address
1WIRE ADDRESS MACRO 1: 0x2D 0×54 0xD2 0xEF 0×00 0×00 0×00 0x2B
1WIRE WRITE: 0xF0 <–read memory
1WIRE WRITE: 0×00 <–start address (2 bytes)
1WIRE WRITE: 0×00
1WIRE BULK READ, 0×08 BYTES: <–read back data
0×00 0×01 0×02 0×03 0×04 0×05 0×06 0×07
1WIRE BULK READ, 0×08 BYTES: <–read beyond our data
0×00 0×00 0×00 0×00 0×00 0×00 0×00 0×00
1-WIRE>

Command 0xf0 followed by a two byte memory address (0×00 0×00) begins the data read process. The first eight bytes (r:8) are the values we wrote earlier. Reads don’t involve the scratch pad and don’t have an 8byte limit, so further reads continue to the end of the memory.

Don’t forget to catch up on any parts posts you may have missed.

Our wallets are filling up with SIM and RFID cards that contain hidden information. Using our latest project, the Bus Pirate universal serial interface, we can dump the memory from many common smart cards. In today’s How-to, we show you how to interface common smart cards, and walk you through the data stored on a FedEx Kinko’s prepaid value card.

Background

The FedEx Kinko’s prepaid card is actually a SLE4442 smart card. There’s nothing secret about the SLE4442, it’s completely documented in the datasheet (PDF), and you can buy blank cards on the web.

The card is openly readable, we’ll be able to look at the contents without any sort of malicious intrusion. It’s protected from writes by a three byte password, with a ‘three strikes you’re out’ policy that renders the card useless after three failed password attempts.

Due to its wide-spread use, in Kinko’s and other capacities, the SLE4442 has been the target of several high-profile hacks.  At the ’06 Toorcon, [bunnie] and [Chris Tarnovsky] hosted a discussion on the card. [Chris] examined the silicon die and suggested that shorting a trace might defeat the security measures. You can see high-resolution images of the die on his site. [Strom Carlson] went right to the source and snooped the password with a logic analyzer, as documented in his famous ’06 Defcon presentation. The card even makes appearances in artwork.

We’re not planning on maliciously intruding on the card, but we can still look at the contents and demonstrate how to interface arbitrary protocols with our latest project, the Bus Pirate.

Connecting to the SLE4442

Grab the SLE4442 datasheet (PDF) if you haven’t already. The pinout is shown in the picture above. If you’re having trouble orienting the card, note that the large center pad connects to ground.

The card requires 5volts DC (datasheet page 27, table 3.2.2), we used the Bus Pirate’s handy 5volt supply. Interfacing at five volts is no problem because the Bus Pirate inputs are all 5volt tolerant.

A two-wire interface is used, with a clock line and bi-directional data line. We connected these to the Bus Pirate’s SDA and SCL pins. A third signal, reset, is required to initialize the chip; we used the Bus Pirate’s auxiliary output to control the reset line. The maximum clock frequency we can use to interface the device is 50kHz, with a 7kHz stated minimum (page 28, table 3.2.4:fCLK). The Bus Pirate’s raw 2 wire protocol runs at about 5kHz, but we didn’t have any problems interfacing the device.

The sle4442 has open collector outputs, and depends on pull-up resistors to hold the bus high. Instead of switching the data pin between ground and 5volts, it switches between ground and high-impedance states. High-impedance means that the chip exerts no state on the line, it lets it float, like a microcontroller input pin.

Each of the signal lines need to be pulled-up to 5volts with a 2K-10K resistor, the value isn’t particularly important.  Without the pull-up resistor, we’ll never see anything but 0 (ground) on the bus because the sle4442 doesn’t exert a voltage of it’s own. A benefit of this technique is that the Bus Pirate, which only switches at 3.3volts, will talk to the sle4442 at a full 5volts, in compliance with the 3.5volt minimum voltage for a high level (datasheet, page 27, table 3.2.3:Vih).

Initializing the card

Before we can read data from the card, we have to initialize it. This is done with a standard ISO 7816-3 Answer to Reset (ATR) command. After initialization, we can read from the card using a simple two wire protocol.

Setup raw 2 wire mode

The interface shares some characteristics with I2C, but it’s not compatible. We used the Bus Pirate’s raw 2 wire bus mode to interface the device.

RAW2>m
1. SPI
2. I2C
3. UART
4. RAW 2 WIRE
5. RAW 3 WIRE
MODE>4 <– raw 2 wire bus mode
900 MODE SET
…
SPEED>1 <– speed setting is ignored in current firmware
901 SPEED SET
1. High-Z outputs (H=input, L=GND)
2. Normal outputs (H=Vcc, L=GND)
MODE>1 <– high impedance output type
9xx OUTPUT HIGHZ
402 RAW2WIRE READY, P FOR PULLUPS
RAW2>

The Bus Pirate has on-board pull-up resistors, but they only pull to 3.3volts. We must use external pull-ups to 5volts, as shown in the picture. High-Z output mode is compatible with the bus, normal outputs would put 3.3volts on the bus, potentially damaging something.

RAW2>l <–configure MSB/LSB
1. MSB first
2. LSB first
MODE>2 <– LSB first
9xx LSB: LEAST SIG BIT FIRST
RAW2>

The card reads and writes each byte least significant bit first (datasheet page 10). We use menu option L to set the data mode to LSB first.

Send 7816-3 ISO answer to reset command

ISO 7816-3 “answer to reset” is a standardized command used among many smart cards. The ATR sequence is shown above: reset is held high, one clock pulse is sent, reset is released. The next 32 clock pulses (4 bytes) read a generic ATR header from the card. The header contains information about the card type and protocol. Multi-card smart card readers use this to determine how to read each card.

RAW2>@^arrrr <– aux high (highz), clock tick, aux low, read 4 bytes
952 AUX HIGH IMP, READ: 1
4xx RAW2WIRE 0×01 CLOCK TICKS
950 AUX LOW
430 RAW2WIRE READ: 0xA2 <–begin ATR header bytes
430 RAW2WIRE READ: 0×13
430 RAW2WIRE READ: 0×10
430 RAW2WIRE READ: 0×91
RAW2>

We issue the command @^arrrr to the Bus Pirate. @ puts the auxiliary pin in high-impedance input mode, the pull-up resistor holds the reset at 5volts. ^ issues one clock pulse, with delay. a returns the auxiliary pin to output and holds the reset line at ground.

r issues 8 clock pulses and displays the returned bits as a byte. This is one instance where the protocol is incompatible with I2C. I2C includes an additional acknowledge bit between each byte, the sle4442 outputs 32bits consecutively.

Page 25 of the datasheet explains the ISO7816-3 header. It’s easiest to interpret in binary. Rather than convert everything to binary, we set the Bus Pirate to binary display mode and issued another ATR command.

RAW2>o <–setup the output mode
1. HEX
2. DEC
3. BIN
4. RAW
OUTPUT MODE>3 <–show numbers in binary
903 OUTPUT MODE SET
RAW2>@^arrrr <–another ATR command
952 AUX HIGH IMP, READ: 1
4xx RAW2WIRE 0b00000001 CLOCK TICKS
950 AUX LOW
430 RAW2WIRE READ: 0b10100010 <–0xA2
430 RAW2WIRE READ: 0b00010011 <–0×13
430 RAW2WIRE READ: 0b00010000 <–0×10
430 RAW2WIRE READ: 0b10010001 <–0×91
RAW2>

The first 2 bytes are protocol header bytes according to ISO 7816-3 (datasheet page 25).

Byte 1 identifies the protocol type.

0b10100010
7:4 – Protocol type (1010=2 wire)
3:3 – RFU (0)
2:0 – Structure Identifier (010=general)

Byte 2, protocol parameters, tells us about the card if we didn’t have a datasheet.

0b00010011
7:7 – Supports random read lengths (0=no, read to end)
6:3 – Data units (0010=256units)
2:0 – Data unit bits (011=8bits per unit)

From the header we can tell that the protocol type is 10, a two wire bus. The card must be read all the way to the end before it accepts a new command. It has 8bits to a unit, and 256units; 256bytes total storage. The final two bytes are 7814-4 data, which seems uninteresting (see datasheet page 26).

Dump main memory (256 bytes)

Once the card is reset and the ATR bytes are read, we can send commands to the card. Commands are three bytes long; they begin with a I2C-style start condition, and end with an I2C-style stop condition. Start and stop conditions can be generated manually with \-/_\ and _/-\, but the raw 2 wire library also includes the shortcuts { and }. The start and stop conditions are the same as I2C, but they’re used at a different point in the transmission.

The read main memory command is 0×30, followed by a read start address (0), and a third byte that doesn’t matter (0xff).  After the stop condition, the card outputs data on every clock until it reaches the end of the memory.  As described by the ATR header, no new commands can be sent until the card reaches the last byte of memory.  Starting at read address 0, it takes 256*8 clock pulses to complete the read cycle.

RAW2>{0×30 0 0xff} 0r255 0r10 <–command
410 RAW2WIRE START CONDITION (\-/_\)
420 RAW2WIRE WRITE: 0×30
420 RAW2WIRE WRITE: 0×00
420 RAW2WIRE WRITE: 0×00
440 RAW2WIRE STOP CONDITION (_/-\)
431 RAW2WIRE BULK READ, 0xFF BYTES: <–bulk read of 255 bytes
0xA2 0×13 0×10 0×91 0×46 0xFF 0×81 0×15
0xFF 0×01 0x4B 0×03 0×00 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0xD2 0×76 0×00
0×00 0×04 0×09 0xFF 0xFF 0xFF 0xFF 0xFF
0x7B 0×14 0xAE 0×47 0xE1 0x7A 0×94 0x3F
0x4C 0×46 0xC6 0x3B 0×00 0×00 0×00 0×00
0×20 0×08 0×03 0×04 0×09 0x** 0x** 0x**
0×00 0×00 0×00 0×00 0×00 0×00 0×00 0×00
0×00 0×00 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
0×30 0×31 0×3* 0×3* 0×30 0×30 0×31 0×33
0×3* 0×3* 0×3* 0×00 0×00 0×00 0×00 0×00
0×00 0×00 0×00 0×00 0×43 0×61 0×73 0×68
0×20 0×43 0×75 0×73 0×74 0x6F 0x6D 0×65
0×72 0×00 0×00 0×00 0×00 0×00 0×00 0×00
0×00 0×00 0×00 0×00 0×00 0×00 0×00 0×39
0×39 0×31 0×31 0×00 0×31 0×30 0×31 0×00
0×30 0×30 0×30 0×30 0×30 0×00 0×00 0×00
0×00 0×00 0×00 0×00 0×00 0×00 0×00 0×00
0×00 0×00 0×00 0×00 0×00 0×00 0×00 0×00
0×00 0×00 0×00 0×03 0×00 0×00 0×01 0×00
0×00 0×00 0×00 0×00 0×00 0×00 0×00 0×00
0×00 0×00 0×00 0×00 0×00 0×00 0×00 0×20
0×08 0×03 0×04 0×09 0x** 0x** 0x** 0×00
0×00 0×00 0×00 0×00 0×00 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
0xFF 0xFF 0xFF 0xFF 0xFF 0×00 0×00
431 RAW2WIRE BULK READ, 0x0A BYTES: <–again to get last byte (256)
0×00 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
RAW2>

{ issues the bus start condition. 0×30 sends the read address, 0 is the start byte, and 0xff could be anything. } sends the bus stop condition. 0r255 clocks in 255 8bit bytes and displays them on the screen. The card actually has 256 bytes of main memory, so we issue an additional read command to get the last byte and verify that the bus returns to high after the read is over. We can’t use 0r256 because the Bus Pirate doesn’t understand decimal numbers greater than 255 (we should address that).

What does the data mean?

We dissected the card according the datasheet, [Strom]‘s Defcon presentation, and this handy guide (PDF).

32byte Header…

0xA2 0×13 0×10 0×91 <–The first four bytes are a repeat of the ATR data
0×46 0xFF 0×81 0×15<–manufacturer tags, other junk
0xFF 0×01 0x4B 0×03 0×00 <–ICCF, IC card fabricator id
0xFF 0xFF 0xFF 0xFF <–ICCN, IC serial number, 0
0xFF 0xFF 0xFF 0xFF<– misc tags and lengths, 0
0xD2 0×76 0×00 0×00 0×04 0×09 <–application identifier (Kinko’s?)
0xFF 0xFF 0xFF 0xFF 0xFF <–all other bytes 0

The first 32 bytes are a permanently burned header with serial numbers, manufacturer codes, and other unique data (datasheet page 24). This header prevents exact duplication of cards, even if you have a blank card and a security code. Kinko’s didn’t have a custom serial number permanently burned into each card.

Now data….

0x7B 0×14 0xAE 0×47 0xE1 0x7A 0×94 0x3F <– IEEE-754 value, $0.02

This is the value stored on the card, in IEEE-754 format. You can use this utility to make it readable. 0x3f947ae147ae147b=$0.02.

…8 bytes of junk…
0×20 <– 0×20 after copy, 0×00 after computer time
0×08 0×03 0×04 0×09 0x** 0x** 0x**<–date/time purchased

This is the date and time the card was purchased, 2008 March 4, 9:**:**.**. Some digits have been obscured to protect the anonymity of our supplier.

…40 bytes of junk…
0×30 0×31 0×3* 0×3* <–Store number: 01**
0×30 0×30 0×31 0×33 0×3* 0×3* 0×3* <– SN: 0013***

The card serial number consists of the store number and a unique, seven digit number. Some digits obscured.

…more bytes…
0×08 0×03 0×04 0×09 0x** 0x** 0x** <– another time
…more bytes…
0xFF 0xFF 0xFF 0xFF 0xFF 0×00 0×00 0×00<– last 8 bytes on the card
0xFF 0xFF… <-not real data bytes

Dump protection memory (4 bytes)

The first 32 bytes of the data memory can be write protected. Each bit of the four byte data protection register (command 0×34) represents a byte of data memory. A bit set to 1 cannot be overwritten. We can read the data protection register and find out which bytes of the main memory are write protected. This is easiest to understand in binary, so we did this operation in binary output mode.

RAW2>{0×34 0 0} 0r4 <–command
410 RAW2WIRE START CONDITION (\-/_\)
420 RAW2WIRE WRITE: 0b00110100
420 RAW2WIRE WRITE: 0b00000000
420 RAW2WIRE WRITE: 0b00000000
440 RAW2WIRE STOP CONDITION (_/-\)
431 RAW2WIRE BULK READ, 0b00000100 BYTES:
0b00100000 0b11100001 0b00011111 0b11111000 <–data protection register
RAW2>

Each bit corresponds with one of the first 32 bytes of the card memory. If the bit is one, the corresponding byte is write protected. This register can be written, but only if you have the correct password.

Dump security memory (4 bytes)

The security memory contains a password verification attempt counter, and the three byte password. We can read the read the security memory without the password, but the password bytes will read as 0. The security memory address is 0×31.

RAW2>{0×31 0 0} 0r4 <–command
410 RAW2WIRE START CONDITION (\-/_\)
420 RAW2WIRE WRITE: 0b00110001
420 RAW2WIRE WRITE: 0b00000000
420 RAW2WIRE WRITE: 0b00000000
440 RAW2WIRE STOP CONDITION (_/-\)
431 RAW2WIRE BULK READ, 0b00000100 BYTES:
0b00000100 0b00000000 0b00000000 0b00000000<–bytes
RAW2>

The attempt counter starts at three (0b00000111), and counts down to 0. When the counter reads 0, the card is essentially destroyed. We used two access attempts to test the password commands, this card has one try left.

Taking it further

We’d like to demonstrate all the capabilities of this card, including password verification and data updates, but we need to buy a new card with a known security code.

Due to the range of interesting smart cards cards out there, it might be handy to add an ISO 7816-3 ATR command macro and reply decoder to the Bus Pirate.