FAQ¶

Short answers to the first questions new users ask. Each answer links to the page with the details. For problems and error messages, see Troubleshooting.

What is AWTRIX NG?¶

Firmware for LED matrix clocks built on an ESP32-S3 board with an LED display. It shows the time, your own apps, notifications, effects and sounds. You control it from the web UI, Home Assistant, or over HTTP and MQTT. Start on the Home page.

Which hardware does it run on?¶

This documentation covers ESP32-S3 boards with a WS2812 display. Pins and display size are configurable within the display limits. See GPIO & boards.

AWTRIX NG runs on other clocks too. Each has its own documentation: Choose your clock.

How do I install it?¶

Follow Install AWTRIX NG. You can install from your browser or with esptool.

How do I connect it to my Wi-Fi?¶

Without Wi-Fi details, the clock opens its own setup hotspot with no password, named like awtrixng-a1b2c3. Join it with your phone and the setup page opens. See Connect to Wi-Fi.

How do I find its address?¶

The clock shows its IP address on the display each time it starts. You can also try http://awtrixng-xxxxxx.local, where xxxxxx is the last 6 characters of its MAC address, or look in your router's device list. See Find your clock.

How do I send my first message?¶

Send a notification from a terminal:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{"text":"hello","textColor":"#00FF00"}'

What the notification shows on the display

The display shows HELLO in green, then the rotation goes on. Always include the Content-Type: application/json header. Without it, curl -d marks the body as a form, and AWTRIX refuses a PUT or PATCH with that (Content-Type). See Your first notification.

What is the difference between a notification and a pushed app?¶

A notification is a one-time message: it appears and disappears. A pushed app stays in the app rotation until you delete it, and you update it whenever your value changes.

Can I write my own apps?¶

Yes. Write a small app in Berry and paste it into the script editor in the web UI. Start with the Scripting guide and Tutorial 1: Draw something. Ready-made apps are on the AWTRIX Hub.

How do I change the brightness?¶

In the web UI, or with PATCH /api/v1/settings and brightness (0–255). If automatic brightness is on, the clock follows its light sensor instead. See Brightness & sensors.

How do I connect it to Home Assistant or MQTT?¶

Turn on MQTT, enter your broker's address and restart the clock. With Home Assistant discovery on, the clock appears in Home Assistant by itself. See the Home Assistant and MQTT guides.

Does it need a username and password?¶

No, login is off until you turn it on. Once on, it protects the web UI and the whole API. See Authentication.

My tool cannot send `PATCH`, `PUT` or `DELETE`¶

Send a POST and put the real method in the X-HTTP-Method-Override header. This helps with tools like the FRITZ!Box HTTP action. See Method override.

How do I update the firmware?¶

In the web UI, without a cable. See Updating firmware.

How do I check the firmware version?¶

The web UI shows it. From a terminal:

curl http://<awtrix-ip>/api/v1/version

I used AWTRIX 3 before. What changes?¶

See Coming from AWTRIX 3.

Something does not work¶

See Troubleshooting, or ask on Discord.