HyperLED Wiki

For developers

HyperLED is open source (EUPL-1.2) and welcomes contributions. This page shows where things are. The detailed, always up-to-date technical documentation lives in the repository's docs/ folder.

The pieces

Piece	Where	What
Master firmware	HyperLED (this repository's root)	PlatformIO project for the ESP32-S3: LED engine, Wi-Fi, web server, MQTT, updates, plugins.
Web interface	`data/` in the same repository	Plain HTML, CSS and JavaScript. No build step; it is written to the board with `pio run -t uploadfs`.
Slave firmware	HyperLED-Slave	A separate repository and PlatformIO project for Slave boards.
Plugins	`plugins/` and, for example, Klipper Status Display	Small JSON files, optionally with a Lua script.

Build and flash

pio run                 # build (default environment: esp32-s3)
pio run -t upload       # build and flash the firmware
pio run -t uploadfs     # build and flash the web interface (data/)
pio device monitor      # serial monitor, 115200 baud

Hardware: the Waveshare ESP32-S3-Zero (ESP32-S3FH4R2, 4 MB flash and 2 MB PSRAM) for both Master and Slave. The partition table has two update slots and a small file system; see partitions.csv.

There is no unit test suite; changes are checked on real hardware by watching the serial output and the web interface.

How the firmware is organised

src/main.cpp starts a fixed set of singleton "managers", each with begin() and loop(), in this order:

LEDManager → WiFiManager → WebServerManager → MqttManager → UpdateManager → SlaveManager → ButtonManager

LEDManager: LED drivers, segments, the effect engine, matrix mapping and the brightness limiter.
WiFiManager: station connection with a captive-portal access point as fallback.
WebServerManager: the web server and the /api/ routes.
MqttManager: MQTT and Home Assistant discovery.
UpdateManager: online updates of firmware and web interface.
SlaveManager: finds Slaves and sends them their configuration and data over HyperBus.
ButtonManager: the two physical inputs.
PluginManager (with the plugin parser, expression language and Lua host): the plugin system.

HyperBus

The Master/Slave protocol: frames with a start byte, header, payload and CRC16, over a UART link or ESP-NOW. The header HyperBus.h exists in both repositories and must be kept identical. Description: Master/Slave architecture.

HTTP API

Everything the web interface does goes through a JSON API, which you can use from scripts: state, segments, presets, panels and widgets, Slaves, plugins, network, updates, MQTT and backup. Full list: API reference.

A taste:

curl http://hyperled.local/api/state                                  # state of all segments
curl -X POST http://hyperled.local/api/state \
     -H "Content-Type: application/json" -d '{"on": "t"}'             # toggle everything
curl http://hyperled.local/api/log                                    # the last minute of the log

Plugins and scripts

Using plugins
Developing plugins: file format, settings, values and rules, and the expression language
Plugin scripts: Lua scripts that draw a segment pixel by pixel, on the Master or on a Slave

A plugin is checked on the controller completely before it is installed (POST /api/plugins/preview checks it without saving anything).

Contributing

Report bugs and ideas as issues.
Source files carry the EUPL header; keep it in new files.
Changes to the wire protocol must go into both repositories.
The web interface texts live in data/i18n.js in German, English and Russian.
Keep the documentation in docs/ in step with changes to the API or networking code.

← PreviousTroubleshooting

The wiki on GitHub