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, melodies 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. For example, the Audio tab is missing on a device with neither a buzzer nor a speaker.

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. A 32×8 display gives a 3200×800 PNG and a 640×160 GIF. Larger displays are enlarged less. 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.

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.

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, 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 and the Melodies.

In the list, ▶ plays a melody on AWTRIX and turns into ■ while it plays. ■ stops it. The bin deletes the melody. 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.

More: Volume.

Melodies¶

Short ringtones in RTTTL format, for notifications and scripts. Only on a board with a buzzer. 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>".
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, GPIO, Buttons, Audio, Scripting, Mirroring, Misc, then AWTRIX Hub, Maintenance and Backup & restore. Sections your board cannot use are hidden.

All fields are in System configuration: Wi-Fi, MQTT and Home Assistant, Time, Identity, web server and authentication, Sensor calibration, Auto-brightness, Buttons, Sound hardware, 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¶

Describe your LED panels:

• how wide one panel is and how many panels the cable runs through,
• which corner the first LED is in,
• whether the LEDs run along rows or columns,
• whether every second row runs back the other way (Serpentine).

The Display size line adds it up while you type, for example 32 × 8 = 256 LEDs. It turns red if the total width is outside 32–128. Such a value is not saved.

Mirror flips the picture left to right. Rotate 180° turns it upside down and swaps the left and right buttons. Use it when the display hangs upside down.

Everything except the total width takes effect right away, so you can flip Serpentine and watch the display.

The built-in apps are drawn for 32 pixels width. On a wider display they are centered.

All fields: Panel and orientation.

Brightness & sensors¶

Minimum and maximum brightness, light sensor factor and gamma, LDR on GND and brightness smoothing, shown only on a board with a light sensor. Below them: battery divider, low-battery threshold, and temperature and humidity offset and decimals.

GPIO¶

Which pin does what: LED data, three buttons, battery, light sensor, buzzer, I²C and DFPlayer. -1 means "not connected". LED data is a list of the pins that can drive LEDs.

Preset wiring fills in the wiring of a Ulanzi TC001 or an AWTRIX 2 mainboard. It does not save. Check the fields, then press Save. Wrong or conflicting pins are refused when you save. GPIO changes apply after a reboot.

More: GPIO & boards · Board presets · Validation rules · Recovery from a bad map.

Audio¶

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

• DFPlayer adds a DFPlayer module on the DFPlayer pins. It shows once both DFPlayer pins are set under GPIO.

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.

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, Scripts, App order. Melodies are only offered where the board has a buzzer.
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