The web UI¶

AWTRIX has its own web UI. Open it in a browser to see the display live, change every setting, manage apps, scripts, icons, sounds and palettes, and update the firmware. It needs no app and no cloud account.

Open the web UI¶

1. Make sure your phone or computer is on the same network as AWTRIX.

2. Open the AWTRIX hostname in a browser, for example:

   http://awtrixng-a1b2c3.local/
   

3. If the .local name does not open, use the IP address instead. See Find your clock.

The page is stored on AWTRIX itself, so it works without an internet connection. Only a few extras load from the internet: the icon editor, the AWTRIX Hub links and the firmware update check.

The header¶

The buttons at the top right:

The tabs¶

On a phone the tabs sit in a bar at the bottom, on a computer in a row at the top. Each tab has its own address, so you can bookmark it:

The web UI shows only what your device can do.

Dashboard¶

Live preview¶

The large picture at the top shows every LED of your display, updated four times a second. The same picture on its own is at http://<awtrix-ip>/fullscreen. You can put it in a Home Assistant dashboard or any other web page.

Controls under the preview¶

Save a screenshot or GIF¶

1. Press ↓ for a still picture, or ● to start a recording. The button turns red while it records.
2. Press ● again to stop. A recording also stops by itself after 240 frames or 10 seconds.
3. The file lands in your browser's download folder, named awtrix-<timestamp>.

Without 1:1, each LED is drawn as a large block with a thin dark gap, so the picture looks like the real display. The 52×16 display gives a 5200×1600 PNG and a GIF of up to 1040×320. The GIF plays back at the speed it was recorded. Every PNG and GIF is small enough to use as a cover or gallery picture in the AWTRIX Hub.

While it records, the display may run a few frames per second slower.

Status tiles¶

Tiles show how the device is doing. A tile appears only when the device has that sensor.

Below the tiles: firmware version (with a note when an update is available), hostname, IP address, MAC address, uptime, free memory, and the app shown now.

What each value means: Device state.

Apps¶

The Apps tab decides what AWTRIX shows and in which order. Every change is saved at once. The message that confirms it has an Undo button for a few seconds.

Each group shows its number of apps next to its title. Every group except On the display starts folded away. Tap its title to open it.

The groups¶

A group without apps is not shown, except On the display.

Change the order¶

Drag a row by its ⠿ grip. This works with a mouse and with a finger. Move up and Move down in the row's ⋯ menu do the same one step at a time.

What a row can do¶

The ⋯ menu holds the rest:

Built-in apps cannot be deleted, only switched off. Scripts are deleted in the Scripts tab.

Under the name, a row says what kind of app it is: Built-in, Script or Pushed (over HTTP or MQTT). Labels next to the name point out something to know. Tap one for a short explanation:

If scripts are switched off under System → Scripting, a banner says so at the top.

The same order can be set over the API: HTTP API → Apps.

Scripts¶

An editor for Berry apps. On the left, a list of what is installed: Scripts first, then Modules. On the right, the code with color highlighting.

Write and install a script¶

1. Press + next to Scripts to start from a template. (+ next to Modules starts a module.)
2. Type a name in the name field and write your code.
3. Press Save or Ctrl-S. This installs the script and starts it.
4. Press Show on the clock to switch the display to your script.

If the script has an error, the line is marked in the editor. The bar under the editor shows the cursor position and how much of the allowed size you have used.

Code and Data above the editor switch between the script and the values it saved, as JSON. Saving changed values restarts the script. See Storage.

Buttons and keys¶

Unsaved work stays in the editor when you visit another tab. If you open another file, the editor asks first.

Rename a script: change the name and save. AWTRIX keeps the new name and removes the old one. The script's sounds move along.

Scripts that need more than your device has¶

A script can say what it needs, for example a gamepad or a certain display size (see @needs and @display). If your device does not have it, saving or importing tells you what is missing, for example Not for this clock: needs a gamepad. You can choose Save anyway, Import anyway or Cancel.

Sounds of a script¶

On a clock, the editor bar has a note button. It shows how many sounds the script has and opens them in the Audio tab, where you add, play and delete them. Modules have no sounds of their own.

Delete a script with the bin next to it. Press twice to confirm. A script with sounds asks instead: Delete with sounds, Keep sounds or Cancel. Kept sounds stay in the Audio tab, marked script removed, until you delete them there. A script installed again under the same name uses them.

Scripts from the AWTRIX Hub¶

• Check for updates checks every script you installed from the Hub and marks those with a newer version. See Hub script updates.
• Scripts for this device opens the Hub with the scripts this AWTRIX can run.

Shared values¶

The Shared list below the files shows the values scripts publish to each other with shared.set(). Tap Shared to open it. Each row shows owner.key and the value. A value written more than five minutes ago turns amber. Point at a row to see how long ago it was written. The list updates every three seconds, is read-only, and is empty again after a reboot.

How to write scripts: Scripting guide.

Icons¶

The header shows how much storage is used. The bar turns red above 90 %. The tab has two parts:

Add an icon¶

• Add icon: drop .gif, .png, .jpg or .jpeg files on the upload area, or click it to choose. Each file gets its own progress line.
• Icons for this device: opens the AWTRIX Hub with icons that fit your display. Pick one and press Send to AWTRIX. Your browser copies the file to the clock over your local network.
• Create an icon: opens the Icon Editor.

PNG and JPG files are turned into GIF while they upload. That looks sharper on the display and uses less space. So smiley.png becomes smiley.gif and replaces an older smiley.jpg. Animated GIFs stay animated. Keep icons within your display's width and height. 8×8 is the usual size for a still icon. A GIF as wide as the display can fill the background behind the text. See Payload → Icon.

Use and manage an icon¶

Show on the clock shows the icon on the display for three seconds. The ⋯ menu on a tile:

Icons from the Hub carry a Hub badge. One you changed says Changed on the clock.

Publishing needs a Hub connection key. Create one in your Hub account and save it under System → AWTRIX Hub. The key stays in this browser. It is not stored on the clock.

More: Icons.

Icon Editor¶

A pixel editor to draw icons and animations and save them straight to AWTRIX.

1. Open the Icon Editor tab, or choose Edit on an icon in the Icons tab.
2. Choose a size: 8×8, 32×8, 16×16, the whole display, or your own size up to the display size.
3. Draw, give the icon a name and save. It appears in the Icons tab.

The Live switch shows your drawing on the real display while you work.

The editor loads from the internet. Without internet the tab says the editor could not load. The rest of the web UI keeps working.

More: Icon editor.

Audio¶

Everything that makes sound: the Mixer, then MP3s, Radio and Melodies.

A bar at the top shows what is playing now: the sound's name, or the station and song title. ■ stops it.

In all three lists, ▶ plays the entry on AWTRIX and turns into ■ while it plays. ■ on an MP3 or a melody stops that sound, and the radio keeps playing. ■ on a station stops the radio, and other sounds keep playing. The bin deletes the entry. Press twice to confirm.

Mixer¶

How loud the clock plays. Each slider goes from 0 to 100 and applies at once:

With Master at 50 and Alerts at 60, a notification plays at 30. The knob moves Master too.

More: Volume.

MP3s¶

Your own MP3 files, for notifications and scripts.

1. Drag MP3 files onto ⬆ Upload, or click it to choose.
2. Use the file name without .mp3 elsewhere: ding.mp3 plays with "sound":"ding" in a notification.

File names may only use letters, digits, _ and -. A file called My Song (2024).mp3 is refused. Rename it first. An MP3 cannot have the name of a melody either. The line below the button shows how many sounds you have, their size and the free storage. Search sounds filters the list.

An MP3 pauses internet radio. The radio comes back by itself afterwards.

Sounds of scripts. Below your own files, every script with its own sounds has a closed group, for example AWTRIX GP · 21 · 1.4 MB (name, number of sounds, size). Open it to play, delete or upload sounds for that script. Before deleting, it says whose sound it is: Sure? Used by AWTRIX GP.

To open the tab with one script's group open, use #/audio/<script>, for example http://<awtrix-ip>/#/audio/awtrix-gp.

More: Sound.

Radio¶

Your internet radio stations.

1. Press + Add station.
2. Enter a name and the stream URL. ▶ in the form tries the URL before you keep it.
3. Press Save or Enter. Cancel or Esc closes the form without a change.

The URL must start with http:// or https://, and each name can be used only once. Otherwise a message appears under the fields and Save stays off. In the list, point at a row to see the full URL. The pencil edits a station.

More: Internet radio.

Melodies¶

Short ringtones in RTTTL format, for notifications and scripts. Each row shows the number of notes and the length, for example 10 notes · 2.3 s. A melody with an error is still listed, marked Invalid melody, so you can fix it.

Add a melody:

1. Press + New melody.
2. Name: 1–24 characters of A-Z, a-z, 0-9, _, -. This is the name you use in "sound":"<name>". It cannot be the name of an MP3.
3. RTTTL: only the part after the name, for example d=4,o=5,b=100:e,c.
4. Press Save or Enter.

The melody is checked while you type. If it has an error, the line below names it, for example 'h' is not a note. 🎧 and ▶ in the form play what is in the fields now, so you can listen before you save. 🎧 plays in your browser, so you hear it even with the clock's volume at 0.

If you paste a complete melody such as jackpot:d=8,o=5,b=120:16c,16e,16g,c6 into the RTTTL field, the name moves to the name field by itself. To rename a melody, change the name and save.

More: Sound · HTTP API → Audio.

Palettes¶

A list of every palette AWTRIX knows, each shown as the color ramp it paints, and an editor next to it. You can make your own palettes and change or restore the eight built-in ones.

How to use it: Palette editor · built-in palettes: Visuals → Palettes.

Display¶

Settings for what the display shows, in five sections: Brightness, Color, App rotation, Text and Weather overlay. The section list stays at the top while you scroll. Clock, date and sensor settings are under Apps → ⚙ on the app's row.

Save your changes¶

1. Change as many settings as you like. The bar at the bottom counts your unsaved changes.
2. Press Save to send only what you changed, or Discard to undo.

If AWTRIX refuses a value, nothing from that save is applied, and a message names the setting.

Black and white in color fields¶

For the clock, date, temperature, humidity and battery colors, open Apps → ⚙. Switch Global text color on to inherit the text color, or off to choose a color of the app's own, including black.

Under Display → Color, white means off for Color correction and Color tint.

Every setting with its range and default:

• Settings → Brightness
• Settings → App rotation
• Settings → Clock app, Clock text, Date text, Weekday bar
• Settings → Global text
• Settings → Sensor apps
• Settings → Color: saturation, gamma, correction, tint
• Visuals → Weather overlays · Transitions

System¶

Device settings in these sections: Wi-Fi, Web server, MQTT, Time, Panel, Brightness & sensors, Buttons, Audio, Scripting, Mirroring, Misc, then AWTRIX Hub, Gamepad, Home Assistant Voice, iPhone, Maintenance and Backup & restore.

All fields are in System configuration: Wi-Fi, MQTT and Home Assistant, Time, Identity, web server and authentication, Buttons, Settings → Sound, Miscellaneous.

Save works as on the Display tab. When a change needs a restart, an amber banner says Saved. Reboot to apply. Its Reboot now button restarts the clock. Sound settings apply at once.

Wi-Fi¶

The Scan button next to the network name searches for networks and lists them by signal strength. 🔒 marks networks with a password.

Passwords¶

Password fields always look empty, with (unchanged) in them. Leave a field empty to keep the saved password. Type a new one to change it.

MQTT¶

A badge at the top shows the connection: whether the broker answered, the address it connected to, or why it failed (for example Wrong login or Host not found).

Time¶

Use my zone takes the time zone your browser is set to.

Panel¶

The display is fixed at 52×16, so this section only shows the size.

Brightness & sensors¶

The clock has no light sensor, so this section holds only the low-battery threshold.

Audio¶

The sound hardware. The volumes are on the Audio tab.

• Boot sound turns the sound at power-on on or off.
• Music source picks what music visualizers and music.pitch() react to: what the speaker plays, the microphone, or automatic.

AWTRIX Hub¶

Paste your Hub connection key here to download icons and script updates from the AWTRIX Hub and to share icons. Open Hub account takes you to the page where you copy the key. The key is saved only in this browser. In another browser, enter it again. Remove key deletes it.

Gamepad¶

Shows the two gamepads, whether they are connected, and their player numbers. Pair adds a gamepad. Each Forget removes only its own gamepad. The player number goes by first input and can differ from the row number. While a phone is a gamepad, a Phone row shows which player it plays. See Gamepad.

Home Assistant Voice¶

Enter the Home Assistant address, an access token and the Assist pipeline, then press Save and connect. The Voice switch turns it on and off at once. A badge shows the connection or, in plain words, why it fails. See Home Assistant Voice.

iPhone¶

iPhone link switches the connection on and off. Connection shows the iPhone and whether it is connected. Forget iPhone removes the remembered iPhone. The apps, music and covers are chosen in the AWTRIX NG app. See iPhone.

Advanced¶

This section appears only when the firmware has a setting the page has no field for. You can change the raw value there.

Maintenance¶

More: Updating firmware · Persistence and resets.

Backup and restore¶

Create a backup:

1. Tick what to include: Wi-Fi, Settings, Icons, Melodies, Palettes, MP3s, Scripts, App order. Scripts include their sounds.
2. Press Download backup. Your browser saves a .zip file.

The file is built in your browser. Nothing is stored on AWTRIX or sent anywhere else.

Restore a backup: press Choose backup… and pick the .zip. Anything that could not be restored is reported as a warning. If the backup changed Wi-Fi, system settings, settings or the app order, you are offered a reboot.

Log¶

The device log, updated every second while the tab is open.

• Auto-scroll follows new lines. Scroll up and it pauses. Scroll back to the bottom and it continues.
• Copy puts the whole log on your clipboard, for example for a bug report.
• Clear empties the list in your browser only.

For more detail in the log, switch on System → Misc → Debug mode.

Setup mode¶

A new AWTRIX, or one after a factory reset, opens its own Wi-Fi network, the setup hotspot. Connect to it and the setup page opens by itself.

The web UI then shows only the System tab, with a blue banner: Setup mode: connect the clock to your Wi-Fi below. You get:

1. the clock's MAC address, then your Wi-Fi name and password, plus an optional clock name,
2. Reboot: AWTRIX restarts and joins your network,
3. Restore: load a backup, Wi-Fi included, after a reset.

The other tabs come back once AWTRIX is on your network. If you set a web login, it is also needed on the setup hotspot. See Authentication.

If the Wi-Fi sign-in window on your phone cannot upload the backup file, open the setup page address it shows in a normal browser. Logs, scripts, file lists and other settings are unavailable on the setup hotspot. See the complete setup-mode policy.

When it goes wrong¶

• A message pops up at the bottom. It is AWTRIX's own error message and names the field that caused it. See Errors.
• "Clock not reachable". The page cannot reach AWTRIX. Check that it is on and on the same network, then reload.
• A button says "Sure?" Delete, reset and reboot buttons need a second press within three seconds. If you wait, the button goes back to normal and nothing happens.
• The Icon Editor does not load. It needs internet access.

Related¶

• HTTP API - every route, with curl
• MQTT topics - the same commands over a broker
• App & notification payload - what you can put on the display