ESP32-HUB75-MatrixPanel-DMA/README.md

136 lines
6.1 KiB
Markdown
Raw Normal View History

2020-07-29 09:47:54 +02:00
# HUB75 LED matrix library for the ESP32, utilising DMA
2018-10-23 02:00:47 +02:00
2020-08-13 15:16:42 +02:00
This ESP32 Arduino library for an 64x32 RGB LED (HUB 75 type) 1/16 Scan LED Matrix Panel, utilises the DMA functionality provided by the ESP32's I2S 'LCD Mode' which basically means that pixel data is sent straight from memory, via the DMA controller, to the relevant LED Matrix GPIO pins with little CPU overhead.
2018-10-23 02:00:47 +02:00
2020-07-29 09:47:54 +02:00
As a result, this library can theoretically provide ~16-24 bit colour, at various brightness levels without noticeable flicker.
2018-10-23 02:09:16 +02:00
2020-08-13 15:17:47 +02:00
## Panels Supported
62x32 pixel 1/16 Scan LED Matrix 'Indoor' Panel, such as this [typical RGB panel available for purchase](https://www.aliexpress.com/item/256-128mm-64-32-pixels-1-16-Scan-Indoor-3in1-SMD2121-RGB-full-color-P4-led/32810362851.html).
2020-08-11 13:42:54 +02:00
2020-08-13 15:17:47 +02:00
## Panels Not Supported
* 1/8 Scan LED Matrix Panels are not supported, please use an alternative library if you bought one of these.
* Chinese junk panels based on FMXXXX chipsets. This library does not support these panels. FM6126 panels based on [this untested example](/examples/FM6126Panel) could work however.
2018-10-23 02:11:30 +02:00
2018-10-23 02:00:47 +02:00
# Installation
* Dependency: You will need to install Adafruit_GFX from the "Library > Manage Libraries" menu.
2020-07-29 09:47:54 +02:00
* Download and unzip this repository into your Arduino/libraries folder (or better still, use the Arduino 'add library from .zip' option.
* Library also tested to work fine with PlatformIO, install into your PlatformIO projects' lib/ folder as appropriate.
2018-10-29 23:57:10 +01:00
2018-10-23 02:00:47 +02:00
# Wiring ESP32 with the LED Matrix Panel
By default the pin mapping is as follows (defaults defined in ESP32-RGB64x32MatrixPanel-I2S-DMA.h).
2018-10-23 02:00:47 +02:00
```
HUB 75 PANEL ESP 32 PIN
+-----------+
| R1 G1 | R1 -> IO25 G1 -> IO26
| B1 GND | B1 -> IO27
| R2 G2 | R2 -> IO14 G2 -> IO12
| B2 GND | B2 -> IO13
2019-07-13 21:00:25 +02:00
| A B | A -> IO23 B -> IO19
| C D | C -> IO 5 D -> IO17
| CLK LAT | CLK -> IO16 LAT -> IO 4
| OE GND | OE -> IO15 GND -> ESP32 GND
2018-10-23 02:00:47 +02:00
+-----------+
```
However, if you want to change this, simply provide the wanted pin mapping as part of the display.begin() call. For example, in your sketch have something like the following:
```
// Change these to whatever suits
#define R1_PIN 25
#define G1_PIN 26
#define B1_PIN 27
#define R2_PIN 14
#define G2_PIN 12
#define B2_PIN 13
#define A_PIN 23
#define B_PIN 22
#define C_PIN 5
#define D_PIN 17
#define E_PIN -1
#define LAT_PIN 4
#define OE_PIN 15
#define CLK_PIN 16
display.begin(R1_PIN, G1_PIN, B1_PIN, R2_PIN, G2_PIN, B2_PIN, A_PIN, B_PIN, C_PIN, D_PIN, E_PIN, LAT_PIN, OE_PIN, CLK_PIN ); // setup the LED matrix
```
2018-10-24 00:58:49 +02:00
The panel must be powered by 5V AC adapter with enough current capacity. (Current varies due to how many LED are turned on at the same time. To drive all the LEDs, you need 5V4A adapter.)
2020-08-14 11:02:58 +02:00
# How to Use
2020-08-14 11:21:31 +02:00
Below is a bare minimum sketch to draw a single white dot in the top left. You must call .begin() before you call ANY pixel-drawing (fonts, lines, colours etc.) function of the RGB64x32MatrixPanel_I2S_DMA class.
2020-08-14 11:02:58 +02:00
2020-08-14 11:21:31 +02:00
No .begin() before other functions = Crash
2020-08-14 11:02:58 +02:00
```
#include <ESP32-RGB64x32MatrixPanel-I2S-DMA.h>
RGB64x32MatrixPanel_I2S_DMA matrix;
void setup()
{
// MUST DO THIS FIRST!
matrix.begin(); // Use default pins supplied within ESP32-RGB64x32MatrixPanel-I2S-DMA.h
// matrix.begin(R1_PIN, G1_PIN, B1_PIN, R2_PIN, G2_PIN, B2_PIN, A_PIN, B_PIN, C_PIN, D_PIN, E_PIN, LAT_PIN, OE_PIN, CLK_PIN ); // or custom pins
// Draw a single white pixel
2020-08-14 11:06:07 +02:00
matrix.drawPixel(0,0, matrix.color565(255,255,255)); // can do this after .begin() only
2020-08-14 11:02:58 +02:00
}
void loop()
2020-08-14 11:06:07 +02:00
{ }
2020-08-14 11:02:58 +02:00
```
2018-10-24 00:58:49 +02:00
2020-09-06 18:22:51 +02:00
## Can I use with a larger panel (i.e. 64x64px square panel)?
2020-08-15 16:38:06 +02:00
If you want to use with a 64x64 pixel panel (typically a HUB75*E* panel) you MUST configure a valid *E_PIN* to your ESP32 and connect it to the E pin of the HUB75 panel! Hence the 'E' in 'HUB75E'
2018-10-24 00:58:49 +02:00
2020-09-06 18:22:51 +02:00
## Can I chain panels?
Yes. If you want to chain two of these horizontally to make a 128x32 panel you can easily by setting the MATRIX_WIDTH to '128' and connecting the panels in series using the HUB75 ribbon cable.
2020-08-03 15:17:03 +02:00
Similarly, if you wanted to chain 4 panels to make a 256x32 px horizontal panel, you can easily by setting the MATRIX_WIDTH to '256' and connecting the panels in series using the HUB75 ribbon cable.
2020-09-06 18:24:51 +02:00
Finally, if you wanted to chain 4 x (64x32px) panels to make 128x64px display (essentially a 2x2 grid of 64x32 LED Matrix modules), a little more magic will be required. Refer to the [Chained Panels](examples/ChainedPanels/) example.
2020-08-02 23:47:02 +02:00
2020-08-15 16:38:06 +02:00
Resolutions beyond 128x128 are likely to result in crashes due to memory constraints etc. You're on your own at this point.
2020-08-03 15:51:48 +02:00
2020-08-11 21:49:36 +02:00
![ezgif com-video-to-gif](https://user-images.githubusercontent.com/12006953/89837358-b64c0480-db60-11ea-870d-4b6482068a3b.gif)
2020-09-06 18:33:39 +02:00
## Panel Brightness
2019-07-31 00:37:40 +02:00
2020-09-06 18:33:39 +02:00
By default you should not need to change / set the brightness setting as the default value (16) is sufficent for most purposes. Brightness can be changed by calling `setPanelBrightness(XX)` and then `clearScreen()`.
2020-09-06 18:31:21 +02:00
The value to pass 'setPanelBrightness' must be a value less than MATRIX_WIDTH. For example for a single 64x32 LED Matrix Module, a value less than 64. However, if you set the brightness too high, you may experience ghosting.
Example:
2019-07-29 14:27:52 +02:00
```
void setup() {
Serial.begin(115200);
matrix.begin(R1_PIN, G1_PIN, B1_PIN, R2_PIN, G2_PIN, B2_PIN, A_PIN, B_PIN, C_PIN, D_PIN, E_PIN, LAT_PIN, OE_PIN, CLK_PIN ); // setup the LED matrix
2020-09-06 18:31:21 +02:00
matrix.setPanelBrightness(16); // Set the brightness. 32 or lower ideal for a single 64x32 LED Matrix Panel.
2020-08-14 11:09:53 +02:00
matrix.clearScreen(); // You must clear the screen after changing brightness level for it to take effect.
2019-07-29 14:27:52 +02:00
}
```
2020-09-06 18:33:39 +02:00
Summary: setPanelBrightness(xx) value can be any number from 0 (display off) to MATRIX_WIDTH-1. So if you are chaining multiple 64x32 panels, then this value may actually be > 64 (or you will have a dim display). Changing the brightness will have a huge impact on power usage.
2020-08-25 00:51:33 +02:00
2020-08-13 15:17:47 +02:00
![It's better in real life](image.jpg)
2020-07-29 09:47:54 +02:00
## Inspiration
2018-10-24 00:58:49 +02:00
* 'SmartMatrix' project code: https://github.com/pixelmatix/SmartMatrix/tree/teensylc
* Sprite_TM's demo implementation here: https://www.esp32.com/viewtopic.php?f=17&t=3188
2018-10-23 02:09:16 +02:00