Device state¶

GET /api/v1/device tells you how AWTRIX is doing right now: firmware version, network, memory, display, sensors, battery and the indicators. The web UI dashboard reads it, and you can read it from your own automations.

All values are live. They are not stored and they reset when AWTRIX restarts.

Endpoint¶

curl http://<awtrix-ip>/api/v1/device

With a password set:

curl -u admin:secret http://<awtrix-ip>/api/v1/device

Any method other than GET gets 405 methodNotAllowed:

curl -i -X POST http://<awtrix-ip>/api/v1/device
# HTTP/1.1 405 Method Not Allowed
# {"error":{"code":"methodNotAllowed","message":"allowed: GET"}}

Response shape¶

An example. The tables below explain every key.

{
  "version": "1.0.12",
  "uid": "a4cf12ab34cd",
  "boardType": "tc002",
  "soc": "armv7l",
  "updateImage": "awtrix-ng-tc002.awup",
  "ipAddress": "192.168.1.42",
  "hostname": "awtrixng-ab34cd",
  "wifiRssi": -58,
  "uptimeSeconds": 4213,
  "freeHeapBytes": 61423616,
  "minFreeHeapBytes": 60817408,
  "scriptingRunning": true,
  "scriptHeapPool": "system",
  "scriptHeapBudgetBytes": 4194304,
  "resetReason": "software",
  "fps": 41,
  "brightness": 120,
  "batteryPercent": 88,
  "batteryVoltage": 4.1,
  "lowBattery": false,
  "matrixPower": true,
  "currentApp": "Time",
  "indicators": [
    {"on": false, "color": "#000000", "blinkMs": 0, "fadeMs": 0},
    {"on": false, "color": "#000000", "blinkMs": 0, "fadeMs": 0},
    {"on": false, "color": "#000000", "blinkMs": 0, "fadeMs": 0}
  ],
  "messageCount": 0,
  "wifi": {
    "enabled": true,
    "state": "connected",
    "host": "MyNetwork",
    "endpoint": "192.168.1.31",
    "attempts": 0,
    "retryInMs": 0,
    "connects": 1,
    "error": null,
    "lastError": null
  },
  "mqtt": {
    "enabled": true,
    "state": "connected",
    "host": "broker.local",
    "endpoint": "192.168.1.42:1883",
    "attempts": 0,
    "retryInMs": 0,
    "connects": 1,
    "error": null,
    "lastError": null
  },
  "mirror": {
    "sharing": false,
    "viewers": 0,
    "source": "kitchen.local",
    "state": "showing",
    "sourceWidth": 52,
    "sourceHeight": 16
  },
  "usbPower": true,
  "update": {"state": "idle", "release": "", "error": ""}
}

Always-present fields¶

These keys are in every response.

Battery fields (conditional)¶

The clock measures the battery itself. batteryPercent, batteryVoltage and lowBattery appear once it reports a value.

batteryPercent is only an estimate from the voltage. It cannot tell you the remaining runtime, and it drops a little under load.

Update fields (conditional)¶

The clock installs .awup update packages. See Updating.

update.state is one of:

• idle – no update is running.
• applying – a package is being installed and the clock restarts.
• boot-pending – the new release has started and is being checked.
• confirmed – the new release works.
• failed – the new release did not start properly, or the installation was interrupted.

update.release names the release, and update.error says what went wrong.

Indicators¶

indicators always holds 3 objects: index 0 is indicator 1, index 2 is indicator 3. It shows what was last set with PUT /api/v1/indicators/{id} (or over MQTT / Home Assistant), which is also what you see on the display: dots on the right edge, indicator 1 at the top, indicator 3 at the bottom.

Connection dots¶

The right edge of the display is for your indicators. The left edge is for AWTRIX: it shows a single pulsing dot there while a connection is missing.

The dots appear by themselves, cannot be switched off, and go away as soon as the connection is back.

Only one dot shows at a time. Without Wi-Fi there is no MQTT either, so a network outage shows only the red dot. If no broker is set up, the yellow dot never shows.

You do not see the dots while the display is off, on the setup screen or in mood light. To find out why a connection is down, read wifi and mqtt below.

Connection status¶

wifi and mqtt tell you whether AWTRIX reached your network and your broker, and if not, why. Both objects have the same keys. mqtt also feeds the Connection line on the web UI's MQTT tab. For the dots on the display see Connection dots.

"mqtt": {
  "enabled": true,
  "state": "offline",
  "host": "broker.local",
  "endpoint": "",
  "attempts": 4,
  "retryInMs": 40000,
  "connects": 0,
  "error": "hostNotFound",
  "lastError": "hostNotFound"
}

What each error means¶

Retries back off¶

After a failed attempt AWTRIX waits 5 seconds, then 10, 20, 40, and then 60 seconds between attempts. Each wait is up to 20 % shorter at random, so many clocks do not all retry at the same moment. After a successful connection the waits start again at 5 seconds. retryInMs counts down to the next attempt.

AWTRIX looks up the broker's address once and keeps it while it works. It looks it up again after three failed attempts in a row, and after it rejoins Wi-Fi.

Mirroring status¶

mirror tells you what mirroring is doing. It feeds the State line in the web UI's Mirroring section.

Also published over MQTT¶

The same JSON is published, retained, to <prefix>/state/device. A subscriber gets the latest state as soon as it connects, so you do not need to poll over HTTP. See MQTT topics for how often it is sent and for the other state topics.

How often the values update¶

The values are updated on their own schedule, not when you ask. Asking more often than this returns the same values.

Platform capabilities¶

Tools that support several device types can read GET /api/v1/capabilities to find out what the device offers. Part of the answer describes the platform:

{
  "platform": { "id": "tc002" },
  "sensors": { "light": false },
  "display": { "width": 52, "height": 16, "configurable": false },
  "gpio": null
}

Related¶

• HTTP API – conventions, auth, and the full route list
• System configuration – lowBatteryThreshold
• Settings – brightness, autoBrightness and the rest of the user settings
• Power & battery – the battery and the low-battery warning
• Errors – what a failing request answers