How blueforcer/awtrix3 works
1. Repository shape
- This repo is primarily an ESP32 firmware project for AWTRIX 3, a programmable LED matrix clock/display.
- It also contains host-side tooling: documentation, web-flasher assets, helper conversion scripts, and a separate AWL_Backup desktop utility.
2. Core runtime boundary
- The embedded application lives under src/ and is built with PlatformIO / Arduino-style C++ for ESP32.
- src/main.cpp is the entry point and wires together the major managers and services that run on the device.
3. Display/content pipeline
- The firmware’s central job is to turn a stream of content into pixels on the matrix.
- Apps, Dictionary, DisplayManager, MatrixDisplayUi, Overlays, effects, and icons form the rendering/content layer.
- This layer handles built-in clock/status pages, custom app payloads, overlays, animated icons, and visual effects.
4. External input sources
- Content and commands can arrive through MQTT and HTTP APIs, which are the main integration points called out in the README.
- MQTTManager and ServerManager are the primary protocol gateways.
- The repo also includes ArtnetWifi, which suggests a networked light/control input path separate from the normal app feed.
5. Local web and file services
- lib/webserver and ServerManager indicate an embedded web UI plus file-management functionality on the device.
- The README explicitly mentions an integrated file browser and onscreen settings menu; these are separate from the external API path and give direct local control.
6. Device management and state
- Globals, Functions, PowerManager, PeripheryManager, and UpdateManager handle cross-cutting device behavior.
- These modules likely manage boot/runtime state, power behavior, attached hardware, and firmware update flows.
- cert.h indicates HTTPS/TLS-related support is embedded where needed.
7. User interaction and system UI
- MenuManager and timer support local interactions and scheduled behavior.
- The built-in UI is not just a display output; it is also a device settings surface for adjusting firmware behavior directly on the clock.
8. Built-in features beyond the clock
- Games/ contains interactive mini-games such as AwtrixSays and SlotMachine, coordinated by GameManager.
- MelodyPlayer/ provides RTTTL-style sound playback, and GifPlayer.h plus media/icon assets support richer visual content.
9. Hardware and integration libraries
- lib/home-assistant-integration is a full Arduino library for Home Assistant MQTT discovery and device modeling.
- Other bundled libraries support display/media and peripherals: TJpg_Decoder, DFMiniMp3, MeanFilterLib, MedianFilterLib, LightResistor, and webserver.
- These libraries are part of the firmware’s device-side dependency boundary, not separate services.
10. Host-side tooling and asset pipeline
- Helper_Scripts/ contains Go/Python utilities for image conversion, screenshots, and AWTRIX cloning workflows; these are build-time or content-prep tools, not firmware runtime code.
- docs/ is the public documentation site and also hosts online flasher bundles for different targets.
- AWL_Backup/ is a separate B4J desktop application packaged with a built executable, used for backup-related device management.
11. Deployment and target profile
- The firmware is explicitly ESP32-only and has board/configuration support for an ESP32-S3 target in boards/.
- The repository includes prebuilt binaries and web-flasher packages under docs/*_flasher/, showing that distribution is designed around both source builds and end-user flashing.
12. High-level architecture summary
- At a diagram level, the system is: external controllers/home automation systems → MQTT/HTTP/Artnet gateways → app/state managers → display/effects/rendering pipeline → ESP32 hardware peripherals and LED matrix.
- Local user control and maintenance run in parallel through the onscreen menu, web UI/file browser, and update/backup tooling.
Main entry points: main.cpp Main · DisplayManager.h Display · Apps.h Apps · index.html Docs site
Components 24
ESP32 firmware
Device-side runtime built for the AWTRIX display on ESP32.
- Main · Bootstraps the embedded application and wires the device managers.
src/main.cpp - Globals · Shared device state and cross-cutting configuration.
src/Globals.h - Functions · Common firmware routines used across subsystems.
src/Functions.h - MQTT · MQTT command and content ingress from external controllers.
src/MQTTManager.h - Server · Embedded HTTP server, file browser, and local web UI surface.
src/ServerManager.h - Artnet · Networked lighting/control input path separate from MQTT.
src/ArtnetWifi.h - Apps · Built-in app model and payload handling for display content.
src/Apps.h - Dictionary · Text, token, and content lookup support for rendering.
src/Dictionary.h - Display · Coordinates matrix output and visual composition.
src/DisplayManager.h - UI · On-device display UI and page navigation.
src/MatrixDisplayUi.h - Overlays · Status and temporary overlay graphics drawn over content.
src/Overlays.h - Effects · Visual effects used by the matrix display pipeline.
src/effects.h - Icons · Icon drawing and embedded visual assets.
src/icons.h - Menu · Onscreen settings menu and direct user interaction.
src/MenuManager.h - Power · Power behavior, brightness, and device lifecycle control.
src/PowerManager.h - Periphery · Attached hardware and peripheral management.
src/PeripheryManager.h - Update · Firmware update and maintenance workflow.
src/UpdateManager.h - Games · Mini-games and game coordination for the device.
src/Games/GameManager.h - Melody · RTTTL-style melody playback and note generation.
src/MelodyPlayer/melody_player.h
Bundled device libs
Embedded libraries and support modules shipped with the firmware.
- Webserver lib · Bundled filesystem web server implementation used by the device UI.
lib/webserver/esp-fs-webserver.h - HA MQTT · Home Assistant discovery and MQTT device modeling library.
lib/home-assistant-integration/src/HAMqtt.h
Host tooling
Desktop and build-time tools used for conversion, flashing, and backup.
- Helper scripts · Go and Python utilities for image conversion, cloning, and screenshots.
Helper_Scripts/Awtrix_Clone.go - AWL Backup · Separate desktop application for backup-related device management.
AWL_Backup/AWL-Backup.b4j
Docs and distribution
Documentation site and prebuilt flashing bundles.
- Docs site · Public documentation and web-flasher distribution site.
docs/index.html
Connections 23
- Main → Globals: init · Boot sequence initializes shared runtime state.
- Main → Functions: uses · Main runtime relies on shared helper routines.
- Main → MQTT: starts · Entry point wires the MQTT gateway.
- Main → Server: starts · Entry point wires the embedded web/file server.
- Main → Artnet: starts · Entry point enables Artnet input handling.
- Main → Apps: loads · Entry point registers content apps and runtime pages.
- Main → Display: starts · Entry point initializes the display pipeline.
- Main → Menu: starts · Entry point enables local menu control.
- Main → Power: starts · Entry point configures power management.
- Main → Periphery: starts · Entry point configures attached hardware.
- Main → Update: starts · Entry point enables update handling.
- Display → UI: drives · Display manager presents the matrix UI and pages.
- Display → Overlays: composes · Overlay layer is composited into rendered frames.
- Display → Effects: applies · Visual effects are applied during rendering.
- Display → Icons: uses · Icon assets feed the render pipeline.
- Apps → Dictionary: uses · App content relies on lookup and text mapping support.
- Apps → Games: includes · Game subsystem is exposed as part of built-in apps.
- Apps → Melody: uses · Apps can trigger sound playback.
- MQTT → HA MQTT: integrates · MQTT path supports Home Assistant discovery and device models.
- Server → Webserver lib: built on · Device web interface is powered by the bundled webserver library.
- Helper scripts → Docs site: feeds · Host utilities support content prep and documentation workflows.
- AWL Backup → Docs site: described by · Desktop backup utility is documented alongside flashing and maintenance.
- Update → Docs site: published in · Firmware update and flashing flows are distributed through docs.