Arduino Driver for Shift Register LED Matrices

This library provides a generalized API to create and drive an image on LED matrix where shift registers, such as the 74HC595 or DM13a, are used to control the rows and columns of the matrix. Both single color and RGB LED matrices are supported. To use this driver in the Arduino IDE, add the folder ShiftRegisterLEDMatrixLib as a library as described in this document, or install via the libraries manager in the Arduino IDE. This driver also depends on the Adafruit GFX Library v1.9.0 or later, which can be installed via the libraries manager.

This driver uses SPI to transfer bits to the shift registers and uses one timer interrupt.

Find at more about this library and hardware that it is designed for at: www.kamprath.net/hacks/led-matrix/

Design and Usage

Hardware Design

The general hardware design of the matrix is to use shift registers to drive the matrix. This library can support either common anode or common cathode RGB LEDs, but default settings assume common anode.

Consider the following 4x4 matrix using common anode RGB LEDs as an example:

                 Serial Bit Stream
                          |
 RGB--RGB--RGB--RGB- R1  LSB
 |||  |||  |||  |||       |
 RGB--RGB--RGB--RGB- R2   |
 |||  |||  |||  |||       |
 RGB--RGB--RGB--RGB- R3   |
 |||  |||  |||  |||       |
 RGB--RGB--RGB--RGB- R4   |
 |||  |||  |||  |||       |
 CCC  CCC  CCC  CCC       |
 000  000  000  111       |
 123  456  789  012       |
                          |
 MSB <--------------------+

In this example, the RGB LED common anodes are connected into rows, and the cathodes are connected into columns aligned with the colors of each LED. To light any particular LED color, its row should be powered and the column sinked. If common cathode LEDs were used instead, this would be swapped with the rows becoming sinks and the columns being power source. The shift registers are connected in serial such that the most significant bit (MSB) being the first LED column and the least significant bit (LSB) being the first row.

Since there are 16 bits needed to control the rows and columns, two 74HC595 shift registers will be used. The first one, U1, will contain the MSB, which will be the first bit shifted out. Give that, U1 should be a downstream slave to U2 and the MSB ultimately will reside in the Q7 pin of U1. U1's SER pin will need to be connected to the SER' (aka Q7') pin on U2. The input serial stream flows into U2, so the LSB will be on Q0 of U2.

In this case, Q7 of the first 74HC595 (U1) would be attached to C01, Q6 to C02, and so on. Since there are 12 column and 4 rows, two 8-bit shift registers are needed. So the second 74HC595 (U2) would have its Q0 through Q3 attached to R1 through R4, and its Q4 through Q7 attached to C12 down through C09. In this configuration, the first bit shifted out in an update cycle is for C01, and the last bit shifted out is for R1.

In this common anode set up, the rows would be "on" when the proper 74HC595 pin is in the high state and the column would "on" when its respective pin is in the low state. Basically, the shift register is sinking the columns and powering the rows. However, since the 74HC595 cannot source enough power to drive the multiple LEDs in the row, you might use a PNP transistor to drive the row. In this case, the row would be on if the its pin on the 74HC595 is low, which turns on the PNP transistor allowing current to flow.

Other similar designs can be used with this library. Common variations would be:

Using a DM13A sink driver to drive the cathode columns. It is not recommended to use a DM13A to drive the rows for common cathode RGB LEDs due to high current needs to drive the multiple LEDs in a single row. Using DM13A chips for the columns is nice because you can forgo the current limiting resistor for each column and the DM13A does the job of limiting the current.
Using common cathode RGB LEDs. In this case NPN transistors would be used to sink the current for a row, and columns are sourced with the current of the high state on a 74HC595 pin.
When using a common anode RGB LEDs, you could use a source driver, such as a UDN2981, to drive a row. This would be turned on with a high state on the row's shift register pin.
Rather than ordering the column bits as alternating through R, G, and B colors, each color can be grouped together. This is convenient when using manufactured LED matrix modules that group the pins by colors rather than by columns. See Bit Layouts.

Library Architecture

This library has three general facets: image handling, matrix driver, and animation management.

Image Handling

All image drawing is handled by the Adafruit GFX API. Please refer to its documentation for information on how to draw an image to a matrix.

For RGB color matrices, there are two color modes supported: 9 bit and 16 bit color. Color for the image is represented by a RGBColorType value. When the preprocessor macro SIXTEEN_BIT_COLOR is defined to 1, RGBColorType will use following bit layout (notice green gets 6 bits while red and blue each get 5 bits):

	Bits   0   4   8   12
		   |---|---|---|---
 		   RRRRRGGGGGGBBBBB

	R = Red
	G = Green
	B = Blue

Color can easily be set in hexadecimal format. For example, the following colors are defined in RGBColor.h:

const RGBColorType RED_COLOR_MASK = 0xF800;
const RGBColorType GREEN_COLOR_MASK = 0x07E0;
const RGBColorType BLUE_COLOR_MASK = 0x001F;

const RGBColorType AQUA_COLOR = GREEN_COLOR_MASK|BLUE_COLOR_MASK;
const RGBColorType BLACK_COLOR = 0;
const RGBColorType BLUE_COLOR = BLUE_COLOR_MASK;
const RGBColorType BROWN_COLOR = 0xA145;
const RGBColorType CORAL_COLOR = 0xF8E5;
const RGBColorType DARK_BLUE_COLOR = 0x0004;
const RGBColorType DARK_GRAY_COLOR = 0x821;
const RGBColorType DARK_GREEN_COLOR = 0x0020;
const RGBColorType DARK_RED_COLOR = 0x0800;
const RGBColorType GRAY_COLOR = 0x39E7;
const RGBColorType GREEN_COLOR = GREEN_COLOR_MASK;
const RGBColorType LIME_COLOR = 0x1983;
const RGBColorType MAGENTA_COLOR = 0xF81F;
const RGBColorType ORANGE_COLOR = 0xF8E0;
const RGBColorType PINK_COLOR = 0xF8B2;
const RGBColorType PURPLE_COLOR = 0x3807;
const RGBColorType RED_COLOR = RED_COLOR_MASK;
const RGBColorType SKY_BLUE_COLOR = 0x867D;
const RGBColorType SLATE_BLUE_COLOR = 0x6ADB;
const RGBColorType TURQUOISE_COLOR = 0x471A;
const RGBColorType VIOLET_COLOR = 0x901A;
const RGBColorType WHITE_COLOR = 0xFFFF;
const RGBColorType YELLOW_COLOR = RED_COLOR_MASK|GREEN_COLOR_MASK;

When the preprocessor macro SIXTEEN_BIT_COLOR is defined to 0, the library will use a subset of bits RGBColorType that effectively makes the color range based on 3 bits per red, green, and blue. This is done automatically, and you can still use the 16 bit color definitions illustrated above.

Matrix Driver

The matrix driver is an object that manages rendering an image on an LED matrix. It does this using a double buffer approach. The first buffer is the image that is desired to be rendered on the LED matrix. The second buffer is the bit sequences that needs to be sent to the LED matrix's shift registers to render the image. The matrix driver object uses SPI to send the bits to the shift register. Since the rows on the matrix are multiplexed when rendering, the matrix driver object will use a system clock interrupt to ensure the multiplexing is consistently timed.

When constructing a matrix driver, you need to tell it a few details:

The matrix's size in rows and columns
Whether the shift registers used for controlling columns should be set to HIGH or LOW to turn on the column.
Whether the shift registers used for controlling rows should be set to HIGH or LOW to turn on the row
The length of the delay that should be present between turning on each rows while multiplexing. By default, this delay is set to zero (no delay). However, if you are using slow switch for the row's power, such as a UDN2981 which has a 2 microsecond turn off time, introducing a short period of all rows being off in between each row update can eliminate LED ghosting.
The pin which will be used to send the latch signal.

LEDMatrix

The LEDMatrix driver is used for matrices of single color LEDs. This driver uses the Adafruit GFX API to draw to the image buffer. However, it only supports two colors:

typedef uint16_t LEDColor;

const LEDColor LED_BLACK = 0; // same as LED off
const LEDColor LED_WHITE = 1; // same as LED on

RGBLEDMatrix

The RGBLEDMatrix driver is used for matrices of RGB color LEDs. This driver uses the Adafruit GFX API to draw to the image buffer.

In addition to the basic options listed above, when constructing an RGBLEDMatrix object, you need to indicate the shift register bit layout for the RGB columns. See the Bit Layouts section of this document.

Animation Management

TimerAction

A TimerAction object allows you to manage a variably timed action in a manner that does not require the use of a clock interrupt. Since timer interrupts are not used, the timing of action may not be precise, so this class should only be used for actions that are not sensitive to some variability in the action timing. The object has a loop() method that should be called in every call to the global loop() method.

Usage

The basic pattern of usage is:

Create a LEDMatrix or RGBLEDMatrix matrix object passing the appropriate arguments
In the global setup() method, call the setup() method of the matrix object to initialize all fields. Then call startScanning() on the matrix

ShiftRegisterLEDMatrixLib

Install / Use

README