Full RGB LED matrix, based on an ESP32 and WS2812B LEDs.
MIT License
Full RGB LED matrix, based on an ESP32 and WS2812B LEDs.
My initial goal was to have a remote display that would show multiple kind of information and run reliably 24/7. Can be connected to the local network via WiFi and controlled via REST API or Websocket. PIXELIX was born! :-)
The PIXELIX firmware is for ESP32 boards that controls a RGB LED matrix. It can be used to display text and animations.
Please note, that not every feature might be available for all kind of development boards. E.g. for MQTT support you need a development board with 8 MB flash or more. See the config<variant>.ini
configuration files in ./config folder.
Some impressions | |
---|---|
... |
The original setup for development and the first release was:
The following shows the absolute minimal wiring setup e.g. for the ESP32 DevKitV1. It may differ depended on your development board.
⚠️ If you power the development board and the LED matrix via USB: Be very careful, because it may destroy your ESP32 board if the LED current is 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.
ℹ️ To avoid any damage on your hardware and by the way to your eyes ;-), PIXELIX starts up with a low brightness setting. Additional the max. current is limited by software.
In the meantime several other boards are supported as well. You can find them in the list of boards.
With the Ulanzi TC001 smart pixel clock you even don't need to assemble the electronic and mechanic together.
If you assemble your own Pixelix hardware, its recommended to use a development board with 8 MB flash or more. 4 MB flash modules are still supported, but the functionality is limited. Also recommended is to use a esp32 dual core variant, which provides more processing power.
Additional supported variants, which were original not in focus:
Although PIXELIX was designed to show information, that is pushed or pulled via REST API, the following sensors can be directly connected and evaluated:
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 web interface.
Note, that the LED panel topology and the display width/height can currently not be changed in the web interface. If its necessary, adapt first in ./config/display.ini
the CONFIG_LED_MATRIX_WIDTH and CONFIG_LED_MATRIX_HEIGHT according your LED matrix and change CONFIG_LED_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
If the device starts the very first time, the wifi station SSID and passphrase settings are empty. They can be configured in two possible ways:
Restart the device and keep the button pressed until it shows the SSID of the wifi access point, spawned by PIXELIX. Search for it with your mobile device and connect.
Depended on the type of device you are using for connecting to PIXELIX, you may get a notification that further information is necessary and automatically routed to the captive portal. In any other case enter the URL http://192.168.4.1 in the browser address field.
Use the following default credentials to get access to the PIXELIX web interface:
Connect PIXELIX with your PC via usb and start a terminal. Use the following commands to set the wifi SSID and passphrase of your home wifi network:
ping
write wifi passphrase <your-passphrase>
write wifi ssid <your-ssid>
reset
get ip
After configuration, restart again and voila, PIXELIX will be available in your wifi network.
For changing whats displayed, go to its web interface. Use the same credentials than for the captive portal in variant 1. In the "Display" page you can change it according to your needs.
Note, the websocket interface is currently only used as a service in the web interface.
For more detailed information, see the documentation.
Adapt in ./config/display.ini
the CONFIG_LED_MATRIX_WIDTH and CONFIG_LED_MATRIX_HEIGHT according your LED matrix and change CONFIG_LED_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
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
Examples
Sourcecode | URL | Result |
---|---|---|
\\lalign\\#ff0000Hi! | %5Clalign%23ff0000Hi! | IHi! I |
\\calign\#ff0000Hi! | %5Ccalign%23ff0000Hi! | I Hi! I |
\\ralign\#ff0000Hi! | %5Cralign%23ff0000Hi! | I Hi!I |
This is a low level error code. Please have a look into the following table.
Error code | Description |
---|---|
E1 | Something happened, 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. |
Upload first the bitmap texture image (.bmp) and afterwards the sprite sheet file (.sprite). See the details here. The order is important, because if a bitmap is uploaded, it is assumed that an existing spritesheet is obsolete and will be removed.
The LDR pin is configured as input (ADC) and it seems that the pin is floating, because there is the ext. pull-down missing.
Find details here.
There are three font types defined:
Note, the default font type is "normal".
The font type can be selected per plugin instance in the settings web page.
Example:
{
"name": "JustTextPlugin",
"uid": 32690,
"alias": "",
"fontType": "large"
}
Not all plugin may support this in case they get conflicts with their layout. If a plugin don't support it, it will use the default font type.
The date/time format used by plugins, e.g. the DateTimePlugin or the SunrisePlugin, can be configured in their configuration JSON file. Use the file editor in the web interface to modify it according to your needs. The file can be found in the /configuration
folder and the filename is <PLUGIN-UID>.json
. The format specifiers following strftime().
Examples:
%I:%M %p
: 02:30 PM%H:%M
: 14:30%m/%d
: 11/12%d.%m.
: 11.12.%d - %b
: 11 - NovYou can colorize it by using the text properties.
The list of plugins which are available depend on the development board you use. Because board with only 4 MB flash don't have enough capacity for all. Or in case of a ESP-S2 (single core) not enough power.
To handle there are several .ini files in the ./config
folder:
Update the one you use for your needs by commenting in or out.
Change option CONFIG_DISPLAY_ROTATE180 in config/display.ini
to 1 as shown below and rebuild.
Example:
[display:common]
build_flags =
-D CONFIG_DISPLAY_ROTATE180=1
Library | Description | License |
---|---|---|
Arduino | ESP32 Arduino framework | Apache-2.0 |
NeoPixelBus | Controlling the LED matrix with hardware support (I2S) | LGPL-3.0 |
ESPAsyncWebServer | Webserver | LGPL-2.1 |
AsyncTCPSock | TCP library, Reimplementation of the API of me-no-dev/AsyncTCP using high-level BSD sockets | MIT |
ArduinoJson | JSON handling | MIT |
StreamUtils | Stream utilities | MIT |
Bootstrap | CSS Framework | MIT |
POPPER JS | POPPER JS | MIT |
jQuery | Javascript librariy for DOM handling | MIT |
Adafruit Unified Sensor Driver | A unified sensor abstraction layer. | Apache License 2.0 |
Adafruit DHT sensor library | An Arduino library for the DHT series of low-cost temperature/humidity sensors. | MIT |
arduino-sht | An Arduino library for reading the SHT3x family of temperature and humidity sensors. | BSD-3-Clause |
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 |
mufonts | A collection of fonts compatible with Adafruit GFX library. These fonts were developed when creating various samples for mupplet display code. | MIT |
JSZip | A library for creating, reading and editing .zip files with JavaScript, with a lovely and simple API. | MIT |
JSZipUtils | A collection of cross-browser utilities to go along with JSZip. | MIT |
FileSaver.js | FileSaver.js is the solution to saving files on the client-side. | MIT |
Arduino client for MQTT | This library provides a client for doing simple publish/subscribe messaging with a server that supports MQTT. | MIT |
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. For questions to the community or showing the own Pixelix, the Discord server can be used.
The whole source code is published under the MIT license. Consider the different licenses of the used third party libraries too!
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.