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": "awtrixng",
  "soc": "esp32",
  "updateImage": "firmware-awtrix-ng.bin",
  "ipAddress": "192.168.1.42",
  "hostname": "awtrixng-ab34cd",
  "wifiRssi": -58,
  "uptimeSeconds": 4213,
  "freeHeapBytes": 118234,
  "minFreeHeapBytes": 91560,
  "largestFreeBlockBytes": 63488,
  "scriptingRunning": true,
  "scriptHeapPool": "internal",
  "scriptHeapBudgetBytes": 98304,
  "resetReason": "software",
  "fps": 41,
  "brightness": 120,
  "lightLevel": 29.3,
  "ldrRaw": 1200,
  "batteryPercent": 88,
  "batteryVoltage": 4.1,
  "batteryPinMillivolts": 2290,
  "lowBattery": false,
  "temperature": 21.5,
  "humidity": 42,
  "pressureHpa": 1013.2,
  "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": 32,
    "sourceHeight": 8
  }
}

Always-present fields¶

These keys are in every response.

PSRAM fields (conditional)¶

Only on boards with PSRAM (extra memory). Both keys appear together or not at all.

Light sensor fields (conditional)¶

Only when the board has a light sensor pin – pinLdr in the system configuration is 0 or higher. The default is GPIO 35, so a stock clock has both keys. With pinLdr: -1 both keys disappear.

lightLevel follows ldrRaw in a straight line. ldrFactor sets what counts as full light, and ldrOnGround handles a sensor wired the other way round. ldrGamma changes only how lightLevel turns into brightness, never lightLevel itself. lightLevel is reported whether autoBrightness is on or off.

Battery fields (conditional)¶

Only when the board has a battery pin – pinBattery in the system configuration is 0 or higher. The default is GPIO 34, so a stock clock has all four keys. With pinBattery: -1 all four disappear.

Calibrate the divider, not the percentage. On a stock Ulanzi TC001 a full battery reads about 2347 mV at the pin. The default ratio of 1.79 turns this into about 4.20 V. If batteryVoltage looks wrong, read batteryPinMillivolts with a fully charged battery and set batteryDividerRatio = 4.2 / (batteryPinMillivolts / 1000). See Power & battery.

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

Environment fields (conditional)¶

Only when a temperature sensor was found at startup. AWTRIX looks for BME280, then BMP280, then HTU21DF, then SHT31. If none answers – or if pinI2cSda / pinI2cScl is -1 – all three keys are left out. A sensor you connect later is found only after a restart.

Only the values the sensor can measure appear:

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, in mood light, or while an Art-Net stream is running. 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": "esp32" },
  "sensors": { "light": true },
  "display": { "width": 32, "height": 8, "configurable": true }
}

Related¶

• HTTP API – conventions, auth, and the full route list
• System configuration – pinBattery, pinLdr, batteryDividerRatio, lowBatteryThreshold, ldrFactor, ldrGamma, minBrightness, maxBrightness, tempOffset, humOffset
• Settings – brightness, autoBrightness and the rest of the user settings
• Brightness & sensors – calibrating the light sensor
• Power & battery – calibrating the divider ratio
• Errors – what a failing request answers