|
1 | 1 | # Arduino Driver for Shift Register LED Matrix |
2 | 2 |
|
3 | | -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. To use this driver in the Arduino IDE, add the folder `ShiftRegisterLEDMatrixLib` as a library as described in [this document](https://www.arduino.cc/en/Guide/Libraries), or install via the libraries manager in the Arduino IDE. |
| 3 | +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](https://www.arduino.cc/en/Guide/Libraries), or install via the libraries manager in the Arduino IDE. |
4 | 4 |
|
5 | 5 | This driver uses SPI to transfer bits to the shift registers and uses one timer interrupt. |
6 | 6 |
|
7 | 7 | Find at more about this library and hardware that it is designed for at: |
8 | 8 | [www.kamprath.net/led-matrix/](http://www.kamprath.net/led-matrix/) |
9 | 9 |
|
10 | | -# General Design |
11 | | -This library has three general facets: image representation, matrix driver, and animation management. |
| 10 | +# Design and Usage |
| 11 | +## Architecture |
| 12 | +This library has three general facets: image handling, matrix driver, and animation management. |
| 13 | + |
| 14 | +### Image Handling |
| 15 | +#### Glyph |
| 16 | +A Glyph is a black and white image with no gray scale. There are two types of Glyphs, the immutable `Glyph` object and the mutable `MutableGlyph` object. The advantage of the immutable `Glyph` object is that it can be initialized with a `PROGMEM` block, thus reducing the RAM footprint for statically constructed `Glyph` objects. |
| 17 | + |
| 18 | +There are two ways to initialize a `Glyph` object: with a bit array and with a boolean array. The bit array approach use a bit sequence as long of the Glyph's rows\*columns, and the bit sequence is stored in an appropriately sized `char` array. If being constructed instead with a boolean array, the `bool` array should be as long os the Glyph's row\*columns size. |
| 19 | +#### RGBImage |
| 20 | +A RGBImage is a color image using one of two color modes: 6 bit and 12 bit. There are two types of RGBImage object, the immutable `RGBImage` object and the mutable `MutableRGBImage` object. The advantage of the immutable `RGBImage` object is that it can be initialized with a `PROGMEM` block, thus reducing the RAM footprint for statically constructed `RGBImage` objects. |
| 21 | + |
| 22 | +Color for the image is represented by a `ColorType` value. When the preprocessor macro `TWELVE_BIT_COLOR` is defined to `1`, `ColorType` will be an `unsigned int` with the following bit layout: |
| 23 | + |
| 24 | +``` |
| 25 | +Bits 0 4 8 12 |
| 26 | + |---|---|---|--- |
| 27 | + TUUURRRRGGGGBBBB |
| 28 | +
|
| 29 | + T = transparent |
| 30 | + U = unused |
| 31 | + R = Red |
| 32 | + G = Green |
| 33 | + B = Blue |
| 34 | +``` |
| 35 | +Color can easily be set in hexadecimal format, as the 2nd byte is red, the third byte is green, and the fourth byte is blue. The left most bit of the first byte is used to indicate whether the color is transparent or not. For operations that support transparency, any other color bits are ignored when the transparency bit is set. Transparency is primarily used when drawing one `RGBImage` onto another. Transparent colors will not change the color of the underlying pixel the `RGBImage` is being drawn on top of. |
| 36 | + |
| 37 | +When the preprocessor macro `TWELVE_BIT_COLOR` is defined to `0`, `ColorType` will be an `unsigned char` with the following bit layout: |
| 38 | + |
| 39 | +``` |
| 40 | +Bits 0 4 |
| 41 | + |---|--- |
| 42 | + TURRGGBB |
| 43 | + |
| 44 | + T = transparent |
| 45 | + U = unused |
| 46 | + R = Red |
| 47 | + G = Green |
| 48 | + B = Blue |
| 49 | +``` |
| 50 | + |
| 51 | +An `RGBImage` can be initialized with an array of `ColorType` values sized to be the image's rows\*columns. |
| 52 | +### Matrix Driver |
| 53 | +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 drive 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. |
| 54 | + |
| 55 | +When constructing a matrix driver, you need to tell it a few details: |
| 56 | +* The matrix's size in rows and columns |
| 57 | +* Whether the shift registers used for controlling columns should be set to `HIGH` or `LOW` to turn on the column. |
| 58 | +* Whether the shift registers used for controlling rows should be set to `HIGH` or `LOW` to turn on the row |
| 59 | +* The pin which will be used to send the latch signle. |
| 60 | + |
| 61 | +#### LEDMatrix |
| 62 | +The `LEDMatrix` driver is used for matrices of single color LEDs. This drive uses a `MutableGlyph` as its image buffer. |
| 63 | +#### RGBLEDMatrix |
| 64 | +The `RGBLEDMatrix` driver is used for matrices of RGB color LEDs. This drive uses a `MutableRGBImage` as its image buffer. |
| 65 | + |
| 66 | +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. |
| 67 | +### Animation Management |
| 68 | +#### TimerAction |
| 69 | +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. |
| 70 | +## Usage |
| 71 | +The basic pattern of usage is: |
| 72 | + |
| 73 | +1. Create a `LEDMatrix` or `RGBLEDMatrix` matrix object passing the appropriate arguments |
| 74 | +1. In the global `setup()` method, call the `setup()` method of the matrix object to initialize all fields. This call `startScanning()` on the matrix object to cause but to be transmitted to the shift registers in the matrix. |
| 75 | +1. Draw to the `image()` object on the matrix object, but do call the `startDrawing()` matrix object method prior to any drawing, and balance the call with a call to `stopDrawing()` on the matrix object. These method prevent the image display on the matrix from being altered while you are drawing to it. |
12 | 76 |
|
13 | | -_detailed documentation TBD_ |
14 | 77 |
|
15 | 78 | # Notes |
16 | 79 | ## Driver Boards |
@@ -48,27 +111,27 @@ ESP8266 boards are generally 3.3v logic level boards. |
48 | 111 | ### 3.3v Logic Level |
49 | 112 | To use the RGB LED Matrices designed in this project with micro-controller boards that use a 3.3V logic level, you must convert the 3.3V logic signals to 5V levels to work with the shift registers. You can easily use a 74HCT125 buffer/line driver chip to do this transformation. For example, you can wire a Teensy 3.6, which is a 3.3v device, to a 74HCT125 chip in the manner shown in the diagram below to get all power and signal lines required to drive the RGB LED Matrix while the Teensy is connected to USB power: |
50 | 113 |
|
51 | | - |
| 114 | + |
52 | 115 |
|
53 | 116 | An alternative to using this 74HCT125 circuit would be to replace the 74HC595 shift registers on the RGB LED Matrix with the 74HCT595 variety. However, this might be more expensive. |
54 | 117 |
|
55 | 118 |
|
56 | 119 | ## RGB LEB Matrices |
57 | 120 | ### Color Modes |
58 | | -This driver can support either 6-bit or 24-bit color. By default, this library uses 6-bit color. You can enable 24 bit color in this library by setting the preprocessor macro `TWENTY_FOUR_BIT_COLOR` to a value of 1 (note, not in your `ino` file, but at compile time for all files). You can do this either by editing the `RGBImage.h` file or setting a compiler flag. However, note that 24 bit color requires more RAM than an Arduino Uno or Nano has. Due its memory requirements, 24 bit color should work on most 32 bit boards and the Arduino Mega 2560. 24 bit color has been tested to work on the following boards: |
| 121 | +This driver can support either 6-bit or 12-bit color. By default, this library uses 6-bit color. You can enable 12 bit color in this library by setting the preprocessor macro `TWELVE_BIT_COLOR` to a value of 1 (note, not in your `ino` file, but at compile time for all files). You can do this either by editing the `RGBImage.h` file or setting a compiler flag. However, note that 12 bit color requires more RAM than an Arduino Uno or Nano has. Due its memory requirements, 12 bit color should work on most 32 bit boards and the Arduino Mega 2560. 12 bit color has been tested to work on the following boards: |
59 | 122 |
|
60 | 123 | * Teensy 3.6 |
61 | 124 | * Arduino Mega 2560 |
62 | 125 | * Wemos D1 mini Lite |
63 | 126 | * NodeMCU |
64 | 127 |
|
65 | 128 | ### Bit Layouts |
66 | | -This driver can support two different bit layouts. The default bit layout assumes each RGB LED is a single unit and each column is wired up with the RGB bits consecutively. That is, for a 4x4 matrix, the bit layout would look like this: |
| 129 | +This driver can support two different bit layouts for RGB LED matrices. The default bit layout assumes each RGB LED is a single unit and each column is wired up with the RGB bits consecutively. That is, for a 4x4 matrix, the bit layout would look like this: |
67 | 130 |
|
68 | | - |
| 131 | + |
69 | 132 |
|
70 | 133 | The second supported bit layout groups all colors together in column order, then sends each color group in Red-Green-Blue order. For a 4x4 matrix, the bit layout would look like this: |
71 | 134 |
|
72 | | - |
| 135 | + |
73 | 136 |
|
74 | | -When constructing the the `RGBLEDMatrix` object, the fourth argument is optional and it take a `RGBLEDBitLayout` enum value indicating which bit layout you are using. This argument defaults to `INDIVIDUAL_LEDS`, which is the first layout described above. The other potential value is `RGB_GROUPS`. |
| 137 | +When constructing the the `RGBLEDMatrix` object, the third argument is optional and it take a `RGBLEDBitLayout` enum value indicating which bit layout you are using. This argument defaults to `INDIVIDUAL_LEDS`, which is the first layout described above. The other potential value is `RGB_GROUPS`. |
0 commit comments