Icons¶

This page shows how to get icons onto AWTRIX and show them next to the text of an app or a notification.

What you get¶

Install the icon sun from the AWTRIX Hub, then send:

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/weather \
  -H 'Content-Type: application/json' \
  -d '{"icon":"sun","text":"21°C"}'

The sun stands at the left edge, and the text in the space to its right.

How it behaves¶

A new AWTRIX has no icons: you add the ones you want, from the AWTRIX Hub, as files of your own, or drawn in the Icon editor. Each icon is a GIF or JPEG file in /ICONS, and its file name without the extension is its ID: sun.gif is "icon":"sun". The icon key puts the icon at the left edge. An 8×8 icon takes the left 8 columns and a gap of 1, and the text uses the rest (Icon and text). Drawing commands ignore the icon and count from the left edge, so a shape next to an 8×8 icon starts at x = 9.

Install from the AWTRIX Hub¶

The AWTRIX Hub is a free community collection of icons.

1. In the web UI, open Icons → Add → Icons for this device, or go to the AWTRIX Hub directly.
2. Search for an icon and open it.
3. Press Send to AWTRIX.

Your browser downloads the icon and copies it to AWTRIX over your local network. AWTRIX itself never contacts the Hub.

Downloading needs a Hub sign-in. Reloading an installed Hub icon, publishing, and installing the icons a script asks for with # @icons need a Hub connection key:

1. Create a key in your Hub account.
2. Paste it in the web UI under System → AWTRIX Hub.

The key stays in this browser and is not stored on AWTRIX.

Icons from the Hub carry a Hub badge in the web UI. Use the icon's name in a payload or in a script's # @icons line.

Share an icon in the Hub¶

Every icon on the device has Publish to Hub in its ⋯ menu, and the Icon editor can publish your drawing. Both share the icon in the Hub under a display name you choose.

You need an AWTRIX Hub account and the connection key under System → AWTRIX Hub. The icon must be a GIF of at most 52×16 pixels and under 64 KB. If the exact same image is already in the Hub, it is refused and the Hub names the icon that has it. Accepted icons are published at once. There is no review, and unsuitable icons are removed afterwards.

Upload an icon¶

1. In the web UI, open Icons → Add.
2. Drop your files on the upload area.

The web UI takes GIF, PNG and JPG and turns PNG and JPG into GIF for you, so mail.png lands as mail.gif. To draw an icon yourself, or change one, use the Icon editor. It offers sizes up to your whole display.

With curl¶

Upload the file, then use it:

# 1. upload an 8x8 JPEG. The file name becomes the icon ID.
curl -X POST "http://<awtrix-ip>/api/v1/files?dir=/ICONS" \
  -F "file=@1234.jpg"

# 2. use it
curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{"text":"Mail","icon":"1234"}'

The icon ID is the file name without the extension. 1234.jpg is "icon":"1234" in a payload, never "1234.jpg" and never a path. IDs are case-sensitive, so Mail.jpg is "Mail".

?dir= defaults to /ICONS, so you can leave it out for icons. The name of the form field does not matter, only the file name counts.

Choose a format and size¶

AWTRIX shows two formats. For an ID it looks for these files, in this order:

Use GIF. At icon size a JPEG looks blurry and is larger. Use .jpg only for icons you already have.

Size¶

• A JPEG icon in the icon field or in Berry icon() should be 8×8.

• A GIF keeps its own size, up to the width and height of your display. A 64×8 GIF plays at full size on a 64×8 display. In the icon field, a GIF as wide as the display is drawn as a background behind the text.

• The same limits apply to script icons, pushed apps and notifications.

• The web UI converts PNG and JPEG up to the display size into GIF without resizing, and refuses larger images.

Keep every animation frame within your display's width and height, and resize large GIFs before you upload them. If an image does not load, try a smaller or shorter GIF.

GIF playback¶

Show an icon next to the text¶

Notifications and pushed apps both take the icon key, as in What you get. By default the icon stays where it is while long text moves. With "iconMode":"push", the moving text pushes the icon out of the display, and the icon comes back on every run:

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/news \
  -H "Content-Type: application/json" \
  -d '{"text":"Long headline that scrolls","icon":"sun","iconMode":"push"}'

More icons where you want them¶

The icons array shows up to four more images, each at its own x and y. Each one animates on its own, and they take no space from the text:

{
  "icons": [
    {"icon": "sun", "x": 0, "y": 0},
    {"icon": "sun", "x": 16, "y": 0}
  ]
}

You can use the icon key in the same payload.

Send the icon inside the payload¶

You can also send the image inside the payload, without uploading a file. Write it as a data URL in place of the ID:

• data:image/gif;base64, followed by a base64-encoded GIF
• data:image/jpeg;base64, followed by a base64-encoded JPEG

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d "{\"text\":\"Inline\",\"icon\":\"data:image/jpeg;base64,$(base64 -w0 1234.jpg)\"}"

This suits a one-off notification that should not leave a file behind. The image travels with every request, so the payload is larger. Script apps can pass the same data URL to icon().

List and delete icons¶

1. In the web UI, open the Icons tab. It lists every icon on AWTRIX.
2. To delete one, open its ⋯ menu, choose Delete, and press it again to confirm.

With curl¶

# what is on AWTRIX, and how full is it?
curl "http://<awtrix-ip>/api/v1/files?dir=/ICONS"

The answer has a files array of {"name": …, "size": …} entries, plus usedBytes and totalBytes for the whole storage.

# remove one: this takes a full path, not an ID
curl -X DELETE "http://<awtrix-ip>/api/v1/files?path=/ICONS/1234.jpg"

DELETE takes ?path=, a full path. GET and POST take ?dir=, a folder.

Download an icon¶

In the Icons tab, open the icon's ⋯ menu and choose Download icon.

With curl¶

# download an icon from AWTRIX
curl http://<awtrix-ip>/ICONS/1234.jpg -o 1234.jpg

AWTRIX creates four folders at boot:

/ICONS/, /MELODIES/ and /PALETTES/ can always be downloaded this way. /SCRIPTS/* and the app order file /apploop.json can be downloaded except in setup mode, while AWTRIX runs its own setup access point. A script's code is also available at GET /api/v1/apps/script/{name}. If you set a web login, it applies here too.

Check the free space¶

Icons, melodies, palettes and scripts share the free storage on AWTRIX. On a board with 4 MB flash that is 512 KB, enough for a few dozen 8×8 JPEGs, or fewer animated GIFs. Larger boards have more.

The web UI shows the storage bar in the Icons tab. The API reports it as usedBytes and totalBytes from GET /api/v1/files. An upload that does not fit is refused, so check the free space before large uploads.

Good to know¶

• An ID that matches no file shows no icon, and the text is centered on the whole display. Write the file name without the extension, with the same capitals: Mail.gif is "Mail".
• When both mail.gif and mail.jpg exist, mail always shows the GIF. Delete the one you do not want.
• The API refuses a PNG with 415 unsupportedMediaType, also when you rename it to .jpg, because AWTRIX looks at the content. Convert it to GIF first, or upload it in the web UI, which converts it for you.
• After a rename in the icon's ⋯ menu, apps and scripts that use the old name show no icon. Change them to the new name.
• Until you set a web login, anyone who can reach AWTRIX can upload and delete files. Set one, see Authentication.

Details¶

• Payload → Icon: icon, iconMode, iconOffsetX and iconGap, the space an icon takes, the full-width GIF background, and a missing icon
• Payload → Multiple icons: the icons array, its drawing order and limits
• HTTP reference → Files: uploading, listing and deleting, with every status code
• HTTP reference → Web UI and static assets: downloading files
• Limits → Storage and Limits → Display: the storage of each board, and the largest GIF
• Persistence and resets: a factory reset erases every file, a settings reset keeps them

Related¶

• How the display works: where the icon and the text sit
• Icon editor: draw and edit icons in the web UI
• Text & colors: the text next to the icon
• Sound: /MELODIES and the RTTTL format