Briefly: using an Adafruit LED Matrix with the Raspberry Pi

gistfile1.md

Adafruit sells an 8x8 LED matrix which you can control from a Raspberry Pi using I2C. Unfortunately they only provide Arduino code; I've only used I2C through the programs i2cset, i2cget, i2cdump and i2cdetect available from the i2c-tools package; and it wasn't immediately obvious how to use Adafruit's code to control the matrix from the Pi.

Fortunately, it turns out to be quite simple. i2c-tools seems to assume a register-based model of I2C devices, where the target device has up to 256 pointers which can be read and written. This doesn't seem to suit the HT16K33 chip (datasheet) that the matrix backpack uses. For example, when I ran i2cdump, which gets the value of each register, it started to blink a picture at me. At least I knew it was working.

Setting individual LEDs works much as you might expect. Every row has a single register, the eight bits of that register correspond to the eight LEDs on a row. (It's not 100% intuitive. If you label the LEDs 0 through 7 from left to right, and the bits 0 through 7 from LSB to MSB, then bit n corresponds to LED n+1 mod 8.) The registers in question are 0x00, 0x02, ..., 0x0e. Registers 0x01, 0x03, etc. seem to correspond to other LED rows that don't exist on this matrix, but presumably do on the bicolour version.

So to turn on the top-left pin for example, run i2cset -y 0 $ADDRESS 0x00 0x80. (By default, the address of the device is 0x70. This can be set up to 0x73 using two address-set pins, but I'm not sure how to use these. Each pin seems to be a pair of conductive plates close to each other on the backpack. My guess is connecting these will turn the pin on, but I'm not sure if there's a standard thing I'm meant to connect them with.)

But you can also turn the whole matrix on/off, set blink rate, and set brightness. Each of these commands also corresponds to a register, but not in the same way. Interacting with the register in any way will run a command. For example, register 0xe0 is "turn brightness all the way down", so any of the following will do that:

i2cget -y 0 $ADDRESS 0xe0
i2cset -y 0 $ADDRESS 0xe0
i2cset -y 0 $ADDRESS 0xe0 $val # for any legal $val, e.g. 0x00, 0xff

Similarly, 0x87 is the "turn display on and blink at 0.5 Hz" register, and is the highest-address register of that nature. So running i2cdump will cycle through all combinations of on/off and blink modes, and finish on that one.

Here are the registers that I've found that I care about (except the LED registers):

• Display setup: 0x80 through 0x87. Binary 10000cba, where a is 1 to turn the display on or 0 to turn it off; cb sets blink mode to off (00), 2Hz (01), 1Hz (10) or 0.5Hz (11). (Actually, registers 0x88 through 0x8f do exactly the same, in the same order. So i2cdump cycles through blink modes twice.)
• Brightness: 0xe0 through 0xef. Higher registers are brighter.

There also seem to be read-only registers corresponding to key input, which I assume is just a feature of the chip not used for the LED matrix; and write-only registers putting the chip in and out of standby mode (which I guess uses less power than simply turning the display off). More information is available in the datasheet, which I've only skimmed.