MQTT topics¶

This page lists every MQTT topic AWTRIX reads and publishes. AWTRIX connects to one broker. The command, state and availability topics below are everything there is. Home Assistant discovery uses these same topics; it is not a second interface.

Command payloads are exactly the same as the HTTP request bodies, so anything you can send with curl you can also publish. There are no read commands over MQTT: instead, AWTRIX publishes its state to retained topics.

The Conventions apply to every topic: camelCase keys, durations in whole milliseconds with an ...Ms suffix, the color forms ("#RRGGBB" out; "RRGGBB", "RGB", [r,g,b], ["HSV",h,s,v] or a number in; null = use the default / off) and the error format {"error":{"code","message","field?"}}.

Connection¶

These keys are part of the system configuration, not the settings – see System configuration. The MQTT client ID is the device uid.

Topic prefix <P>¶

<P> is the value of mqttPrefix. If you leave it empty, AWTRIX uses its uid – the 12-character MAC address, for example a4cf12ab34cd/cmd/notify. That works, but is hard to read, so set a name.

Every example on this page uses awtrixNG as the prefix. Topics outside <P>/ are ignored.

Command topics¶

AWTRIX reads only topics under <P>/cmd/. Topics under <P>/state/ are only published by AWTRIX. <P>/cmd and <P>/cmd/ alone do nothing.

A topic that is not in this table gets no /result at all – no error, no answer. So a typo in a topic is silent. This includes <P>/cmd/indicators/<bad-id>, where HTTP would answer 404 id must be 1..3. If a command seems to do nothing, check the topic spelling first.

Not available over MQTT: factory reset works only over HTTP (POST /api/v1/device/factory-reset). Publishing to <P>/cmd/device/factory-reset does nothing and gets no answer.

notify¶

Publishes a notification. The payload is the same body as the HTTP route - see App & notification payload.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/notify' \
  -m '{"text":"Doorbell","textColor":"#FF0000","durationMs":10000}'

notify/dismiss¶

Dismisses the active notification. Payload is ignored.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/notify/dismiss' -m ''

notify/dismiss/<name>¶

Dismisses the notification sent with that name, wherever it is in the queue. Payload is ignored. If no notification has that name, the result is notFound.

With names, several senders sharing one AWTRIX can each dismiss only their own messages. It is not a protection – any client that knows the name can dismiss that notification.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/notify'   -m '{"name":"backup-job","text":"Backup running","hold":true}'
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/notify/dismiss/backup-job' -m ''

apps/pushed/<name>¶

<name> is the rest of the topic after apps/pushed/. It must be 1 to 32 characters from A-Z a-z 0-9 _ - ([A-Za-z0-9_-]{1,32}) – the same rule as over HTTP. An empty payload or {} deletes the app; anything else creates or replaces it.

# create / replace
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/pushed/weather' \
  -m '{"text":"21C","icon":"2422"}'

# delete (both forms work)
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/pushed/weather' -m ''
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/pushed/weather' -m '{}'

<P>/cmd/apps/pushed/ with an empty name does nothing. An invalid name is answered on <topic>/result and nothing is stored:

{"ok":false,"error":{"code":"invalidName","message":"invalid name","field":"name"}}

This topic removes pushed apps only. Scripts cannot be installed or removed over MQTT; to remove one, use DELETE /api/v1/apps/{name} over HTTP.

apps/switch¶

Send either just the app name or a JSON object. The payload is read as JSON only when it starts with {.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/switch' -m 'Time'
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/switch' \
  -m '{"name":"Time","fast":true}'

An unknown app answers notFound. A JSON object without name is taken as an app name as it is, and so also answers notFound.

apps/next, apps/previous¶

Payload ignored.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/next' -m ''
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/previous' -m ''

apps/order¶

order lists the apps that rotate, in that order. disabled is the complete list of switched-off apps: every app it does not name is switched on. An app may appear more than once in order. disabled is always required, order is optional.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/order' \
  -m '{"order":["Time","weather","Date"],"disabled":["Battery"]}'

Send disabled alone to keep the order. Battery is then off and every other app on:

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/order' \
  -m '{"disabled":["Battery"]}'

apps/<name>/enabled¶

Switches one app on (true) or off (false). Every other app stays as it is. The rules are those of PUT /api/v1/apps/{name}/enabled.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/apps/Battery/enabled' -m 'false'

settings¶

Any subset of the settings JSON, the same as PATCH /api/v1/settings. If one key is wrong, nothing is applied and the result names it in field. All keys, ranges and defaults are in Settings.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/settings' \
  -m '{"brightness":120,"autoBrightness":false}'

A rejected value answers, for example:

{"ok":false,"error":{"code":"validationFailed","message":"out of range","field":"brightness"}}

settings/reset¶

Payload ignored. Deletes the stored settings and restarts. The /result may not arrive because of the restart.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/settings/reset' -m ''

display¶

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/display' -m '{"power":false}'

display/moodlight¶

An empty payload turns the mood light off, like DELETE /api/v1/display/moodlight.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/display/moodlight' \
  -m '{"color":"#3366FF","brightness":120}'
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/display/moodlight' -m ''

indicators/1 … indicators/3¶

The ID must be 1, 2 or 3. Anything else is ignored without an answer. The three indicators are the dots on the display's right edge – 1 top, 2 middle, 3 bottom. Their state is published in <P>/state/device.

# on, red, blinking
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/indicators/1' \
  -m '{"color":"#FF0000","blinkMs":500}'

# full reset (both forms)
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/indicators/1' -m ''
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/indicators/1' -m '{}'

An empty payload or {} resets the indicator completely (off, black, no blinking or fading). Every other payload sets blinking and fading anew, so {"color":"#00FF00"} gives a steady green light. Without color the indicator keeps its color and stays on or off. {"color":0} switches it off and keeps the stored color.

audio/play¶

The payload is a sound object, as for POST /api/v1/audio/play: a stored name, an object with exactly one source key, or a list of 1 to 4 of them. The sound plays as an alert. station starts the radio.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/audio/play' -m '"ding"'
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/audio/play' \
  -m '{"rtttl":"two:d=4,o=5,b=200:c,e"}'

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/audio/play' -m '{"station":"SWR3"}'

A payload without a source key answers:

{"ok":false,"error":{"code":"validationFailed","message":"needs a sound key"}}

The errors are those of POST /api/v1/audio/play. The whole message, topic included, may be at most 8192 bytes. A longer one is dropped without an answer.

{"ok":true} means the sound was accepted. If the master volume or the alert volume is 0, it plays silently.

cmd/audio/stop stops everything with an empty payload or {}. {"group":"alert"} stops the alert that plays, {"group":"app"} every sound of the scripts, and {"group":"radio"} the radio. Another value answers must be alert, app or radio.

device/reboot¶

Payload ignored. Restarts AWTRIX; the /result may not arrive because of the restart.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/device/reboot' -m ''

device/sleep¶

A valid value answers {"ok":true} on .../result. Right after that AWTRIX goes into deep sleep and publishes nothing more.

mosquitto_pub -h broker.local -t 'awtrixNG/cmd/device/sleep' \
  -m '{"durationMs":60000}'

screen/get¶

Payload ignored. Publishes <P>/state/screen and answers {"ok":true} on <P>/cmd/screen/get/result.

mosquitto_sub -h broker.local -t 'awtrixNG/state/screen' &
mosquitto_pub -h broker.local -t 'awtrixNG/cmd/screen/get' -m ''

The /result reply¶

Every command on a topic from the table above is answered on <cmd topic>/result, not retained, QoS 0:

awtrixNG/cmd/settings        ->  awtrixNG/cmd/settings/result
awtrixNG/cmd/apps/pushed/x   ->  awtrixNG/cmd/apps/pushed/x/result

Success is exactly:

{"ok":true}

A failure has the same error body as HTTP, inside ok:false (field is left out when there is none):

{"ok":false,"error":{"code":"validationFailed","message":"invalid value","field":"brightness"}}

Eight codes can appear here; they and their messages are listed in Errors – Errors over MQTT. HTTP-only codes such as methodNotAllowed, unauthorized and unsupportedMediaType never appear over MQTT.

The code values and messages are the same as over HTTP, with one exception: an unknown app in cmd/apps/switch answers not found, where HTTP says app not found.

AWTRIX never reads a /result topic as a command, so its answers cannot trigger new commands.

To see every failure in one place, subscribe to <P>/event/error instead.

State topics¶

state/device is published at least every statsInterval (default 10 000 ms, minimum 1 000). It is also published at once when the display power or an indicator changes, so a display switched off over HTTP does not show as on for another ten seconds. These extra messages come at most every 250 ms, so an automation that blinks an indicator sends one message every 250 ms, not one per frame.

A brightness change does not publish at once; with auto-brightness the value changes all the time and is sent with the regular interval. state/settings and state/apps/active are sent whenever they change and do not use statsInterval.

state/device¶

Same content as GET /api/v1/device; see Device state for every field, including which fields appear only with a battery pin or a sensor.

state/buttons/<button>¶

Published on every press and release, whether or not an app reacts to it, and only on the topic of the button that changed. It is not retained, so a press reaches only the subscribers listening at that moment and is never replayed later. On each connect AWTRIX sends the current state once and deletes any retained message left on these topics. The buttons are named left, select and right. The HTTP button webhook (buttonCallback) calls the middle one middle.

mosquitto_sub -h broker.local -t 'awtrixNG/state/buttons/+' -v

event/error¶

Sent whenever AWTRIX rejects a command, whether it came over MQTT or HTTP. Use it to find out why a payload from an automation does nothing, without watching every /result topic or reading HTTP responses:

{"source":"http","request":"PUT /api/v1/apps/pushed/weather","error":{"code":"validationFailed","message":"not allowed with layout","field":"text"}}

{"source":"mqtt","request":"awtrixNG/cmd/notify","error":{"code":"invalidJson","message":"invalid JSON"}}

Only commands are reported: pushed apps, notifications, settings, apps, audio, display, indicators, scripts and the device commands. Failed logins, uploads, firmware updates and unknown paths are not.

It is not retained: a new subscriber only sees errors that happen after it subscribed.

mosquitto_sub -h broker.local -t 'awtrixNG/event/error' -v

state/capabilities¶

The transitions list holds the 22 names the transitionEffect setting accepts, in this order:

["Random","Slide","Dim","Zoom","Rotate","Pixelate","Curtain","Ripple","Blink","Reload","Fade",
 "Cover","Uncover","Split","Blinds","Blocks","Flash","Diamond","Wave","Rain","Melt","Interlace"]

palettes is the fixed list of built-in palettes, ["Cloud","Lava","Ocean","Forest","Stripe","Party","Heat","Rainbow"]; your own palette files are not in it. effects and overlays are the names this clock offers – see Visual reference.

state/prefix¶

The prefix itself – awtrixNG/state/prefix contains awtrixNG. Retained, so a new subscriber sees it at once.

It is meant for Home Assistant: the MQTT prefix sensor reads it. A blueprint can then start from the device you pick and find the topic to publish to.

mosquitto_sub -h broker.local -t 'awtrixNG/state/prefix' -v

state/screen¶

pixels is a list of width × height colors, row by row from the top left. Each color is one number (0xRRGGBB written as a decimal number).

Retain and QoS¶

QoS 0 everywhere – for publishing, subscribing and the last will. A message lost on the way is not sent again.

A command you publish may be at most 8192 bytes, topic included. A larger one is dropped without an error and without /result – a very long notification is the usual way to hit this. Messages AWTRIX publishes to you have no such limit: state/device and state/screen are sent at full size. All other limits are in Limits.

Availability and LWT¶

There is one availability topic, <P>/availability (online / offline, retained, QoS 0). AWTRIX publishes online as soon as it connects. It also registers offline as its "last will" (LWT) with the broker, so the broker publishes offline when AWTRIX disappears without saying goodbye – for example on a power cut.

mosquitto_sub -h broker.local -t 'awtrixNG/availability' -v

Home Assistant discovery uses this same topic (avty_t) for every entity. An automation that watches <P>/availability keeps working after you turn on haDiscovery – the topic stays the same.

After a failed connection AWTRIX tries again after 5 s, then 10, 20, 40, and then every 60 s. Each wait is up to 20 % shorter at random. After a successful connection the waits start again at 5 s.

Whether AWTRIX is connected, and why not, is reported at GET /api/v1/device under mqtt and in the web UI under System → MQTT.

Home Assistant discovery¶

Published when haDiscovery is on. There are no extra topics for Home Assistant – every entity uses the <P>/cmd/... and <P>/state/... topics above, with the same checks and the same /result answers. Automations you built with plain MQTT keep working when you turn discovery on.

One document, one topic¶

This is Home Assistant's device discovery format: one retained message with dev (the device), o (the origin) and cmps (all entities). It needs Home Assistant 2024.11 or newer.

• <uid> – the 12-character lowercase MAC address, also the Home Assistant device ID.
• Each entity's uniq_id is <uid>_<key>, where <key> is its cmps key (mat, ind1, rssi, …).
• Every entity in cmps has its own "~":"<P>", so its topics are written ~/cmd/display, ~/state/device and so on.
• Keys use the standard Home Assistant short forms: p, stat_t, cmd_t, val_tpl, cmd_tpl, bri_cmd_t, rgb_stat_t, avty_t, uniq_id.
• Entity types used: light, select, button, switch, sensor, binary_sensor.

When you turn haDiscovery off, AWTRIX publishes an empty retained message to the same topic. This tells Home Assistant to remove the device.

Device block¶

Under the dev key.

Entity set¶

19 entities are always created, plus more for the hardware your clock has. The cmps key is also the end of the uniq_id. The Reads / writes column shows the topic each entity uses; all of them are described above.

These entities are created only when the hardware is there, so none of them stays at unknown forever. <P>/state/device follows the same rule and leaves those fields out.

A clock with a battery pin, a light sensor and a temperature/humidity sensor has 26 entities without the sound entities. A clock with none of this hardware has only the 19 base entities.

Version, IP address, MQTT prefix, WiFi strength, Uptime, Free RAM and Battery voltage are marked entity_category: diagnostic, so Home Assistant shows them under diagnostics, not on the main device card.

The button binary_sensors use the <P>/state/buttons/... topics. They are 1 while a button is held and 0 when it is released, so you can use them as automation triggers. After Home Assistant restarts they show unknown until the next press or until AWTRIX reconnects.

What the entities write¶

• Matrix – state writes power: turns the display on and off. (Shown as matrixPower in device state.)
• Matrix – brightness writes brightness. This does nothing while autoBrightness is on and the clock has a light sensor. The slider shows the brightness the display really uses, so with auto-brightness on it moves with the room light. Set Brightness mode to Manual to control the display with the slider.
• Matrix – RGB writes textColor, the default text color – it does not tint the display.
• Indicator n writes indicators[n]. The switch turns it on in white; use the color picker for other colors. There is no "on with the last color" command. Both stop blinking and fading. blinkMs and fadeMs can only be set with <P>/cmd/indicators/<id>.

Entity states come from the state topics. A change made over HTTP or <P>/cmd/... reaches Home Assistant the next time that state topic is published:

• Display power and the three indicators are in state/device, which is then published within 250 ms – faster changes are combined into one message.
• Everything else in state/device, brightness included, waits for the next statsInterval.
• Settings entities (Brightness mode, Transition effect, Transition, the four volumes and the Matrix RGB color) are in state/settings, which is published right after every change.
• Current app is in state/apps/active, published as soon as the app changes.

Related¶

• HTTP API – the same commands over HTTP
• App & notification payload – what goes into notify and apps/pushed
• Device state – the content of state/device
• Home Assistant
• Errors