Firmware for LED pixel clocks. Your clock, showing what matters to you.
Documentation · AWTRIX Hub · App · Release notes · Discord
AWTRIX NG turns an affordable LED pixel clock into a small display for your home. It shows the time and date, the readings of its sensors, and whatever your smart home has to say: the washing machine is done, someone is at the door, the train is late. Apps you write run on the clock itself, so it keeps working without a server in the background.
It is the successor to AWTRIX 3, rewritten from scratch. It runs on the Ulanzi TC001, the Ulanzi TC002 and clocks you build yourself with an ESP32 or ESP32-S3. Every clock runs the same engine, with the same API, the same MQTT topics and the same scripts, so an automation written for one clock works on the others.
| ESP32 (Ulanzi TC001, AWTRIX 2, DIY) | ESP32-S3 (DIY) | Ulanzi TC002 | |
|---|---|---|---|
| Display | 8 rows, 32 to 128 wide | 8 rows, 32 to 128 wide | built-in 52 × 16 |
| Sound | buzzer melodies, DFPlayer tracks | plus MP3s and internet radio with PSRAM and an I²S amplifier | speaker with MP3s, radio, synthesizer and offline speech |
| Controls | three buttons | three buttons | buttons and a knob |
| Bluetooth | – | – | two gamepads, iPhone notifications |
| Home Assistant | MQTT discovery | MQTT discovery | plus Home Assistant Voice on the knob |
| Scripts | on the clock | on the clock, with more memory | plus Bluetooth LE, TCP, hashing, sign-in to services and layouts |
| Pictures | icons on the clock and from the Hub | icons on the clock and from the Hub | plus GIF, JPEG and PNG from any web address |
| Art-Net | yes | yes | – |
| Install | in the browser | in the browser | USB installer for Windows, macOS and Linux |
Shows what you send it. Home Assistant, Node-RED, n8n, a shell script or anything else that speaks HTTP or MQTT can send a notification that appears at once, or a pushed app that takes its turn in the rotation with the clock, the date and the rest.
Runs apps on the clock. Scripts are small programs in Berry, written and saved in the web UI. They fetch data from the internet, talk MQTT and Modbus, keep their state across restarts and have settings of their own. A script with an error shows a red frame, and everything else keeps running.
Looks good doing it. Colored and scrolling text, animated icons, charts and progress bars, 19 background effects, weather overlays, 22 transitions between apps, and palettes of your own.
Plays sound. Melodies on every clock, DFPlayer tracks, and on clocks with a speaker your own MP3s and internet radio. One mixer keeps radio, apps and alerts at the volume you set.
Fits into your smart home. Home Assistant finds the clock through MQTT discovery and gets its buttons, sensors, brightness and volume as entities. The buttons can also call webhooks.
Belongs to you. Everything is set up in the web UI on the clock: a live preview, editors for scripts, icons and palettes, backups and every setting. No cloud and no account.
And more. Hold the middle button for a menu with your games, tools and radio stations. Let one clock share its display with others. Ask an AI assistant to write a script for you with the prompt from the docs.
The TC002 gets everything above and makes the most of its hardware. Its speaker plays MP3s, internet radio and songs from a built-in synthesizer, and an offline voice reads notifications aloud. Hold the knob and it becomes a Home Assistant Voice satellite. Two Bluetooth gamepads turn it into a games console, your iPhone sends its notifications over Bluetooth, and album covers and other pictures come straight from the web. Pushed apps written for 32 × 8 clocks are drawn at double size, so your existing automations fill the larger display.
The USB installer sets it up without any cloud, and later updates come through the web UI. You can always go back to the Ulanzi firmware.
The AWTRIX Hub is the community gallery for AWTRIX: hundreds of scripts and automations for Home Assistant, Node-RED, n8n and more, and thousands of icons. Choose your clock at the top and the Hub shows only what runs on it. Send to AWTRIX puts a script on your clock together with everything it needs. The pixel studio draws icons and animations in the browser, and anything you make can be shared back.
The AWTRIX NG app for iPhone and Android finds the clocks in your Wi-Fi, shows them live and brings the Hub to your phone. It sends Android notifications and your photos to the clock, and on the TC002 your phone becomes a gamepad. It is a one-time purchase with no subscription, no ads and no account, and every purchase supports the development of AWTRIX NG. The iPhone app is in review at Apple and waits for its release.
- Install it. Flash a TC001 or a DIY ESP32 or ESP32-S3 clock from the browser. For the TC002, download the USB installer.
- Connect it to your Wi-Fi. Enter your network in the TC002 installer, or join the clock's setup hotspot. Wi-Fi setup walks you through it.
- Open the web UI. The clock shows its address after it starts. Its name is
awtrixng-followed by the last six characters of its MAC address, for examplehttp://awtrixng-a1b2c3.local. - Add something. Install a script from the AWTRIX Hub, send your first notification, or write an app of your own.
Coming from AWTRIX 3? AWTRIX NG has its own API, so integrations for AWTRIX 3 need an update. Migrating from AWTRIX 3 shows what changed and converts many of them for you.
Updating from AWTRIX NG 1.1.2? Read the breaking changes for ESP32 or ESP32-S3 first. Volumes, sound keys and some script calls changed.
Send a notification from any computer in your network:
curl -X POST http://<awtrix-ip>/api/v1/notifications \
-H "Content-Type: application/json" \
-d '{"text":"Hello world","textColor":"#FF0000"}'Hello world scrolls across the display in red.
Or paste this script into the Scripts tab of the web UI. It joins the rotation like any other app:
class Dashboard
var level, fx, ramp
def init()
self.level = 0
self.fx = {"speed": 0.3, "palette": "Ocean"}
self.ramp = [0x00FFAA, 0x0066FF]
end
def loop() # about once a second, even while hidden
self.level = (self.level + 7) % 101
end
def draw() # about 40 times a second while shown
effect("PlasmaCloud", self.fx)
progress(self.level, 0x00FF00, 0x101010)
ramp_text(1, 6, "NET", self.ramp)
end
end
return Dashboard()The scripting guide starts from zero, and the documentation covers every endpoint, setting and payload field.
pio run -e awtrix # build the ESP32 firmware
pio run -e awtrix -t upload # build and flash over USBThe developer guide covers the ESP32-S3 builds, the TC002 and the tests.
Issues and pull requests are welcome. Start with CONTRIBUTING.md. Reports from boards beyond the stock clocks help a lot, and so do scripts worth shipping as examples. Please report security problems as described in SECURITY.md, not in the issue tracker.
AWTRIX NG is free for noncommercial use. If you would like to support its development, get the AWTRIX NG app, or chip in through GitHub Sponsors, Ko-fi or PayPal. Thank you!
PolyForm Noncommercial 1.0.0 · © Stephan Mühl (Blueforcer)
Free to use, change and share for any noncommercial purpose: at home, in schools, in research, for charities and public safety. The source is available, but it is not OSI open source. Selling it or using it in a business needs a separate agreement. Third-party licenses are listed in THIRD-PARTY-NOTICES.md.