AWTRIX NG 1.2.2¶

Release of 2026-10-06. Everything that changed since 1.1.2.

New¶

• Device menu: hold the middle button for half a second. It lists scripts you start on demand and your stations. See The menu.
• Scripts on demand: a script with # @ondemand stays out of the rotation. It starts from the device menu or the Apps tab and has the display to itself. Holding the middle button ends it. See Start from the device menu.
• Mirroring: one clock shares its display, and other clocks with the same panel size show it. See Mirroring.
• Pause button on the dashboard: one tap stops the automatic app change, another starts it again. See Controls under the preview.
• One sound mixer with Master, Radio, Apps and Alerts, in the Audio tab and as four volume controls plus a Stop sound button in Home Assistant. See Volume.
• Repeat any sound with "loop": true. See Repeat a sound.
• Songs: a built-in synthesizer plays music written as text, many instruments at once. A song plays like any other sound, once or with "loop": true. See Song text.
• Text alignment: textAlign puts still text left (start), centered (center) or right (end). See Positioning and alignment.
• Two new fonts, matrix-light6 and matrix-chunky8x6, and every font works in pushed apps and notifications, not only small and large. See The fonts.
• More characters in every font: all fonts share the same 731 characters, with Greek, Vietnamese, IPA, more currency signs and the Chinese and Korean date and weekday characters.
• Sounds that come with a script: a script brings its own MP3s. Manage them in the Scripts tab. Deleting a script asks whether its sounds go too. See Sounds of a script.
• Rename MP3s with the pen next to each MP3 in the Audio tab, or over the API. See Rename an MP3.
• A script's saved data can be viewed and edited in the Scripts tab (Data). See Storage.
• Scripts check the clock: a script says which hardware and panel size it needs and which other scripts it uses. The web UI warns when a script does not fit and offers to install what it needs. See Scripts from the AWTRIX Hub.
• Hub links for this clock: "Scripts for this device" and "Icons for this device" show only what fits.
• Rename icons on the clock. The icon editor draws up to the size of your panel. See Icon editor.
• Boot screen: after the start animation the clock shows its address. See Read it from the panel.
• Home Assistant: the clock's device page links to its web UI.
• MQTT error events: every refused HTTP or MQTT command is also published on <prefix>/event/error. See MQTT topics.
• Switch one app on or off with PUT /api/v1/apps/<name>/enabled or the MQTT topic <prefix>/cmd/apps/<name>/enabled, sending true or false. Every other app stays as it is. See Switching an app on or off.

For script developers¶

• One sound object everywhere: sound.play(), notify(), HTTP and MQTT take a name, or a map with file, rtttl, song, track or station, or a list of up to 4 where the first one the clock can play wins. sound.can() tells what the clock can play. See Sound and music.
• sound.stop('loop') stops only the script's music. A script's sounds stop with the script.
• A bad sound raises value_error at the call, for example a broken melody.
• music.station() and music.title() give the playing station and song title.
• New header lines: # @ondemand, # @requires <name> [hub-id], # @needs … and # @display WxH. A # comment may end an @icons, @needs, @display or @requires line. See Every header key.
• @config … group="…" puts settings into folding sections. See Settings the user can change.
• rotation.close() ends an on-demand script.
• icon() takes inline data URLs.
• The script editor's API list shows every way to call a function, for example both forms of scroll_text().
• The scripting guide is rewritten for beginners.

Improved¶

• Apps tab: apps are grouped by what they do. Every change is saved at once, with Undo. Each row has an on/off switch and Move up / Move down. See Apps.
• App settings in the Apps tab: the settings of the clock, date, temperature, humidity and battery apps are on the app's row. Time and Date each have their own weekday bar.
• Audio tab: compact lists, MP3 search and a now-playing bar with a stop button.
• Background effects: BrickBreaker, PingPong and Snake really play, and the other effects match or beat AWTRIX 3. Thunder draws lightning bolts, and frost shimmers. See Visual reference.
• Setup hotspot: only Wi-Fi setup, restoring a backup and restarting are possible there, and passwords cannot be read. Requests must come from the clock's own page.
• MAC address: the setup page and the dashboard show the clock's Wi-Fi MAC address, for networks that only admit known devices. GET /api/v1/device has it as macAddress. See Connect to Wi-Fi.
• Backups: Create backup starts with every category selected and includes script sounds. A restore skips settings this firmware does not know, and a backup from another model restores the settings that model supports.
• Passwords: password fields have a show button, and the login password is entered twice.
• Web UI header: the book button opens the documentation for your clock, and the shop button opens the AWTRIX Hub.
• Radio: stations are listed A–Z everywhere, and the volume follows a natural curve.
• A refused MP3 upload says which file names are allowed.
• The DFPlayer switch appears only when its pins are set.
• A failed Modbus read names the reason in the log.
• MQTT reconnects cleanly after Wi-Fi comes back.
• The web UI loads faster, and the firmware uses less memory.
• The documentation is rewritten for beginners, with release notes and new pages for the device menu, mirroring, reset and recovery.

Fixed¶

• Security: a web page you visited could read the clock's passwords, install firmware, restore a backup or reset the clock while no login was set. These actions answer only the clock's own web page and tools such as curl or Home Assistant. See Requests from other web pages.
• Overlays: rain, drizzle, storm and snow no longer cut dark holes into text and icons.
• Short inline icons were not shown, and long icon file names were read as image data.
• A notification with a number as sound played nothing. Use {"track": n} now.
• Auto brightness on a clock without a light sensor no longer keeps the display at its lowest brightness.
• The degree sign in the small font has its 2 × 2 shape again.
• Time app: with the calendar box and the weekday bar switched off, the time sat one row lower than the text of other apps.
• Upper-case text also turns Vietnamese letters into capitals.
• Scripts:
  • A script uploaded with curl's default content type arrived empty.
  • A number written as .5 could take a wrong value. Syntax errors name the right keyword.
  • Calls with ||, && or := in an argument get the following arguments right.
  • A broken or hostile script can no longer crash the clock.
  • A script waiting for an HTTP or Modbus answer works again after its app was switched off and on.
  • Saving a script's settings no longer overwrites what the script stores while it restarts.
  • Renaming a script keeps its saved data and settings.
  • An app you operate with the buttons is not switched away while you use it.
  • Two scroll_text() strips on one row, for example a left and a right half, did not move.
  • num() reads numbers with leading zeros such as "07", and numbers with spaces or a line break around them.
• A script could take the name of a built-in app and replace it. Apps named active, next, previous or order could not be deleted. Both names are now refused.
• Static IP settings that would cut the clock off the network are refused.
• The Wi-Fi list in the setup hotspot could stay empty while a phone was connected.
• A failed save of the app order or the station list is reported, and the file is never left half written.
• A large bitmap in a draw command could restart the clock when memory was short.
• A body of { } with a space counted as content: it created an empty pushed app or switched the mood light on. It is refused like {}.
• A palette with more than 16 colors and a palette file that is not a palette are refused.
• MQTT button presses that came quickly one after the other could get lost.
• Web UI: a failed restore showed "[object Object]", a backup could contain an error page instead of a file, and the live view stopped after one failed frame.
• Radio:
  • Playlists whose address contains a ? and audio/mpegurl playlists play. Many German stations use them.
  • A station reconnects through its own address, so expiring stream links no longer stop it.
  • MP3s and stations with low sample rates (8–24 kHz) play, including Home Assistant Cloud speech.
  • Stopping an MP3 or melody in the Audio tab no longer stops the radio.

Breaking changes¶

These changes need action when you update from 1.1.2.

Volume¶

The old volume settings are dropped and not carried over. After the update volume is 60. Set your volumes again in the Audio tab. A clock that was muted with soundEnabled: false makes sound again until you set volume to 0. See Volume.

The old keys are refused with 422.

Notifications and pushed apps¶

The old keys, a number as sound and plain base64 are refused with 422. See The sound object and Inline icons.

Playing and stopping sounds¶

These apply to POST /api/v1/audio/play and POST /api/v1/audio/stop, and to the MQTT topics cmd/audio/play and cmd/audio/stop. See Play a sound.

Scripts¶

See Sound and music.

Nesting deeper than 25 levels no longer compiles.

Names, files and stations¶

• An MP3 and a melody can no longer share a name (409 nameTaken). Pairs already on the clock stay; rename one of them.
• Apps cannot be named active, next, previous or order (400), or after a built-in app such as Time (422).
• Radio stations are always sorted A–Z. {"station":2} means the second station of that list.
• The icon menu has Rename instead of Reload from Hub.

MQTT and Home Assistant¶

• state/buttons/left, select and right are no longer retained. On connect AWTRIX deletes old retained messages and sends the current state once. See MQTT topics.
• The Home Assistant entity Brightness mode exists only on clocks with a light sensor.

Other¶

• Reading passwords (?secrets), PUT /api/v1/system, restoring a backup, installing firmware and the factory reset are refused with 403 forbiddenOrigin when a web page on another address sends them. The clock's own web page, curl, Home Assistant and other tools are not affected. See Requests from other web pages.
• Broken JSON sent to a script's /config or /data route answers 400 invalidJson.
• An indicator command without blinkMs or fadeMs gives a steady light, as on AWTRIX 3. Send them with every command that should blink or fade. Switching an indicator in Home Assistant also stops blinking. See indicators.
• The web UI is in English only.
• Error messages are shorter; the error codes are unchanged. Automations that compare message texts need an update. See Errors.
• Uploads that cannot be written answer 507 insufficientStorage instead of 500.
• JSON nested deeper than 16 levels is refused with 400 invalidJson.
• Screenshots and GIF recordings from the web UI are saved at one pixel per LED.

Still works, but please switch¶

• Settings of the built-in apps have their own route, /api/v1/apps/builtin/{name}/config. PATCH /api/v1/settings still takes them with the same key names. See PATCH /api/v1/apps/builtin/{name}/config.
• textCenter still works; use textAlign.

AWTRIX Hub¶

The AWTRIX Hub has scripts, icons and automations for your clock. These changes are live on the Hub already.

• Choose your device: pick your clock at the top of the Hub, or let the Hub read it from your AWTRIX. It then shows only what runs on your clock and says why the rest does not.
• One entry, the right version: a script can come in a 32×8 and a 52×16 version. The Hub installs the one that fits your panel.
• Everything a script needs in one step: installing a script also installs the modules and background scripts it uses, and its sounds.
• Try an icon first: the Hub shows an icon on your clock for a few seconds before you install it.
• Community: likes, replies under comments, and a note when someone answers you or comments on your work. Signed-in users see a script's code with Berry highlighting.
• Your browser: to reach your clock, Chrome and Edge ask for access to your local network. Allow it. Safari and the browsers on iPhone and iPad cannot reach your clock from the Hub: use Chrome, Edge or Firefox on a computer or an Android phone.

For authors:

• The share form reads what a script needs from its code, so you do not tick it again.
• Made for says whether a script runs on every clock or needs the 52×16 panel.
• One entry holds up to six versions, for example one per panel size.
• A cover and up to six gallery pictures, animated covers included. A script brings its own sounds. The icon studio draws up to 52×16.
• Uploads must run on the official AWTRIX NG firmware, not on forks or modified builds.