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 the Ulanzi TC002 LED matrix clock. 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 the Ulanzi TC002 with its fixed 52×16 display, knob and speaker. See download availability.

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

How do I install it?¶

Follow Install AWTRIX NG. The installer can also work without internet (offline installation) or without a desktop (terminal installation).

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.

You can also enter your Wi-Fi in the installer.

How do I find its address?¶

The clock shows its IP address on the display each time it starts. The Status app shows it at any time. 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). 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, and so does the display at startup. From a terminal:

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

Something does not work¶

See Troubleshooting, or ask on Discord.