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 writes the new firmware next to the running one and switches only after the whole image is checked, so a failed update leaves the clock as it was. Settings and uploaded files are stored apart from the firmware and stay.

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:

Board Update file Maximum upload
Octal PSRAM firmware-awtrix-ng-s3-octal.bin 1,769,472 bytes
Quad PSRAM firmware-awtrix-ng-s3-quad.bin 1,769,472 bytes

Choose the image by how the PSRAM is wired on your board. The memory size alone does not tell you. See Which of the two images.

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=@firmware-awtrix-ng-s3-octal.bin"

Success is 200 {"ok":true}. The image is written and checked, then the clock restarts into it.

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.

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.

When an update fails

An image for another chip or for the other PSRAM type is refused with 400 wrongChip.

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-*.bin files do not work for this upload. They are for the first installation over USB. Upload the firmware-awtrix-ng-s3-… file that matches your board.
  • 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