Skip to content

Your first notification

This page shows you how to send a short message that interrupts the clock, and how to change its look, its sound and how long it stays.

New here?

How the display works shows where things sit on the display and which text moves by itself.

What you get

Replace <awtrix-ip> with the IP address of your clock and run:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Hello"}'

What the notification shows on the display

The display shows HELLO for seven seconds, then the rotation goes on. The answer is:

{"ok":true}

Everything else on this page is one more key in that JSON object. <awtrix-ip> can also be the hostname, awtrixng-xxxxxx.local by default. See Find your clock.

How it behaves

A notification is shown once, on top of the rotation, for seven seconds by default. The rotation keeps turning behind it, so afterwards you often see another app than before. Notifications that arrive meanwhile wait in a queue and are shown one after the other. The text moves only when it does not fit, and text you draw with draw never moves (When text moves). The notification ends when its time is up, even in the middle of moving text. To keep it until the text has been read, add repeat next to text.

A notification is drawn at double size, like a pushed app. So positions in draw count on a grid of 26 × 8: the last column is 25, the last row 7. See The display.

Send it from Home Assistant

Let Home Assistant send a notification from any automation. Add a REST command to your configuration.yaml:

rest_command:
  awtrix_notify:
    url: "http://<awtrix-ip>/api/v1/notifications"
    method: POST
    content_type: "application/json"
    payload: '{"text":"{{ message }}"}'

Restart Home Assistant. Then use it in any automation or script:

action: rest_command.awtrix_notify
data:
  message: "Someone is at the door"

To send over MQTT instead, see Over MQTT.

Keep upper and lower case

Text is shown in capitals, because the uppercase setting is on by default. Send "textCase": "asTyped" to keep your text exactly as you typed it:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Hello","textCase":"asTyped"}'

What the notification shows on the display

Show it in a color

Give the text a color with textColor:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Disk full","textColor":"#FF0000"}'

What the notification shows on the display

These all mean the same red: "#FF0000", "FF0000", "F00", [255,0,0], ["HSV",0,100,100] and 16711680. For several colors in one string, gradients, blinking and fading, see Text & colors.

Show an icon next to the text

icon takes the ID of an icon stored on the clock:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"29°C","icon":"sun","textColor":"#FFAA00"}'

What the notification shows on the display

sun is an icon from the AWTRIX Hub. AWTRIX looks for /ICONS/sun.gif first, then /ICONS/sun.jpg. Only GIF and JPEG work, not PNG. If no file matches, the notification still shows, without the icon and without the space for it.

You can also send the image itself instead of an ID, as a data URL: data:image/gif;base64,… or data:image/jpeg;base64,…. A web address works too: Pictures from the internet. How to get icons onto the clock: Icons.

Play a sound with it

sound plays a sound when the notification appears. It takes the same sound as /api/v1/audio/play.

A stored sound by its name:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Doorbell","sound":"chime"}'

AWTRIX looks for the name in this order:

  1. the MP3 file /MP3/chime.mp3,
  2. the melody /MELODIES/chime.txt.

A notification sent by a script looks in the script's own sounds first. How to upload MP3 files: MP3s.

A melody in the request, in RTTTL. Nothing needs to be stored on the clock:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Doorbell","sound":{"rtttl":"bell:d=4,o=5,b=120:c,e,g"}}'

RTTTL is a short text format for ringtones: a name, the tempo, then the notes.

Speech or a sound, when your clock has a voice. The clock plays the first entry it can play:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Door","sound":[{"speech":"The front door is open."},"ding"]}'

The sound plays once, when the notification appears, at the alert volume (Volume). Add "loop": true inside the sound to repeat it for as long as the notification is shown. It stops as soon as the notification goes.

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"ALARM","hold":true,"sound":{"file":"siren","loop":true}}'

More about sounds: Sound.

Show it longer or shorter

A notification shows for the appDurationMs setting, 7000 ms by default. Set a different time for one notification with durationMs, in milliseconds:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Quick","durationMs":2000}'

Keep it until the text has been read

The notification ends when its time is up, even if the text is still moving. Add repeat to keep it until the text has run through:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"The washing machine has finished","repeat":1}'

What the notification shows on the display

repeat stands at the top level of the JSON, next to text. It does not go inside scroll.

The notification then stays exactly as long as the text needs. A higher number means more passes. If you also set durationMs, it stays at least that long.

Keep it until you remove it

Use hold:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"ALARM","textColor":"#FF0000","hold":true}'

What the notification shows on the display

With hold: true the notification ignores durationMs and stays until you dismiss it. Add a sound with "loop": true for an alarm that does not stop by itself.

Wake a dark display

When the display is switched off (PATCH /api/v1/display {"power":false}), notifications are not shown. Add wakeup to show one anyway:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"Motion","wakeup":true}'

The display lights up while this notification is shown and goes dark again when it ends.

Interrupt the notification shown

Notifications wait in a queue. Send three and they play one after the other, in order. This is stack: true, the default.

Send stack: false when a new message makes the current one pointless. It replaces the notification shown. Notifications waiting behind it stay in the queue:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"URGENT","stack":false,"textColor":"#FF0000"}'

What the notification shows on the display

The replacement starts from the beginning: scrolling, icon and sound. If nothing is showing, stack: false works like a normal notification.

Dismiss a notification

Remove the notification shown before its time is up. On the clock, press select. In the web UI, press the Bell under the live picture on the Dashboard. Over the API:

curl -X DELETE http://<awtrix-ip>/api/v1/notifications/active

This is how you end a hold. The answer is always 200 {"ok":true}, even when nothing is showing. The next notification in the queue appears at once.

Dismiss one by name

Give a notification a name. You can then remove exactly that one later, even if it is still waiting in the queue:

# send one with a name
curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"name":"backup-job","text":"Backup running","hold":true}'

# remove it later
curl -X DELETE http://<awtrix-ip>/api/v1/notifications/backup-job

The answer is 200 {"ok":true} when it was removed, and 404 notFound when no notification with that name is in the queue. Removing a waiting notification does not disturb the one shown.

active always means "the notification that is shown", so you cannot use active as a name.

Over MQTT

Every example on this page works over MQTT with the same JSON. Use these topics:

Topic Does
<prefix>/cmd/notify send a notification
<prefix>/cmd/notify/dismiss remove the notification shown
<prefix>/cmd/notify/dismiss/<name> remove the notification with that name 
mosquitto_pub -h broker.local -t 'a4cf12ab34cd/cmd/notify' \
  -m '{"text":"Hello","icon":"sun"}'

# remove the "backup-job" notification
mosquitto_pub -h broker.local -t 'a4cf12ab34cd/cmd/notify/dismiss/backup-job' -m ''

<prefix> is the device ID (the 12-character MAC address, like a4cf12ab34cd above) unless you set mqttPrefix. From Home Assistant, use the mqtt.publish action. See Sending notifications from Home Assistant and the MQTT guide.

Good to know

  • repeat inside scroll is refused with 422 and "field":"scroll.repeat". Put it next to text.
  • hold stops the queue. The notifications behind it wait until you dismiss it, so do not mix hold with a stream of stacked notifications.
  • The queue holds 32 notifications, counting the one shown. One more is refused with 507 insufficientStorage: send less often.
  • A value of the wrong type is skipped, not refused. {"durationMs":"5000"} answers 200 and keeps the default time. Send numbers without quotes.
  • A sound name that is not stored plays nothing. The request still answers 200, so check the spelling of the name.

Details