Install AWTRIX NG¶

This page shows how to install AWTRIX NG on a Ulanzi TC002 with the TC002 USB installer for Windows, macOS or Linux. You do not need to set up the Ulanzi app first.

Already running AWTRIX NG? Use Updating firmware instead.

What you need¶

• A Ulanzi TC002 running the Ulanzi app.
• A computer and a USB-C data cable. A charging-only cable does not work.
• An internet connection, unless you prepare the files for offline installation.
• A stable power supply for the whole installation.
• Your Wi-Fi name and password, if you want to enter them during installation.

Get the installer¶

Download the installer for your operating system and processor. On a computer without a desktop, use the terminal version. See Terminal installation.

Choose x64 (also called x86_64 or amd64) for an Intel or AMD computer, and ARM64 (aarch64) for an ARM computer. RPM packages, checksums and the installer's source code are on the latest release.

• Windows: the .exe is the whole app. Put it in any folder and start it. Nothing is installed. It uses Microsoft's WebView2 component, which Windows 11 and current Windows 10 already contain. If the window stays empty or does not open, install the WebView2 Runtime once.
• macOS: open the DMG and copy the app into Applications.
• Linux: install the package through your system's software installer, so its required libraries and the clock's USB permission rule are installed too. Reconnect the clock afterwards, and start the app from your signed-in desktop session. Check the package's platform notes before you install it.

The installer can download TC002 firmware from the latest stable GitHub release and check it. If that release has no TC002 package, choose a compatible firmware ZIP from a TC002 release. Without a compatible firmware ZIP, the installer stops before it connects to the clock.

The TC002 .awup file is for updates after AWTRIX NG is installed. Other firmware files do not work on this clock.

Install over USB¶

1. Open the installer. Close other clock installers, browser installation tabs and phone-management tools that use USB. Wait until the firmware is loaded and checked and Ready when you are. appears. If it shows Choose the firmware., press Choose firmware ZIP… and select usb-awtrix-ng-tc002.zip.
2. Connect and switch on the TC002. Connect only one clock with the data cable. If it is already on, switch it off and on once. The installer finds it and prepares the installation.
3. Add your Wi-Fi, if you like. Enter the network name and password under Home Wi-Fi. Leave both fields empty to set up Wi-Fi afterwards.
4. Press Install AWTRIX NG. The button appears when preparation is complete. Keep the clock powered, the USB cable connected and the installer open. After the check the clock restarts by itself, and the installer sends your Wi-Fi details as soon as it has started. This can take a minute.
5. Press Open your clock when it connects. If the clock cannot join your network, the installer says why: correct the details and press Try again, or use the setup hotspot. Without Wi-Fi details you can enter them afterwards and press Send Wi-Fi to the clock.

Installation removes the Ulanzi app's saved Wi-Fi and cloud login. Wi-Fi details you enter in the installer go only to the clock. They are not saved on your computer.

Terminal installation¶

The terminal version works without a graphical desktop. Extract the CLI archive for your operating system and processor.

On Linux, do the one-time USB setup first. Follow README-LINUX.md in the archive. It explains how to install the included 70-awtrix-tc002.rules in /etc/udev/rules.d and reload the USB rules. For SSH or a computer without a desktop session, also follow its plugdev group setup and sign out and back in. Reconnect the clock afterwards.

Open a terminal in the extracted folder and run:

.\awtrix-tc002-installer-cli.exe

./awtrix-tc002-installer-cli

The installer downloads anything else it needs by itself. You do not need to install Node.js, Python or ADB. Keep the computer online while it prepares, or prepare the files for offline installation.

Then follow the prompts:

1. Wait until the firmware is checked and you are asked to connect the clock. Connect one TC002 and switch it on. If it is already on, switch it off and on once.
2. Enter your Wi-Fi name and password when asked, or press Enter at the network-name prompt to skip them. The password is hidden while you type.
3. Type INSTALL to start. Keep the clock powered, the USB cable connected and the terminal open while progress is shown.
4. After Installation verified the clock restarts by itself. Keep the USB cable connected for the Wi-Fi setup. Then open the address shown in the terminal. If the clock cannot join your network, answer y to Try Wi-Fi again? and enter the details again, or use the setup hotspot.

If writing is interrupted, keep the same clock powered and the same terminal open. Reconnect the USB cable and press Enter at the recovery prompt to finish. Do not restart the clock until the check succeeds.

Offline installation¶

Prepare the installer and a TC002 installation firmware ZIP while you are still online:

1. Download the installer for your computer from Get the installer.
2. Open the latest release on GitHub. Under Assets, download usb-awtrix-ng-tc002.zip. This is the same file the installer downloads when it is online.

Leave the ZIP compressed.

Choose the ZIP yourself:

• In the graphical app, press Choose firmware ZIP… before you connect the clock and select the file. Canceling the dialog keeps the current choice.
• In the terminal version, start the installer with the file path:

.\awtrix-tc002-installer-cli.exe --firmware "C:\Downloads\usb-awtrix-ng-tc002.zip"

./awtrix-tc002-installer-cli --firmware "/path/to/usb-awtrix-ng-tc002.zip"

Or let the installer find it. Keep the exact name usb-awtrix-ng-tc002.zip and put the file here:

• Windows: in the same folder as the installer .exe or the terminal program.
• macOS graphical app: beside the .app, not inside it. If the app is in Applications, put the ZIP there too.
• macOS / Linux terminal: beside awtrix-tc002-installer-cli in the extracted folder.
• Linux graphical app: beside the installed program, not beside the installer package. Use Choose firmware ZIP… for a file in any other folder.

The installer uses the first of these it finds: the file you chose → a ZIP beside the program → the GitHub download. It shows Local firmware and checks the file before it connects to the clock. If a local file is missing, unreadable or invalid, installation stops. It never switches to another source. Fix or replace the file and press Retry firmware, choose another ZIP, or remove the file to use the GitHub download. To go back to the automatic choice, reopen the app or start the terminal command without --firmware.

Wi-Fi setup¶

If the installer already connected the clock to your Wi-Fi, skip this section.

1. Wait until the display shows AP MODE.
2. With your phone or computer, join the open Wi-Fi network shown on the display, usually awtrixng-xxxxxx.
3. Open http://192.168.4.1, enter your Wi-Fi name and password, and press Save.
4. The clock connects by itself. Switch your phone or computer back to your usual Wi-Fi.

The Connect to Wi-Fi page shows these steps in detail.

If you do not want to wait for the USB Wi-Fi setup, press Skip and set up Wi-Fi later in the graphical installer and use the hotspot. The terminal installer shows the hotspot steps if it cannot finish the Wi-Fi setup. You do not need to reinstall AWTRIX NG.

The hotspot also comes back when your router is not available. The clock keeps its saved Wi-Fi details during an outage. If you replace the router, use the hotspot to enter the new network.

Find the clock¶

After switching on, the clock shows its firmware version and address for a few seconds. Later, open the Status app to read the address, or use http://awtrixng-xxxxxx.local. A hostname you set replaces that name. See Find your clock.

Set your time zone under System → Time. A web login is optional. See Authentication.

What the clock has¶

• The clock has no light sensor, so brightness stays where you set it.
• After power-on it needs a network time server before it shows the correct time.
• It always uses HTTP port 80. webPort and artnet are accepted but have no effect.
• Timed sleep is not supported. Use display blanking to switch the display off while the clock stays reachable.
• One upload (an icon, an MP3, a backup) can be up to 2 MiB, an update package up to 8 MiB. The clock keeps 1 MiB of storage free for settings, the Wi-Fi setup and updates. See Limits.

Scripts, HTTP, MQTT and Home Assistant work as this documentation describes. You set everything up in the web UI.

Privacy¶

AWTRIX NG has no manufacturer cloud. The Ulanzi app does not run, its cloud login is removed, and Ulanzi's Bluetooth Wi-Fi setup is switched off. The clock contacts only:

• your router, for its address and name lookups;
• the time server: pool.ntp.org, unless you set another under System → Time;
• Ulanzi's download server, once, when a release brings a microphone-controller update and the original file is not on the clock yet;
• the radio stations you play;
• your MQTT broker and Home Assistant, when you set them up;
• the addresses your scripts call, and nearby Bluetooth devices when a script uses the Bluetooth LE interface.

Update checks and downloads run in your browser, from GitHub. The installer's USB access works only through the cable, never over Wi-Fi.

When the install goes wrong¶

The clock is not found¶

The clock accepts the installer connection only for a short time after switching on. Waiting for your TC002… means the installer is still trying.

1. Keep the installer open. If Try USB again is shown, press it. In the terminal version, answer y to the USB retry prompt.
2. Close other USB installers, browser installation tabs and phone-management or Android developer tools. They can keep the USB connection busy in the background.
3. Connect only one TC002 with a data cable, then switch the clock off and on once.
4. If it still does not connect, try another data cable and a USB port directly on the computer.

If USB access is denied, follow the error shown by the installer:

• Windows: check the TC002's USB interface in Device Manager. It needs a compatible WinUSB driver.
• Linux, graphical app: reconnect the clock after installing the package.
• Linux, terminal: complete the steps in README-LINUX.md, including signing out and back in after joining plugdev, then reconnect the clock.

Write down the exact error if you ask for help.

Use these restart steps only before installation starts. If installation was interrupted, keep the clock powered and follow the recovery message in the installer.

The firmware does not load¶

Press Retry firmware (terminal: answer y to the retry prompt). If you use a local ZIP, check the file and its location first. Retry reads the same file again. You can also press Choose firmware ZIP… to select another one. For the GitHub download, check the internet connection. If GitHub is limiting requests, wait a while before you retry.

No compatible TC002 firmware has been published yet means that no local ZIP was found and the latest stable release has no installation package for this clock. Reconnecting USB does not help. Wait for a release with a TC002 package, or use a TC002 firmware ZIP as described in offline installation. Other firmware files do not work.

Other messages¶

Related¶

• Reset & recovery - reset, start the Ulanzi app, remove AWTRIX NG
• Updating firmware - install newer versions
• Buttons, knob & clock - the knob, Status app and clock faces
• The web UI - what the built-in interface does
• Find your clock - names and browsing for devices
• Sound and Internet radio - the speaker
• Home Assistant Voice - talk to Assist with the knob
• Limits - every limit