# Blueforcer/awtrix3: a discontinued ESP32 pixel clock firmware, and the rewrite that replaces it

> AWTRIX 3 is custom ESP32 firmware for the Ulanzi TC001 pixel clock, the older AWTRIX 2 mainboard and self built matrices, and its own README states that development has ended and that a from scratch rewrite called AWTRIX NG is where the work has moved. What follows is what the archived firmware does, how its CustomApp model works, and what changes if you are holding a matrix you built yourself.

**Blueforcer/awtrix3** — ⚠️ Discontinued — superseded by AWTRIX NG (github.com/Blueforcer/awtrix-ng). Archived custom firmware for the Ulanzi Smart Pixel clock and self build matrix clocks.

- Repository: https://github.com/Blueforcer/awtrix3
- Website: https://blueforcer.github.io/awtrix3/
- Stars: 2,358 · Forks: 231
- Language: C++
- License: NOASSERTION
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/blueforcer-awtrix3

## The project's own notice: development ended, the rewrite is named

The first thing in this README is a notice, and it is unusually direct. AWTRIX 3 is no longer maintained. Development has ended. The repository stays online as an archive, the firmware keeps working on a device, and there will be no further releases and no new features. Issues and pull requests are no longer being worked on. The successor is named in the same block, AWTRIX NG, described as a complete rewrite from scratch where all development now happens, with its own documentation site, its own community link and a hub of ready made content. The dates around that statement are worth keeping separate. The repository is not archived in the technical sense, and the last push was on 2026-09-20, while the last release is 0.98 from 2025-01-05, preceded by 0.97 in December 2024 and 0.96 in March 2024. So the source tree has been touched long after the final binary was cut, which is what an archive that someone tidies looks like, and the firmware line itself stopped at a pre one version number twenty months ago. The licence is a custom file that the forge cannot classify, held at the top of the repository, and that is a second thing to read before you flash anything. The honest summary for an evaluator is that this is finished, publicly maintained software rather than abandoned code, which is a better position than it sounds: the code is readable, the documentation site is up, and the hardware support is what it always was.

## Three hardware targets, one microcontroller family, and a checked in flash layout

AWTRIX 3 is firmware written in C++ for a specific class of device, and the README is specific about which. It targets the Ulanzi Smart Pixel clock TC001, it can be used as an upgrade for the older AWTRIX 2 mainboard, and it can go onto a matrix clock you have built yourself. A note states that the firmware is only compatible with ESP32, which matters because the successor adds support for the S3 variant of the same chip family, so the hardware boundary moves with the firmware. The top-level files show how a project like this is built. There is a platformio configuration, which is the usual way ESP32 firmware is compiled and flashed, a source directory and a library directory, and a boards directory that suggests the build covers more than one board definition. There is also a partition table checked in as a CSV, and that file is worth noticing on its own, since the flash layout on these microcontrollers is fixed and a wrong partition arrangement is one of the more common reasons a firmware refuses to boot or refuses to accept an update. Content lives in the repository too, with directories of animated images and of backups, so the icons and animations that ship with the firmware are versioned with it rather than downloaded. Finally there are two files that only make sense together, a configuration file and a diagram description for the Wokwi simulator, which is a browser based ESP32 simulator. That combination means the firmware can be exercised without the hardware in front of you, which is the single most useful development fact in the file list.

## An App here is a page, not a program, and it holds no logic

The README spends a long, bolded paragraph on the word App, and it exists because the word is misleading. In AWTRIX an App is not something you install on the device. A CustomApp is a dynamic page that rotates in the display's app loop, it stores no logic and executes none, and it displays content pushed from an external system over MQTT or HTTP through the CustomApp API. All of the logic for deciding what should be on that page lives in your home automation. The flexibility that buys is real, since content can change at any moment. The cost is equally real and it is architectural rather than a bug. The device is a display with a protocol listener, so the freshness of what you see is entirely a property of the system pushing to it. If that system stops, the page does not report an error, it keeps showing what it last received, and the display gives you no way to distinguish a live value from a frozen one. The practical implication is that anything you put on a CustomApp which must be trustworthy needs its own staleness handling on the sending side, such as an explicit timestamp rendered into the page, because the firmware will not add one. The pre-installed apps are the built-in exception to all of this. Time, date, temperature, humidity and battery pages work the moment the device is powered on, with no external system at all, which is what makes the out of the box experience work and also what makes it easy to mistake for a fully local device.

## MQTT, HTTP, notifications, RTTTL, a file browser, and no cloud

The feature list is short and every entry is a capability rather than a slogan. There is Home Assistant discovery, so a device on the network announces itself. There is an onscreen menu, so settings can be changed on the device without a serial cable or a web interface. There is notification support, animated icons, fullscreen animations and effects, and a custom icon system where icons can be added without recompiling, which follows directly from the CustomApp model. There is an RTTTL melody player, which is the one-bit-per-note format a microcontroller can play without a decoder, and an integrated file browser on the device. The transport is described as a powerful MQTT and HTTP API, and those two protocols are the whole integration surface. Two entries are architectural statements rather than features and they are the ones to weigh. No cloud, and no telemetry: the device talks to what you tell it to talk to and reports nothing anywhere else, which is verifiable in the sense that there is no vendor service in the path. For a display that sits in your house showing your calendar and your doorbell, that is the correct default, and it is worth confirming it still holds in any configuration you add later, since a CustomApp is free to call anything. The out of the box pages are time, date, temperature and humidity, and the README is clear that custom apps and MQTT commands are the part that takes it further, so the sensible order is to run the device unchanged for a week before deciding what to push at it.

## The install path is a documentation site and an online flasher

The getting started section contains no commands. It says starting is easy as one two three, with the documentation, and links to it. That is the whole install procedure as far as the README is concerned, so anyone evaluating this needs the documentation site to answer basic questions, and this article cannot tell you the flash commands because they are not written down here. The feature list does name the method, an online flasher, and that is worth pausing on. Flashing through a browser means the firmware image travels from a web page to the device rather than from a file you downloaded and checked, which is convenient to the point of being the only realistic option for many people, and it moves a step of the supply chain somewhere you may not be able to audit. The repository publishes prebuilt release binaries rather than source-only builds, and the README documents no checksum file, no signature and no reproducible build procedure. For firmware that runs on a device in your home and can join your network and your MQTT broker, that is a reasonable thing to want and a reasonable thing to note. The mitigation available from the file list is the simulator configuration, which lets you run the firmware against a described virtual device before committing it to hardware, and the partition table in the repository, which tells you what the flash layout is expected to be. The paid companion app adds a third path to the firmware, through the stores, and it is discussed below because its status is the confusing part of this project rather than the technical one.

## What NG changes, and why a self built matrix is the case that moves

The successor notice lists what the rewrite adds, and reading it as a delta rather than as marketing tells you who should move. Three items are hardware. One image now covers both ESP32 and the S3 variant. Pin assignment, panel width and colour order become settings rather than constants, with panel width stated as a range from 32 to 128 pixels. For someone who bought a stock TC001 those are conveniences. For someone who built a matrix on their own board, panel width and colour order are the two things that determine whether the firmware will drive it at all, and in this firmware they are not settings. The next group is compute. The rewrite can run apps on the device as scripts edited in the browser, talking over HTTP, MQTT and Modbus TCP, and it has a full web interface on the device itself with a live preview and editors for scripts, icons and palettes, plus backup. That is the direct answer to the CustomApp limitation above, because logic that runs on the device is not logic you have to keep alive somewhere else. Audio is the third group, with MP3, DFPlayer tracks and internet radio added on top of the RTTTL melodies this firmware can already play. The rendering list is longer too, nineteen effects, twenty-two transitions, charts, drawing primitives and weather overlays. One conclusion matters more than the list. A complete rewrite from scratch is a new codebase with a new API, and the notice describes new capabilities rather than a migration path, so treat the transition as a port with nothing guaranteed to carry over, and test your existing CustomApp payloads against it before planning the work.

## A custom licence, a paid app for a finished firmware, and an affiliate link

Three commercial details sit in the README and they are worth reading carefully. The first is the app. There is a mobile app for AWTRIX with a live view of the device, settings customisation, icon management, an icon database exclusive to app users, and icon creation and sharing, offered through Google Play, the Apple App Store and Amazon. It is a paid purchase, and the README states plainly that buying it directly contributes to the development of AWTRIX 3. Since development has ended, that is a purchase against a firmware line that will not gain features, and anyone deciding whether to buy it should weigh that first. The second is the hardware link. The Ulanzi TC001 is linked with a referral parameter in the URL, so buying the clock through the README supports the project and buying it elsewhere does not, which is a fair arrangement and worth noticing. The third is the licence, a custom file at the top of the repository that GitHub cannot classify, so there is no standard identifier to check your policy against and the text itself is what governs. Alongside these sit the community and content resources: a Discord server, a flows site for sharing and discovering automations, and a documentation site that is still the place to learn this firmware. None of that changes the maintenance position, which is that a 0.98 release from January 2025 is what you install, the successor is a separate project, and the practical decision is whether your hardware needs anything this firmware cannot already do.

## Conclusion

AWTRIX 3 remains the right firmware if you own a TC001 or an AWTRIX 2 mainboard and your display is fed by MQTT or HTTP from a system that already exists, because the installed firmware does not stop working when development stops and the last release behaves as documented. Choose AWTRIX NG instead if your matrix is anything other than the stock panel, and the deciding item is panel width: the rewrite makes pin assignment, panel width from 32 to 128 pixels and colour order configuration settings, while this firmware targets ESP32 hardware and one layout. Do not plan a migration as an upgrade, since the successor is described as a complete rewrite from scratch and the notice lists new capabilities rather than a compatibility path, so existing CustomApp payloads and API calls are the thing to test first. Two practical checks close this out. Confirm where the firmware image comes from before flashing, since the documented path is an online flasher and the repository publishes prebuilt release binaries with no checksum or signing procedure described. And decide what you are depending on, since the licence is a custom file, the last release was 0.98 on 2025-01-05, and the mobile app offered alongside it is a paid purchase against a firmware line that has ended.

## FAQ

### Is AWTRIX 3 still maintained?

No, and the project says so itself. The README states that development has ended, that the repository stays online as an archive, that there will be no further releases or new features, and that issues and pull requests are no longer worked on. The last release is 0.98 from 2025-01-05, and the successor is AWTRIX NG.

### What is a CustomApp, and does it run any logic itself?

It is a dynamic page that rotates in the display's app loop, and it does not store or execute logic. It shows content pushed from an external system over MQTT or HTTP through the CustomApp API, so all of the logic for what appears on it has to live in that external system.

### Which hardware does AWTRIX 3 support?

The Ulanzi Smart Pixel clock TC001, the older AWTRIX 2 mainboard as an upgrade path, and self built matrix clocks. The README states the firmware is only compatible with ESP32, which is the boundary the successor moves by adding support for the S3 variant and making panel width and colour order configurable.

### How do I install the firmware?

The README contains no commands and sends you to the documentation site, describing the process as one two three. The feature list names the method as an online flasher, and the repository publishes prebuilt release binaries without a documented checksum or signature. A simulator configuration and a diagram file in the repository allow the firmware to be exercised before it is flashed to hardware.

### Can I move my existing AWTRIX 3 setup to AWTRIX NG?

There is no documented migration path. The successor is described as a complete rewrite from scratch, and the notice lists new capabilities rather than compatibility, so existing CustomApp payloads and API calls are the first thing to test. The rewrite does add on-device scripting, a web interface, Modbus TCP, wider panel support and audio beyond RTTTL.

## Sources

- [Blueforcer/awtrix3 on GitHub](https://github.com/Blueforcer/awtrix3)
- [Issues](https://github.com/Blueforcer/awtrix3/issues)
- [Project website](https://blueforcer.github.io/awtrix3/)
- [README](https://github.com/Blueforcer/awtrix3/blob/main/README.md)
- [Releases](https://github.com/Blueforcer/awtrix3/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/blueforcer-awtrix3