PIXELIX

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

Motivation
Introduction
Features
Original Setup
Attention
Supported Development Boards
- Recommendation
- Special Variants
Installation
Very First Startup
User Interface
Details
FAQ
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. It can be used to display text and animations.

Features

Supports 32x8 LED matrix size out of the box. Its possible to cascade another matrix to have a longer display.
Can display static or scrolling text, as well as static or animated icons.
Includes a web interface for configuring and controlling the LED matrix.
Supports REST API and MQTT for remote control and integration with other systems, like Home Assistant.
Can be extended with custom effects and animations. See list of plugins.

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


	...

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

⚠️ 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.

Supported Development Boards

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.

Recommendation

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.

Special Variants

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:

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 web interface.

Setup the toolchain.
Build the software and check whether the toolchain works.
Upload/Update the software and firmware to the target.
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 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

Very First Startup

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:

Using the browser and set them in the captive portal.
Using a terminal connecting via usb.

Variant 1: Configure wifi station SSID and passphrase with the browser

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.

SSID: pixelix-<DEVICE-ID>
Passphrase: Luke, I am your father.

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:

User: luke
Password: skywalker

Variant 2: Configure wifi station SSID and passphrase with the terminal

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:

Test: ping
Write wifi passphrase: write wifi passphrase <your-passphrase>
Write wifi SSID: write wifi ssid <your-ssid>
Restart PIXELIX: reset
Get IP-address: get ip

PIXELIX Is Ready

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.

User Interface

Pixelix can be controlled with buttons. Most of the development boards are supported with just one user button.
- One button control:
  - 1 short pulse: Activates the next slot.
  - 2 short pulses: Activates the previous slot.
  - 3 short pulses: Activates next fade effect.
  - 4 short pulses: IP address is shown.
  - 5 short pulses: Toggle display power on/off.
  - Long pressed: Increases the display brightness until maximum and then decreases until minimum. After that it will again increases it and so on.
- Two button control (LILYGO® T-Display ESP32-S3):
  - Left button:
    - 1 short pulses: Activates the previous slot.
    - 2 short pulses: Toggle display power on/off.
    - Long pressed: Decreases the display brightness until minimum.
  - Right button
    - 1 short pulse: Activates the next slot.
    - 2 short pulses: Activates next fade effect.
    - 3 short pulses: IP address is shown.
    - Long pressed: Increases the display brightness until maximum.
- Three button control (Ulanzi TC001):
  - Left button:
    - 1 short pulses: Activates the previous slot.
    - Long pressed: Decreases the display brightness until minimum.
  - Ok button:
    - 1 short pulses: Activates next fade effect.
    - 2 short pulses: IP address is shown.
    - Long pressed: Toggle display power on/off.
  - Right button
    - 1 short pulse: Activates the next slot.
    - Long pressed: Increases the display brightness until maximum.
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 possibility 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.

Details

For more detailed information, see the documentation.

FAQ

Where to change panel topology of the LED matrix?

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

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

How can I use animated icons?

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.

How do I know that my sensor is recognized?

Check the log output from USB (not via web interface) right after startup (at this point WiFi is not connected yet).
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 floating, because there is the ext. pull-down missing.

How can I use alternative icons?

Find details here.

Is it possible to use a font with 8px height?

There are three font types defined:

default (6px height)
normal (6px height)
large (8px height)

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.

How to configure the date/time format?

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 - Nov

You can colorize it by using the text properties.

How to configure my own list of plugins?

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:

configSmall.ini: Used for boards with 4 MB flash.
configNormal.ini: Used for boards with 8 MB flash or more.
configSmallNoI2s.ini: Used for boards with 4 MB flash and less mcu power.

Update the one you use for your needs by commenting in or out.

Is there an easy way to rotate the display by 180° ? I need to turn the display when putting it into a housing.

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

Used Libraries

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

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. For questions to the community or showing the own Pixelix, the Discord server can be used.

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.

peter 备注

显示方向

\config\display.ini 修改点阵屏显示方向，显示方向可以参考以下内容：

The layout objects are a collection of "feature" classes that define how items in a 2d grid are ordered.
TERMINOLOGY: A "feature" or "method" class is used to define features for a template class and are not meant to be used directly.

RowMajorLayout

The first item is in the upper left. Then the numbering within the layout moves through the row, then continues on the left of the next row.
There are three related objects with the same layout, but they are rotated 90, 180, and 270 degrees clockwise.
RowMajor90Layout -
RowMajor180Layout -
RowMajor270Layout -

no rotation           rotated 90            rotated 180           rotated 270
00  01  02  03        12  08  04  00        15  14  13  12        03  07  11  15
04  05  06  07        13  09  05  01        11  10  09  08        02  06  10  14
08  09  10  11        14  10  06  02        07  06  05  04        01  05  09  13
12  13  14  15        15  11  07  03        03  02  01  00        00  04  08  12

RowMajorAlternatingLayout

The first item is in the upper left. Then the number within the layout moves through the row, then continues on the right of the next row moving toward the left; repeating this alternating pattern through the layout.
There are three related objects with the same layout, but they are rotated 90, 180, and 270 degrees clockwise.
RowMajorAlternating90Layout -
RowMajorAlternating180Layout -
RowMajorAlternating270Layout -

no rotation           rotated 90            rotated 180           rotated 270
00  01  02  03        15  08  07  00        12  13  14  15        03  04  11  12
07  06  05  04        14  09  06  01        11  10  09  08        02  05  10  13
08  09  10  11        13  10  05  02        04  05  06  07        01  06  09  14
15  14  13  12        12  11  04  03        03  02  01  00        00  07  08  15

ColumnMajorLayout

The first item in in the upper left. Then the number within the layout moves down the column, then continues on the top of the next column moving downward again.
There are three related objects with the same layout, but they are rotated 90, 180, and 270 degrees clockwise.
ColumnMajor90Layout -
ColumnMajor180Layout -
ColumnMajor270Layout -

no rotation           rotated 90            rotated 180           rotated 270
00  04  08  12        03  02  01  00        15  11  07  03        12  13  14  15
01  05  09  13        07  06  05  04        14  10  06  02        08  09  10  11
02  06  10  14        11  10  09  08        13  09  05  01        04  05  06  07
03  07  11  15        15  14  13  12        12  08  04  00        00  01  02  03

ColumnMajorAlternatingLayout

The first item is in the upper left. Then the number within the layout moves down the column, then continues on the bottom of the next column moving toward the top; repeating this alternating pattern through the layout.
There are three related objects with the same layout, but they are rotated 90, 180, and 270 degrees clockwise.
ColumnMajorAlternating90Layout -
ColumnMajorAlternating180Layout -
ColumnMajorAlternating270Layout -

no rotation           rotated 90            rotated 180           rotated 270
00  07  08  15        03  02  01  00        12  11  04  03        15  14  13  12
01  06  09  14        04  05  06  07        13  10  05  02        08  09  10  11
02  05  10  13        11  10  09  08        14  09  06  01        07  06  05  04
03  04  11  12        12  13  14  15        15  08  07  00        00  01  02  03

插件种类选择

在\config\configSmall.ini文件中选择需要的插件

管脚定义

在config\board.ini中定义管脚

时间插件设置

在文件 \lib\DateTimePlugin\src\DateTimePlugin.cpp 中修改时间插件默认参数
北京时间的时区为CST-8

设置网络默认参数

在\lib\SettingsService\src\SettingsService.cpp 中设置默认网络参数，特别注意以下几项：

static const char* DEFAULT_NTP_SERVER = "ntp1.aliyun.com";
static const char* DEFAULT_WIFI_AP_PASSPHRASE = "12345678";
static const char* DEFAULT_WEB_LOGIN_USER = "admin";
static const char* DEFAULT_WEB_LOGIN_PASSWORD = "admin";
static const char* DEFAULT_NTP_SERVER = "pool.ntp.org";