PIXELIX <!-- omit in toc -->

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

Click on the preview to see the video.

---

Table of Content <!-- omit in toc -->

• Motivation
• Introduction
• Features
• Original Setup
• Attention
• Supported Development Boards
  • Recommendation
  • Special Variants
• Installation
• Very First Startup
  • Variant 1: Configure WiFi station SSID and passphrase using a browser
  • Variant 2: Configure WiFi station SSID and passphrase using a serial terminal
  • PIXELIX Is Ready
• User Interface
  • One button control
  • Two button control (LILYGO® T-Display ESP32-S3)
  • Three button control (Ulanzi TC001)
  • Remote button
• Details
• 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?
  • Is it possible to use a font with 8px height?
  • How to configure the date/time format?
  • How to configure my own list of plugins?
  • Is there an easy way to rotate the display by 180° ? I need to turn the display when putting it into a housing
• Used Libraries
• Issues, Ideas And Bugs
• License
• Contribution

Motivation

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!

Introduction

The PIXELIX firmware is for ESP32 boards that controls a RGB LED matrix or a TFT display. It can be used to display time, date, weather, text, animations and etc. It doesn't require any cloud connection, even its not required to have a smarthome system. But with its REST and MQTT API it fits perfect with Home Assistant or any other smarthome system.

Features

• Supports 32x8 LED matrix size out of the box. Its possible to cascade another matrix to have a longer display.
• Supports some small TFT displays to simulate a LED matrix in retro style.
• Display static or scrolling text, as well as static (BMP and GIF) or animated icons (GIF).
• Includes a web interface for configuration and control.
• Supports REST and MQTT API for remote control and integration with other systems, like Home Assistant.
• Extendable with custom effects and animations by plugins. See list of plugins.
• Its plugin concept allows to scale for different development boards.

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, except for the Ulanzi TC001. See the config<variant>.ini configuration files in ./config folder.

| Some impressions | | | -------------------------------------------------------------------------- | -------------------------------------------------------------- | | | | | | | | | ... |

Original Setup

The original setup for 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 e.g. for the ESP32 DevKitV1. It may differ depended on your development board.

Attention

:warning: 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.

:information_source: 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.

Supported Development Boards

In the meantime several other boards are supported as well. You can find them in the list of boards. If your board is not listed in the main branch, please have a look in the Development branch too.

With the Ulanzi TC001 smart pixel clock you even don't need to assemble the electronic and mechanic together.

Recommendation

If you assemble your own Pixelix hardware, its recommended to use a development board with the following properties:

• 8 MB flash or more. 4 MB flash modules are still supported, but the functionality is limited.
• A esp32 dual core variant, which provides more processing power.
• PSRAM for images as internal RAM isn't that much available depended on the configured features.

Special Variants

Additional supported variants, which were original not in focus:

• LILYGO® TTGO T-Display ESP32 WiFi and Bluetooth Module Development Board For Arduino 1.14 Inch LCD
• LILYGO® T-Display ESP32-S3 1.9 inch ST7789 LCD Display Touch Screen Development Board
• Limited HUB75 panel support, configured for the ESP32-DoIt DevKit v1 and the Adafruit MatrixPortal S3 development board.

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 Updater: https://github.com/BlueAndi/PixelixUpdater. You can accesss the Updater through the submenu "Update" of PIXELIX's 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.
4. Verify that the LED panel topology is correct and you see the "Hello World" on the display.

Note, that the LED panel topology and the display width/height can 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

Very First Startup

When the device starts for the very first time, the WiFi station SSID and passphrase settings are empty. The