This repository was archived by the owner on Oct 23, 2026. It is now read-only.

Repository navigation

Release list

AWTRIX NG TC002 v1.1.2-tc002.4 Latest

Latest

github-actions released this 02 Oct 14:40

v1.1.2-tc002.4

a2e8e6d

AWTRIX NG TC002 v1.1.2-tc002.4

What's new in v1.1.2-tc002.4

MP3s with album art play. Songs with large embedded cover art stopped with
MP3 decoding failed (#12).
Upload songs with their normal names. A file such as Alyssa Reid - High.mp3 was refused
with Device not reachable. It is now stored as Alyssa_Reid_-_High.mp3 (at most 32
characters). If that name is already taken by another song, it gets _2, _3 and so on
rather than replacing it.
The web UI stays responsive during an upload. It no longer shows Device not reachable
while a song is uploading.
Clear reasons when an upload is refused. Files the clock cannot play, such as 22 or 24 kHz
MPEG-2 audio (common for text-to-speech) or MP2, are refused with the reason and how to
re-encode them. A song that does not fit tells you how much space is free.
Scripts can call strict web APIs, such as Spotify's token endpoint
(#11). A script's own Content-Type
header was sent twice.

Tested on a TC002: every change in a RAM trial, and the release build in a full install. The
release validation protocol
(cold boots, the knob-hold and three-strikes fallbacks, restoring stock) has not been run on it
yet.

If the clock does not start

First hold the knob while powering on: that starts the stock Ulanzi app, from which the installer's
--restore puts the stock firmware back. If even that fails, Ulanzi's own USB recovery
reinstalls the stock firmware:

Prepare a 16 GB USB drive and format it as FAT32.
Place the upgrade files and zkautoupgrade in the root directory of the USB drive.
With the base unit powered via the pin connector, power on the device, then insert the USB
drive into the left-side USB-C port and wait for the device to restart and recover.
Once the device restarts and the "Ulanzi" logo appears, remove the USB drive. The device
should return to normal.

More recovery options: installation guide.

Install this version

The one-line installer takes the newest stable release unless told otherwise. To install
exactly this release on your clock:

curl -fsSL https://raw.githubusercontent.com/sanderdw/awtrix-ng-tc002/main/install.sh | sh -s -- --version v1.1.2-tc002.4 CLOCK_IP

What it checks and how to go back to stock: installation guide.

Try it from RAM first

Run this build for three minutes without flashing anything: download the
trial ZIP
(SHA-256)
and follow the trial guide,
which is also the ZIP's README.

Neither download contains vendor libraries, a device backup or a firmware image.

Build

Source: a2e8e6d134c363cf36e2fab9d10e71ce89790f67

Build and checks

Assets 7

AWTRIX NG TC002 v1.1.2-tc002.3 (experimental RAM trial)

github-actions released this 26 Sep 08:36

v1.1.2-tc002.3

080d617

AWTRIX NG TC002 v1.1.2-tc002.3

What's new in v1.1.2-tc002.3

Installs on more stock firmware (#8,
#6). Every stock version ships a
different Ulanzi application (libzkgui.so), and only the 1.1.1 build was recorded, so the
installer refused clocks on 1.0.1, 1.0.8 or 1.1.3. The launcher only calls four functions in
that application: the FlyThings app entry points and the SDK's base::wifiOnAndWait. The
installer and the update helper now read the application's ELF symbol table (it is never
loaded) and accept it when those four are there. The installer reports that as
compatible instead of verified. The audio and network libraries still need an exact
recorded build, because the port passes hand-measured structures to them.
--allow-unverified works. It now passes --force to the update helper, which it never
did, and it says which feature stays off (audio, or DHCP after the first lease, static
addressing and the fallback access point) instead of a blanket warning. A stock application
without the four entry points is refused even with the flag: without them, holding the knob or
three failed starts could not bring the stock app back.
--restore always works. It runs the helper with --force: the recovery image is the
clock's own stock partition. It was refused on every clock that had been force-installed.
Room for more scripts (#9). Berry
scripts share a 1 MiB heap instead of the ESP32's 96 KB, which refused the sixth average
script although the clock has 12 to 15 MB available. scriptHeapBudgetBytes in
/api/v1/device reports 1048576; past that, new installs are still refused.
The installer prints the full SHA-256 of anything it does not recognise, ready to paste into an
issue. /api/v1/tc002/vendor gains status (verified, compatible, unknown) and the vendor
application's requiredSymbols and missingSymbols. Its stock field is now reference:
it is the stock build the hashes were recorded from (1.1.1, MCU V1.0.17), not the clock's own
version.
tools/install.py runs from a repository checkout. It looked for vendor-fingerprints.json
next to itself, where only the installer ZIP has it.
The RAM-trial ZIP includes paths.py. try.py stopped with
No module named 'paths' in every trial ZIP since 1.1.1-tc002.1.

Installed an earlier release by running the helper with --force? Take this update with
the one-line installer once, not the web UI. The web UI update runs the helper that is already
on the clock, which still refuses your stock application.

Host tests cover both symbol readers, including 500 damaged files on which they must agree, and
install scripts until the 1 MiB budget refuses one. A reporter installed this build with the
one-line installer on a stock SoC 1.0.1 clock, without --allow-unverified: its application was
reported compatible, the budget read 1048576 with eight scripts installed, and scripts, icons and
settings survived. The
release validation protocol
has not been run on it, which is why it is a pre-release.

Install this version

The one-line installer takes the newest stable release unless told otherwise. To install
exactly this release on your clock:

curl -fsSL https://raw.githubusercontent.com/sanderdw/awtrix-ng-tc002/main/install.sh | sh -s -- --version v1.1.2-tc002.3 CLOCK_IP

What it checks and how to go back to stock: installation guide.

Try it from RAM first

Run this build for three minutes without flashing anything: download the
trial ZIP
(SHA-256)
and follow the trial guide,
which is also the ZIP's README.

Neither download contains vendor libraries, a device backup or a firmware image.

Build

Source: 080d61745df0f3e82bcc03495a5d4b50c0bb2513

Build and checks

Assets 7

AWTRIX NG TC002 v1.1.2-tc002.2 (experimental RAM trial) Pre-release

Pre-release

github-actions released this 25 Sep 15:05

v1.1.2-tc002.2

c2147fa

Experimental RAM trial v1.1.2-tc002.2

Try AWTRIX NG TC002 for three minutes without installing firmware. The trial
temporarily controls the display and buttons, then restarts the app already
installed on your clock. No compilation is needed.

This is an experimental build of v1.1.2-tc002.2. Automated tests do not
replace physical testing on every TC002 revision. Hardware validation so far
covers stock app 1.1.1 and MCU V1.0.17.

What's new in v1.1.2-tc002.2

Knob turns over MQTT (#4). Every
detent publishes cw or ccw to <prefix>/state/knob (not retained), also while block
buttons is on, so the knob can drive Home Assistant, for example a soundbar's volume. Turning
right is cw. With HA discovery on, the clock gains a Knob event entity. Every upstream
MQTT topic is unchanged; see the
README for an example
automation.
Buy me a coffee link for the port in the web UI and README. The upstream author's Ko-fi
button stays first.
The one-line installer now installs the newest stable release by default and takes
--version TAG for a specific one.

Run on the test clock against EMQX 6.3.1 and Home Assistant. The
release validation protocol
has not been run on this build, which is why it is a pre-release.

Install this version

The one-line installer takes the newest stable release unless told otherwise. To install
exactly this release on your clock:

curl -fsSL https://raw.githubusercontent.com/sanderdw/awtrix-ng-tc002/main/install.sh | sh -s -- --version v1.1.2-tc002.2 CLOCK_IP

What it checks and how to go back to stock: installation guide.

Download

The download contains the prebuilt ARM application, web UI, CA certificates,
trial runner and license notices. It contains no vendor runtime libraries,
personal device backup or firmware update image.

Quick start

Connect your TC002 to Wi-Fi using its stock app. Keep the clock on USB power
and use a computer on the same LAN.
Install Google Platform-Tools
(adb) and uv.
Put both on your PATH.
Download and extract the ZIP. Open a terminal in the extracted
awtrix-ng-tc002-trial folder containing try.py.
Replace the example IP below with your clock's IP, then run:

adb connect 192.168.100.190:5555
uv run --no-project try.py 192.168.100.190 --binary bin/awtrix-tc002 --seconds 180

Once the terminal prints Trial ready, open
http://192.168.100.190:18081 using your clock's IP. Leave the terminal open;
after three minutes the installed app restarts. Port 5555 must already be
reachable; if ADB cannot connect, stop here.

During the trial, avoid Wi-Fi changes, factory reset, maintenance/update and
reboot controls. These are real hardware controls; a firmware update would
leave the temporary trial path. Saving system configuration can restart the
application and its trial timer. Run only one trial at a time.

Returning to the installed app

Normally, wait for the trial to end. If its time has expired but the installed
app has not returned, and ADB still works:

adb -s 192.168.100.190:5555 shell setprop ctl.start zkswe

If Wi-Fi drops during this RAM trial, a power cycle boots the firmware already
installed in flash. This does not mean a firmware flash can be interrupted.

Full trial guide

Versioned releases

Each version gets a separate tag and release. GitHub Actions runs host regression
tests, builds the tagged ARM application and validates the archive before
publishing its downloads. Existing tags and release assets are preserved.
Each ZIP records its version, source commit and file checksums in manifest.json.
Choose a newer release to try a newer build. Your clock does not install updates
automatically.

Build

Source: c2147fa2c01f52e7a4c352a19c90a2c43a7b29e6

Build and checks

Assets 7

AWTRIX NG TC002 v1.1.2-tc002.1

github-actions released this 22 Sep 19:22

v1.1.2-tc002.1

b1bd3fb

AWTRIX NG TC002 v1.1.2-tc002.1

This is the stable release. The one-line installer installs it by default:

curl -fsSL https://raw.githubusercontent.com/sanderdw/awtrix-ng-tc002/main/install.sh | sh -s -- CLOCK_IP

Hardware validation so far covers stock app 1.1.1 and MCU V1.0.17. Newer builds are published as
pre-releases; install one by tag with --version, see the
installation guide.

You can also try it for three minutes without installing firmware, as below.

Download

Quick start

Connect your TC002 to Wi-Fi using its stock app. Keep the clock on USB power
and use a computer on the same LAN.
Install Google Platform-Tools
(adb) and uv.
Put both on your PATH.
Download and extract the ZIP. Open a terminal in the extracted
awtrix-ng-tc002-trial folder containing try.py.
Replace the example IP below with your clock's IP, then run:

adb connect 192.168.100.190:5555
uv run --no-project try.py 192.168.100.190 --binary bin/awtrix-tc002 --seconds 180

Returning to the installed app

Normally, wait for the trial to end. If its time has expired but the installed
app has not returned, and ADB still works:

adb -s 192.168.100.190:5555 shell setprop ctl.start zkswe

If Wi-Fi drops during this RAM trial, a power cycle boots the firmware already
installed in flash. This does not mean a firmware flash can be interrupted.

Full trial guide

Versioned releases

Build

Source: b1bd3fbc905a85790dd6771c972e4776338f4a95

Build and checks

Assets 7

AWTRIX NG TC002 v1.1.1-tc002.5 (experimental RAM trial) Pre-release

Pre-release

github-actions released this 16 Sep 20:11

v1.1.1-tc002.5

976e1b9

Experimental RAM trial v1.1.1-tc002.5

This is an experimental build of v1.1.1-tc002.5. Automated tests do not
replace physical testing on every TC002 revision. Hardware validation so far
covers stock app 1.1.1 and MCU V1.0.17.

Download

Quick start

Connect your TC002 to Wi-Fi using its stock app. Keep the clock on USB power
and use a computer on the same LAN.
Install Google Platform-Tools
(adb) and uv.
Put both on your PATH.
Download and extract the ZIP. Open a terminal in the extracted
awtrix-ng-tc002-trial folder containing try.py.
Replace the example IP below with your clock's IP, then run:

adb connect 192.168.100.190:5555
uv run --no-project try.py 192.168.100.190 --binary bin/awtrix-tc002 --seconds 180

Returning to the installed app

Normally, wait for the trial to end. If its time has expired but the installed
app has not returned, and ADB still works:

adb -s 192.168.100.190:5555 shell setprop ctl.start zkswe

If Wi-Fi drops during this RAM trial, a power cycle boots the firmware already
installed in flash. This does not mean a firmware flash can be interrupted.

Full trial guide

Versioned releases

Build

Source: 976e1b992e7ebc2c0f331f9a9837926783d7cc09

Build and checks

Assets 7

AWTRIX NG TC002 v1.1.1-tc002.4 (experimental RAM trial) Pre-release

Pre-release

github-actions released this 16 Sep 19:57

v1.1.1-tc002.4

b6413a7

Experimental RAM trial v1.1.1-tc002.4

This is an experimental build of v1.1.1-tc002.4. Automated tests do not
replace physical testing on every TC002 revision. Hardware validation so far
covers stock app 1.1.1 and MCU V1.0.17.

Download

Quick start

Connect your TC002 to Wi-Fi using its stock app. Keep the clock on USB power
and use a computer on the same LAN.
Install Google Platform-Tools
(adb) and uv.
Put both on your PATH.
Download and extract the ZIP. Open a terminal in the extracted
awtrix-ng-tc002-trial folder containing try.py.
Replace the example IP below with your clock's IP, then run:

adb connect 192.168.100.190:5555
uv run --no-project try.py 192.168.100.190 --binary bin/awtrix-tc002 --seconds 180

Returning to the installed app

Normally, wait for the trial to end. If its time has expired but the installed
app has not returned, and ADB still works:

adb -s 192.168.100.190:5555 shell setprop ctl.start zkswe

If Wi-Fi drops during this RAM trial, a power cycle boots the firmware already
installed in flash. This does not mean a firmware flash can be interrupted.

Full trial guide

Versioned releases

Build

Source: b6413a7f05fda2b0c0305aebd8e6bea984d4d1f8

Build and checks

Assets 4

AWTRIX NG TC002 v1.1.1-tc002.1 (experimental RAM trial) Pre-release

Pre-release

github-actions released this 16 Sep 18:37

v1.1.1-tc002.1

9d6a667

Experimental RAM trial v1.1.1-tc002.1

This is an experimental build of v1.1.1-tc002.1. Automated tests do not
replace physical testing on every TC002 revision. Hardware validation so far
covers stock app 1.1.1 and MCU V1.0.17.

Download

Quick start

Connect your TC002 to Wi-Fi using its stock app. Keep the clock on USB power
and use a computer on the same LAN.
Install Google Platform-Tools
(adb) and uv.
Put both on your PATH.
Download and extract the ZIP. Open a terminal in the extracted
awtrix-ng-tc002-trial folder containing try.py.
Replace the example IP below with your clock's IP, then run:

adb connect 192.168.100.190:5555
uv run --no-project try.py 192.168.100.190 --binary bin/awtrix-tc002 --seconds 180

Returning to the installed app

Normally, wait for the trial to end. If its time has expired but the installed
app has not returned, and ADB still works:

adb -s 192.168.100.190:5555 shell setprop ctl.start zkswe

If Wi-Fi drops during this RAM trial, a power cycle boots the firmware already
installed in flash. This does not mean a firmware flash can be interrupted.

Full trial guide

Versioned releases

Build

Source: 9d6a6675bbb80fb6676ef419884e41678e39b5d5

Build and checks

Assets 4

AWTRIX NG TC002 v1.1.0-tc002.8 (experimental RAM trial) Pre-release

Pre-release

github-actions released this 16 Sep 18:36

v1.1.0-tc002.8

bb40ea3

Experimental RAM trial v1.1.0-tc002.8

This is an experimental build of v1.1.0-tc002.8. Automated tests do not
replace physical testing on every TC002 revision. Hardware validation so far
covers stock app 1.1.1 and MCU V1.0.17.

Download

Quick start

Connect your TC002 to Wi-Fi using its stock app. Keep the clock on USB power
and use a computer on the same LAN.
Install Google Platform-Tools
(adb) and uv.
Put both on your PATH.
Download and extract the ZIP. Open a terminal in the extracted
awtrix-ng-tc002-trial folder containing try.py.
Replace the example IP below with your clock's IP, then run:

adb connect 192.168.100.190:5555
uv run --no-project try.py 192.168.100.190 --binary bin/awtrix-tc002 --seconds 180

Returning to the installed app

Normally, wait for the trial to end. If its time has expired but the installed
app has not returned, and ADB still works:

adb -s 192.168.100.190:5555 shell setprop ctl.start zkswe

If Wi-Fi drops during this RAM trial, a power cycle boots the firmware already
installed in flash. This does not mean a firmware flash can be interrupted.

Full trial guide

Versioned releases

Build

Source: bb40ea340d19c75b6f7bb3e14dacc6296d4e1eaf

Build and checks

Assets 4

AWTRIX NG TC002 v1.1.0-tc002.7 (experimental RAM trial) Pre-release

Pre-release

github-actions released this 15 Sep 21:01

v1.1.0-tc002.7

b754d57

Experimental RAM trial v1.1.0-tc002.7

This is an experimental build of v1.1.0-tc002.7. Automated tests do not
replace physical testing on every TC002 revision. Hardware validation so far
covers stock app 1.1.1 and MCU V1.0.17.

Download

Quick start

Connect your TC002 to Wi-Fi using its stock app. Keep the clock on USB power
and use a computer on the same LAN.
Install Google Platform-Tools
(adb) and uv.
Put both on your PATH.
Download and extract the ZIP. Open a terminal in the extracted
awtrix-ng-tc002-trial folder containing try.py.
Replace the example IP below with your clock's IP, then run:

adb connect 192.168.100.190:5555
uv run --no-project try.py 192.168.100.190 --binary bin/awtrix-tc002 --seconds 180

Returning to the installed app

Normally, wait for the trial to end. If its time has expired but the installed
app has not returned, and ADB still works:

adb -s 192.168.100.190:5555 shell setprop ctl.start zkswe

If Wi-Fi drops during this RAM trial, a power cycle boots the firmware already
installed in flash. This does not mean a firmware flash can be interrupted.

Full trial guide

Versioned releases

Build

Source: b754d575b1532beec54069bc95a5aa3afb3cb37d

Build and checks

Assets 4

Experimental RAM trial (main) Pre-release

Pre-release

github-actions released this 15 Sep 14:15

experimental-trial

21c4011

Experimental RAM trial

This is an experimental rolling build of main. Automated tests do not
replace physical testing on every TC002 revision. Hardware validation so far
covers stock app 1.1.1 and MCU V1.0.17.

Download

Quick start

Connect your TC002 to Wi-Fi using its stock app. Keep the clock on USB power
and use a computer on the same LAN.
Install Google Platform-Tools
(adb) and uv.
Put both on your PATH.
Download and extract the ZIP. Open a terminal in the extracted
awtrix-ng-tc002-trial folder containing try.py.
Replace the example IP below with your clock's IP, then run:

adb connect 192.168.100.190:5555
uv run --no-project try.py 192.168.100.190 --binary bin/awtrix-tc002 --seconds 180

Returning to the installed app

Normally, wait for the trial to end. If its time has expired but the installed
app has not returned, and ADB still works:

adb -s 192.168.100.190:5555 shell setprop ctl.start zkswe

If Wi-Fi drops during this RAM trial, a power cycle boots the firmware already
installed in flash. This does not mean a firmware flash can be interrupted.

Full trial guide

Automatic updates

After a push to main, GitHub Actions runs host regression tests, builds the ARM
application and validates the archive before replacing these two downloads.
Failed builds leave the previous download available. A manual workflow run on
main can refresh it too. The experimental-trial tag moves to the published
source commit; each ZIP records its version, source commit and file checksums
in manifest.json. Download it again to test a newer build. Your clock does not
install updates automatically.

Build

Source: 21c4011c045b6b170e1ae7a2c4801f7451be8094

Build and checks

Assets 4

Releases: sanderdw/awtrix-ng-tc002

Release list