Skip to content

Power & battery

This page shows how to read the battery, get a low-battery warning, and switch the display off and on.

How it behaves

Switching the display off only darkens the LEDs. Wi-Fi, MQTT and the apps keep running, and AWTRIX stays reachable over HTTP. The low-battery warning stays off until you set a threshold.

Check the battery

All battery values are in the device state:

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

The battery part of the answer:

{
  "batteryVoltage": 4.1,
  "batteryPercent": 88
}
  • batteryPercent is how full the battery is.
  • batteryVoltage is the battery voltage.

The values come from the clock's battery controller. The Status app shows the battery level and whether USB power is connected.

Every field: Device state → Battery fields.

Get told when the battery is low

GET /api/v1/device always has a lowBattery value. lowBattery becomes true when batteryPercent is below lowBatteryThreshold (below, not equal). Set the threshold to a percentage under Low-battery threshold in System → Brightness & sensors of the web UI, or send:

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"lowBatteryThreshold": 15}'

{
  "batteryPercent": 12,
  "lowBattery": true
}
  • The default is 0, which turns the warning off: lowBattery stays false.
  • Below the threshold, the battery in the Status app blinks, unless USB power is connected.
  • In Home Assistant the same warning is the Low battery sensor. See Battery in Home Assistant.

Turn the display off and on

This switches the LEDs off, not the clock. Your brightness settings stay as they are.

  • On the clock, press the select (middle) button twice quickly. This is the only way to switch the display back on without the network.
  • In the web UI, use the Power switch on the Dashboard.

With the API

Off:

curl -X PATCH http://<awtrix-ip>/api/v1/display \
  -H "Content-Type: application/json" \
  -d '{"power":false}'

On:

curl -X PATCH http://<awtrix-ip>/api/v1/display \
  -H "Content-Type: application/json" \
  -d '{"power":true}'

To see the current state, read power in GET /api/v1/display or matrixPower in GET /api/v1/device. Both are false while the display is off.

Battery in Home Assistant

Home Assistant gets four battery entities automatically:

Entity Device class Unit Source
Battery battery % batteryPercent
Battery voltage voltage V batteryVoltage
Low battery battery - lowBattery
Charging battery_charging - usbPower

See Home Assistant.

Good to know

  • A double press of select does nothing while Block buttons is on. Switch the display with the Power switch or a request instead.
  • Notifications are not shown while the display is off. Add "wakeup": true to show one anyway. See Wake a dark display.
  • There is no sleep timer. POST /api/v1/device/sleep does not put this clock to sleep. It only restarts AWTRIX NG. To save power, switch the display off.

Details