Skip to content

Updating firmware

This page shows how to install a newer AWTRIX NG version on a clock that already runs AWTRIX NG. Settings and uploaded files are kept. If you want a separate copy of them, create a backup first.

To install AWTRIX NG for the first time, see Install AWTRIX NG.

How it behaves

The web UI asks GitHub for the newest release and downloads it in your browser. The clock itself never contacts GitHub. The clock installs only a complete package for this clock that is newer than the installed version, and a refused package changes nothing. After the restart, the new version must keep running for one minute. Until then the clock refuses further uploads.

Update from the web UI

The easiest way:

  1. Open the web UI and go to System → Maintenance.
  2. Press Check for updates.
  3. If a newer release has a file for your clock, the button turns into Download & install. Press it, then press it again to confirm.
  4. Keep the page open and the clock powered until it restarts.

A newer version number alone does not mean the release has a file for this clock. Without one, the button stays at Check for updates.

Upload a file yourself

Which file to download

Download the file for your clock from the releases page:

Update file Maximum upload
awtrix-ng-tc002.awup 8 MiB

If a release has no awtrix-ng-tc002.awup, it has no update for this clock.

Upload a new image

Open System → Maintenance, press Choose file… next to Upload firmware and select the file. Wait for the progress display. After the clock restarts, reload the page if it does not reconnect by itself.

curl -X POST http://<awtrix-ip>/update -F "firmware=@awtrix-ng-tc002.awup"

Success is 200 {"ok":true,"applying":true}. The package is accepted for installation. Wait for the clock to restart, then check the running version.

Add -u myuser:mypass to the command when HTTP login is on. Use the same user name and password as for the web UI.

curl -F sends the file as a form upload. Name the form field firmware. The clock refuses any other field name.

Confirm which version is running

The web UI shows the running version. You can also ask for it:

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

The answer is {"version":"…"}. GET /version returns the version as plain text, and Device state includes it as version.

What to know about updates

  • If the new version fails to start three times, the clock shows USB RECOVERY. See Reset & recovery.
  • The clock keeps 1 MiB of storage free for settings and updates. A release can still need more free space.

Microphone controller updates

Some releases also update the clock's microphone controller. This happens by itself:

  1. The clock checks the installed controller version.
  2. For the first update, it downloads the original controller firmware from Ulanzi once, checks it and keeps it on the clock. Later updates use that copy.
  3. It installs the update. The clock may restart afterwards.

Keep the clock on USB power while this runs. If the download is not available, the clock works normally and tries again later.

Install an older version

The web UI installs only newer versions. If you need an older one, ask on Discord.

When an update fails

The answer names the reason. Settings, uploaded files and Wi-Fi are kept.

Error What to do
invalidPackage The file is damaged. Download an intact package again.
wrongTarget Select the awtrix-ng-tc002.awup package.
notNewer This clock already has that version or a newer one.
insufficientStorage The package is larger than the clock can hold. The answer names both sizes. Use the package from the releases page.
updateBusy Wait until the current upload, installation or confirmation has finished.
payloadTooLarge / insufficientMemory Check the package size and the free memory. The answer gives the details.

The size limits are in Which file to download. Exact status codes and answers are in Firmware upload.

Recovering a device that will not boot

See Reset & recovery.

Good to know

  • The USB installer does not update AWTRIX NG. It is only for clocks that still run the Ulanzi app. Use the web UI or the upload above.
  • Packages are not signed. Download them only from the releases page or another source you trust.
  • The clock refuses firmware uploads while its setup hotspot is active. Put the clock on your Wi-Fi first, as in Connect to Wi-Fi.

Details