Device state¶

GET /api/v1/device is the read-only status snapshot of AWTRIX: firmware version, identity, network, memory, display state, sensors, battery and the indicator slots. It is the endpoint the web UI dashboard polls, and the one to poll from an automation.

Every value is live: nothing here is persisted, there is no caching and no ETag, and everything resets on reboot.

Endpoint¶

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

With auth enabled:

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

Any method other than GET on this path is rejected with 405 methodNotAllowed:

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

Response shape¶

Keys are emitted in a fixed order. 21 fields are always present; up to 11 more appear only when the hardware supports them.

{
  "version": "1.0.12",
  "uid": "a4cf12ab34cd",
  "boardType": "awtrixng",
  "soc": "esp32",
  "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
  }
}

Always-present fields¶

These 22 keys are in every response, on every board, in every state.

PSRAM fields (conditional)¶

Present only when the board has external PSRAM. Both fields appear together, or not at all.

Light sensor fields (conditional)¶

Present only when the board has a light sensor pin - that is, when pinLdr in the system configuration is >= 0. The default (ESP32 wiring) is GPIO 35, so on a stock device both fields are present. Set pinLdr to -1 and both disappear from the response.

lightLevel rises linearly with ldrRaw, so calibrate it there: ldrFactor sets what counts as full light, and ldrOnGround accounts for a sensor wired the other way round. ldrGamma shapes only the step from lightLevel to brightness; it never changes lightLevel, which is reported whether or not autoBrightness is switched on.

Battery fields (conditional)¶

Present only when the board has a battery pin - that is, when pinBattery in the system configuration is >= 0. The default (ESP32 wiring) is GPIO 34, so on a stock device these four fields are present. Set pinBattery to -1 and all four disappear from the response.

The first three come from the same reading: pin millivolts → cell volts → percent; lowBattery is a flag derived from that percent.

Calibrate the divider, not the percentage. On a stock Ulanzi TC001 a full cell reads roughly 2347 mV at the pin, which the default ratio of 1.79 turns into ≈ 4.20 V at the cell. If your batteryVoltage looks wrong, read batteryPinMillivolts on a known-full cell and set batteryDividerRatio = 4.2 / (batteryPinMillivolts / 1000). See Power & battery.

batteryPercent is a charge estimate from voltage alone. There is no fuel gauge in the hardware, so it cannot give you a runtime estimate, and it will move under load as the cell sags.

Environment fields (conditional)¶

Present only when an I²C environment sensor was detected at boot. Detection happens once during startup, in probe order: BME280, then BMP280, then HTU21DF, then SHT31. If none answers - or if pinI2cSda / pinI2cScl is -1, which disables I²C entirely - all three keys are omitted, and plugging a sensor in later does nothing until you reboot.

Which keys appear is gated by what the detected sensor can measure. A field is never emitted with a phantom 0.

Indicators¶

indicators is always an array of exactly 3 objects, one per slot, index 0 → indicator 1, index 2 → indicator 3. It reflects whatever was last written via PUT /api/v1/indicators/{id} (or over MQTT / Home Assistant), and it matches what is on screen: the slots paint as pixels down the panel's right edge, slot 1 at the top and slot 3 at the bottom.

Connection dots¶

The right edge belongs to your indicators. The left edge belongs to AWTRIX, which lights a single pulsing pixel there while a connection it should have is missing:

The dots appear on their own, cannot be switched off, and disappear the moment the connection is back.

Only one lights at a time. Without WiFi there is no MQTT either, so a network outage shows the red dot alone - a lit dot always points at one thing to fix. A device with no broker configured never shows the yellow dot at all.

You will not see the dots while the panel is off, on the setup screen, in mood light, or while an Art-Net stream is running. For the reason behind an outage, read wifi and mqtt below.

Connection status¶

wifi and mqtt report whether AWTRIX reached your network and your broker, and if not, why. Both objects have the same shape, and mqtt drives the Connection line on the web UI's MQTT tab. AWTRIX also shows an outage on the panel itself - 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¶

A failed connection is retried after 5 seconds, then 10, 20, 40, and at most every 60 seconds, each delay shortened by up to 20 % so a rebooting broker does not get every device knocking in lockstep. A successful connection resets the schedule. retryInMs counts down to the next attempt.

The broker's address is looked up once and kept for as long as it works. It is looked up again after three consecutive failures against the same address, and after AWTRIX rejoins WiFi.

Also published over MQTT¶

The same JSON document is published, retained, to <prefix>/state/device. Because it is retained, a subscriber gets the last snapshot immediately on connect, which is cheaper than HTTP polling. See MQTT topics for the publish cadence and the rest of the state topics.

How often the values update¶

The values in this response are refreshed on their own schedules, not at request time. Polling faster than these intervals returns repeated values.

In the simulator¶

The native simulator serves GET /api/v1/device with the same key set, with a few differences worth knowing if you develop against it: boardType is "simulator", and the battery fields (including lowBattery) plus temperature and humidity are always present, because the simulated board always reports a battery and a temperature+humidity sensor. The simulated sensor is not a barometer, so pressureHpa is absent in the simulator - the one environment field you cannot exercise there. Do not use the simulator to test how your client handles missing fields - point it at a device with pinBattery set to -1 instead. See Simulator.

Related¶

• HTTP API v1 - 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 LDR
• Power & battery - calibrating the divider ratio
• Errors - what a failing request answers