kien242 / esp-rgb-led-matrix

Full RGB LED matrix, based on an ESP32 and WS2812B LEDs.

PIXELIX

Full RGB LED matrix, based on an ESP32 and WS2812B LEDs.

• PIXELIX
• Motivation
• Overview
  • Original setup
  • Others
• Installation
• Very First Startup
• User Interface
• Documentation
• Used Libraries
• FAQ
  • Where to change panel topology of the LED matrix?
  • How to change text properties?
  • The display only shows a error code, like "E4". What does that mean?
  • How can I use animated icons?
  • How do I know that my sensor is recognized?
  • Why do I see sometimes values from the LDR in the SensorPlugin, although no LDR is installed?
  • How can I use alternative icons?
• Issues, Ideas And Bugs
• License
• Contribution

Motivation

I want to have a remote display to show multiple kind of information, running 24/7 reliable. Connected over wifi to the local network, it can be controlled via REST API or websocket.

Some impressions
	...

Overview

The firmware contains a plugin concept (at compile time) to provide different functionalities. Each plugin can create its own layout and place the information as required. If you are only interesting in showing just text provided via REST API, choose the JustTextPlugin. It uses the whole display size and will scroll text automatically. Sometimes in front of the text a nice icon is required in which case choose the IconTextPlugin. These are only examples and you will find more in the plugin list.

A little bit more detail about the generic plugins and the first idea can be found in this rough overview.

Original setup

The original setup during development and the first release was:

• ESP32 DevKitV1
• WS2812B 5050 8x32 RGB Flexible LED Matrix Panel
• Power supply 5 V / 4 A

The following shows the absolute minimal wiring setup:

⚠️ If you power all via USB: Be very careful, because it may destroy your esp32 board if the LED current gets too high. Avoid increasing the LED display brightness or filling it complete with white pixels. Please use a external power supply with at least 5V / 4A.

Others

In the meantime several other board are supported as well. You can see them in the platformio configuration (platformio.ini) or the list of boards.

Additional supported variants, which were original not in focus:

• TTGO T-Display ESP32 WiFi and Bluetooth Module Development Board For Arduino 1.14 Inch LCD

Although Pixelix was designed to show information, that is pushed or pulled via REST API, the following sensors can be directly connected and evaluated:

• Temperature and humidity sensors DHTx
• Temperature and humidity sensors SHT3x
• Digitial microphone INMP441 for some sound reactive stuff.

Installation

The following steps are necessary for the first time and to get PIXELIX initial running on the target. Once it runs, later on the firmware and filesystem can be updated via the PIXELIX webinterface.

1. Setup the toolchain.
2. Build the software and check whether the toolchain works.
3. Upload/Update the software and firmware to the target.

Very First Startup

If the device starts the very first time, the wifi station SSID and passphrase are empty. To be able to configure them, start the device and keep the button pressed until it shows the SSID. The device will start up as wifi access point with the default SSID "pixelix" and the default password "Luke, I am your father.". The display itself will show the SSID of the webserver.

Connect to the captive portal and configure via webinterface the wifi station SSID and passphrase. Use the default user name "luke" and the default password "skywalker" for authentification to access the webinterface.

Restart and voila!

User Interface

• The user button activates always the next slot.
• If the display's location is hard to reach, the virtual user button can be used. It is controllable via REST API and perfect for remote buttons like the Shelly Button 1.
• If a ambilight sensor (LDR) is connected, the display brightness is automatically adapted.
• The web interface provides the possibilty to install plugins, control their duration in the slots and etc.
• Some plugin's spawn a dedicated REST API, see the web page of the plugin or have a look to the REST API documentation.

Note, the websocket interface is currently only used as a service in the web interface.

Documentation

For more information, see the documentation.

Used Libraries

• Arduino - ESP32 Arduino framework - Apache-2.0 License
• NeoPixelBus - Controlling the LED matrix with hardware support (RMT) - LGPL-3.0 License
• ESPAsyncWebServer - Webserver - LGPL-2.1 License
• AsyncTCPSock - TCP library, Reimplementation of the API of me-no-dev/AsyncTCP using high-level BSD sockets - LGPL-3.0 License
• ArduinoJson - JSON handling - MIT License
• StreamUtils - Stream utilities - MIT License
• Bootstrap - CSS Framework - MIT License
• POPPER JS - POPPER JS - MIT License
• jQuery - Javascript librariy for DOM handling - MIT License
• Adafruit Unified Sensor Driver - A unified sensor abstraction layer. - Apache License 2.0 License
• Adafruit DHT sensor library - An Arduino library for the DHT series of low-cost temperature/humidity sensors. - MIT License
• arduino-sht - An Arduino library for reading the SHT3x family of temperature and humidity sensors. - BSD-3-Clause License
• TFT_eSPI - Arduino and PlatformIO IDE compatible TFT library optimised for the Raspberry Pi Pico (RP2040), STM32, ESP8266 and ESP32 that supports different driver chips - Mixed licenses: MIT, BSD, FreeBSD
• arduinoFFT - Fast Fourier Transform for Arduino. - GPL 3.0 License

FAQ

Where to change panel topology of the LED matrix?

First adapt in ./lib/HalLedMatrix/Board.h the width and height according your LED matrix.

In the ./lib/HalLedMatrix/LedMatrix.h file you have to change the member variable m_topo according to your physical panel topology. Take a look how your pixels are wired on the pcb and use the following page to choose the right one: https://github.com/Makuna/NeoPixelBus/wiki/Layout-objects

How to change text properties?

Text properties can be changed using different keywords added to the string to be displayed.
In order to be able to use these keywords, they must be prefixed by a backslash, otherwise they will only be treated as text.

The following keywords are available:

Keyword	Description
\#RRGGBB	Change text color (RRGGBB in hex)
\lalign	Alignment left
\ralign	Alignment right
\calign	Alignment center

Note

• If theses keywords are used within the sourcecode they have to be prefixed with two backslashes (one additional for escaping).
• If these keywords are used via the REST API all unsafe ASCII characters must be replaced by the respective percent encoding (see also ASCII Encoding Reference).
• The keywords can be combined.

Examples

Sourcecode	URL	Result
\\lalign\\#ff0000Hi!	%5Clalign%23ff0000Hi!	IHi!        I
\\calign\#ff0000Hi!	%5Ccalign%23ff0000Hi!	I    Hi!    I
\\ralign\#ff0000Hi!	%5Cralign%23ff0000Hi!	I        Hi!I

The display only shows a error code, like "E4". What does that mean?

This is a low level error code. Please have a look into the following table.

Error code	Description
E1	Something happended, which can not be further explained, but was fatal.
E2	There is a problem with the two-wire (i2c) interface.
E3	There is no user button available.
E4	Bad filesystem, did you explicit program the filesystem too? If not, please upload it.
E5	The display manager didn't start up.
E6	The system message handler didn't start up.
E7	The update manager didn't start up.

How can I use animated icons?

Upload first the bitmap texture image (.bmp) and afterwards the sprite sheet file (.sprite). See the details here.

How do I know that my sensor is recognized?

1. Check the log output from USB (not via web interface) right after startup (at this point WiFi is not connected yet).
2. Install the SensorPlugin and open the SensorPlugin website. There the sensor should be shown in the drop-down.

Why do I see sometimes values from the LDR in the SensorPlugin, although no LDR is installed?

The LDR pin is configured as input (ADC) and it seems that the pin is foating, because there is the ext. pull-down missing.

How can I use alternative icons?

Find details here.

Issues, Ideas And Bugs

If you have further ideas or you found some bugs, great! Create a issue or if you are able and willing to fix it by yourself, clone the repository and create a pull request.

License

The whole source code is published under the MIT license. Consider the different licenses of the used third party libraries too!

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions.