Skip to content

Install AWTRIX NG

This page puts AWTRIX NG on a Ulanzi TC001, an AWTRIX 2 or an ESP32 DIY board over USB.

What you need
The board A classic ESP32 with 4, 8 or 16 MB of flash. The Ulanzi TC001 and the common 32×8 clocks have 4 MB.
A USB data cable A charge-only cable does not show up as a serial port.
A browser Chrome, Edge or Opera on a desktop computer. Other browsers need esptool instead (pip install esptool).

Install from your browser

  1. Connect the clock to your computer with the USB cable.
  2. Press Fresh install for a board that does not run AWTRIX NG yet, or Update AWTRIX NG for one that does.
  3. Choose your board's port when the browser asks.
  4. Wait until the flasher says Done.

The flasher detects the chip and the flash size, and writes the newest release for your board.

Fresh install is for a board that does not run AWTRIX NG yet. It clears settings, Wi-Fi credentials, icons, melodies, palettes and scripts. The clock then opens its own setup hotspot: continue at Connect to Wi-Fi.

Update AWTRIX NG is for a board that already runs it. Everything on it stays, and it comes back on your Wi-Fi with the new version. You can also update without a cable in the web UI.

Keep a copy of the original firmware

Installing overwrites the firmware your clock came with. If you may want it back later, make a backup first.

Set your wiring

A fresh install uses the pin map of the Ulanzi TC001, the default of the common 32×8 clocks. If you have one of those, there is nothing to do. Continue at Connect to Wi-Fi.

An AWTRIX 2 or a DIY board with other wiring needs its pin map set once:

  1. Open the web UI and go to System → GPIO.
  2. Enter the whole pin map at once. Changing one pin on its own is usually rejected because it collides with another pin.
  3. Save and restart the clock. The new map takes effect after the restart.

Presets for common boards, the pins each field accepts, and how to undo a bad map are in GPIO & boards.

Install with esptool

Use this method if your browser has no Web Serial support or the browser flasher refuses your board. esptool is a command-line tool: install it with pip install esptool.

Command names in esptool 5

The commands below use read_flash, write_flash, erase_flash and flash_id. esptool 5 also accepts read-flash, write-flash and so on, and prints a warning for the underscore form.

In all commands, --port is COM5 on Windows, /dev/ttyUSB0 on Linux and /dev/cu.usbserial-* on macOS. Use your own port.

Back up the original firmware

Make the backup before you install AWTRIX NG. This needs esptool, even if you install from the browser.

python -m esptool --chip esp32 --port COM5 --baud 921600 read_flash 0x0 0x400000 tc001-stock-4mb.bin
  • It takes about a minute. If it stops or fails, try again with --baud 115200.
  • The file must be exactly 4,194,304 bytes. A smaller file is a failed read, not a backup.
  • This is for a 4 MB board such as the TC001. For 8 MB read 0x800000 bytes, for 16 MB 0x1000000.

To restore it later, write the same file to offset 0:

python -m esptool --chip esp32 --port COM5 --baud 460800 write_flash 0x0 tc001-stock-4mb.bin

This restores the original firmware and everything stored on it, Wi-Fi credentials included.

Pick your image

Download usb-awtrix-ng.zip from the releases page and unpack it. It holds one image per board and flash size:

File For
usb-awtrix-ng-4mb.bin 4 MB ESP32 boards, including the Ulanzi TC001
usb-awtrix-ng-8mb.bin, usb-awtrix-ng-16mb.bin ESP32 boards with more flash

Take the image that matches your board's flash size. If you do not know the flash size, ask the chip:

python -m esptool --port COM5 flash_id

The firmware-awtrix-ng*.bin files on the same page are not for a USB install. They are for updating a clock that already runs AWTRIX NG.

Write the image

python -m esptool --chip esp32 --port COM5 --baud 460800 write_flash 0x0 usb-awtrix-ng-4mb.bin

When the write is done, esptool prints Hash of data verified. If it stops earlier, see When it goes wrong.

Do not use 921600 baud for writing

On a TC001 a write at 921600 baud stops partway. The chip is then half-written and does not start. Repeat the write with --baud 460800.

What happens to your data:

  • Settings and Wi-Fi credentials are erased. The clock opens its setup hotspot. Continue at Connect to Wi-Fi.
  • Your files may or may not survive. Icons, melodies, palettes and scripts are stored in a separate area that the image does not overwrite. A different firmware may not find them there. Download anything you want to keep first in the web UI, or list the files with GET /api/v1/files and download each one from its /ICONS/, /MELODIES/ or /PALETTES/ path.

To start from a completely empty chip, erase it before you write:

python -m esptool --chip esp32 --port COM5 erase_flash

Watch it start

Open any serial monitor at 115200 baud. After a successful install you see a line like:

boot: AWTRIX NG 1.0.12 on ESP32

A freshly installed clock has no Wi-Fi credentials and opens its setup hotspot. See Connect to Wi-Fi. Once it is on your network, it shows its IP address on the display every time it starts.

When it goes wrong

Symptom What to check
No serial port found The USB cable may be charge-only, or the driver for your board's USB-to-serial chip is missing.
The write stops partway Lower the baud rate: --baud 115200 works where 460800 does not. The clock does not start until a write succeeds, so just repeat it.
A fatal error occurred: Failed to connect Hold the boot button while esptool connects. A TC001 does not need this. DIY boards often do.
Unable to verify flash chip connection, with a different reason each time Add --no-stub to the command. It is slower but works with more USB-to-serial chips. The browser flasher retries this way by itself.
It starts, but the display stays dark The LED data pin does not match your hardware, or the brightness is 0. See Set your wiring.
It starts, but the hardware behaves strangely Watch the serial log. If the saved pin map cannot be used on this chip, the log says so and the clock uses the default pins for its chip.