System configuration¶

GET/PUT /api/v1/system holds the system configuration of AWTRIX: Wi-Fi, MQTT and Home Assistant, time server and time zone, device name and login, the battery warning, the buttons and mirroring. This page describes every field.

It is one flat JSON object without nesting.

Settings are something different: they control how the display behaves – brightness, apps, transitions – and are written with PATCH /api/v1/settings.

Most system fields take effect only after a restart: curl -X POST http://<awtrix-ip>/api/v1/device/reboot. The "Reboot" column in each table shows which fields apply at once.

Read the whole configuration¶

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

Returns 200 with the full configuration as a flat JSON object, using the field names on this page:

{
  "wifiSsid": "MyNetwork",
  "netStatic": false,
  "mqttHost": "192.168.1.10",
  "mqttPort": 1883,
  "hostname": "kitchen-clock",
  "lowBatteryThreshold": 15
}

wifiPass, mqttPass and authPass are secrets and are left out of a normal GET. Add ?secrets=1 – GET /api/v1/system?secrets=1 – to get them too. The web UI's backup export uses this so that you can restore the backup later. In setup mode any secrets query parameter is refused with 403 forbidden, because anyone nearby can join the open setup hotspot. A PUT answer never contains the secrets.

Write a configuration¶

PUT takes only the keys you want to change. Keys you leave out keep their stored value. Unknown keys are ignored without an error.

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"mqttHost":"192.168.1.10","mqttPort":1883,"mqttUser":"awtrix"}'

Returns 200 with the new configuration (same as GET, without secrets). The change is saved at once.

A rejected write changes nothing. All answers and error messages of this route are in Errors – PUT /api/v1/system.

Always send Content-Type: application/json. Without it, curl -d marks the body as a form, and AWTRIX refuses the PUT with 415 (Content-Type).

What PUT checks¶

AWTRIX checks the type and range of every number before it stores anything. A wrong value is rejected with 422 validationFailed, and field names the key – the same as with PATCH /api/v1/settings.

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

{ "error": { "code": "validationFailed", "message": "out of range", "field": "webPort" } }

The allowed range of each field is in the "Range" column of its table.

Whole-number fields also reject other values ({"mqttPort":"eighty"} and {"tempDecimals":1.5} both fail with 422). Decimal fields accept any number in range.

What PUT does not check¶

Apart from the number ranges, the IP address fields, mqttTlsPin and the rules in the next section, text fields are not checked. Unknown keys are ignored.

Switches, blank fields and secrets¶

MQTT and the login each have an on/off switch: mqttEnabled for MQTT, authEnabled for the login. The feature runs only while its switch is true. Switching it off keeps host, user name and password, so you do not need to type them again later. Because the switch decides, you can leave mqttHost and authUser empty whenever you like.

You can switch a feature on only when it has what it needs. Otherwise you get 422 validationFailed:

wifiSsid cannot be emptied with PUT (422, field: wifiSsid), because an empty network name sends AWTRIX into setup mode. The error points you to POST /api/v1/device/factory-reset.

An empty value for one of the three secrets is ignored and the stored secret stays. So a PUT can set or change a password, but never delete one. To stop using a feature, switch it off. To delete all stored secrets, use POST /api/v1/device/factory-reset.

The API does not tell you when a restart is needed. The web UI shows its "reboot required" note after every save, even for fields that apply at once. Use the "Reboot" column in the tables below.

Keys without effect¶

GET also returns these keys. You can write them, and they are checked and stored, but they change nothing on this clock:

• webPort: the web server always uses port 80.
• tempOffset, humOffset and batteryDividerRatio: the clock has no temperature sensor and measures its battery itself.
• minBrightness, maxBrightness, ldrFactor, ldrGamma, ldrOnGround and brightnessSmoothing: see Auto-brightness.
• dfplayer, artnet and tempDecimals.

There are no panel or pin keys. A PUT or a restored backup ignores such keys like any unknown key. See Panel.

Wi-Fi¶

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"wifiSsid":"MyNetwork","wifiPass":"secret123"}'

A fixed address needs netStatic and ip together:

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"netStatic":true,"ip":"192.168.1.50/24","gateway":"192.168.1.1"}'

/24 is the mask; "ip":"192.168.1.50","subnet":"255.255.255.0" means the same.

Other Wi-Fi details cannot be changed: power saving is always off, channels 12 and 13 work, and AWTRIX checks the connection every 5 s and reconnects if it dropped.

MQTT and Home Assistant¶

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"mqttEnabled":true,"mqttHost":"192.168.1.10","mqttPort":1883,"mqttPrefix":"awtrix","haDiscovery":true}'

To turn MQTT off, set the switch and restart. Host, port, prefix and login stay stored, so you can switch it on again later without typing them again:

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

See MQTT topics and Home Assistant.

Time¶

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"tz":"EST5EDT,M3.2.0,M11.1.0","tzName":"America/New_York","ntpServer":"time.cloudflare.com"}'

Daylight saving time needs no extra setting: the change dates are the M rules in the POSIX string.

You can write tz alone – the web UI then shows the first zone that uses this rule. Writing tzName alone does not change the time. The web UI's time zone picker writes both.

Identity, web server and authentication¶

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"hostname":"kitchen-clock","authEnabled":true,"authUser":"admin","authPass":"hunter2"}'

The login applies from the next request on – including the answer to this PUT. To switch it off again, send the current login with the request. User name and password stay stored:

curl -u admin:hunter2 -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"authEnabled":false}'

Battery warning¶

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

The clock measures its battery by itself. See Power & battery.

Auto-brightness¶

The clock has no light sensor. autoBrightness is accepted, but the display always uses the brightness setting. minBrightness, maxBrightness, ldrFactor, ldrGamma, ldrOnGround and brightnessSmoothing are checked and stored, but change nothing. minBrightness must still not be greater than maxBrightness.

Panel¶

The panel is 52 × 16 pixels and cannot be changed. There are no panel or pin keys: GET /api/v1/capabilities reports the size with configurable: false.

Buttons¶

With buttonCallback the buttons can control something in your home – a lamp, a scene, a Node-RED flow. Set it to the URL of your listener. AWTRIX sends a POST with Content-Type: application/json and this body:

{"button":"left","state":true,"uid":"dcda0c29dcb8"}

button is left, middle or right. state is true when the button goes down and false when it is released. uid is the device ID from GET /api/v1/device.

The knob reports too. Pushing it sends "button":"knob" with state, like a button. Turning it sends turn instead of state: the number of clicks, positive clockwise, negative counterclockwise.

{"button":"knob","turn":2,"uid":"dcda0c29dcb8"}

Clicks that come faster than your listener answers are added up into one call, so a quick turn sends one call with a larger turn, not one per click.

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

Good to know:

• One press means two calls – "state":true when pressed, "state":false when released. React to true and ignore the other, or measure the time between them to detect a long press.
• The buttons keep working normally. They still switch apps, and the knob still sets brightness and volume. Use blockNavigation if the buttons and the knob should only control your automation, or a script that returns true from on_button() to handle presses on its own screen.
• middle, not select – MQTT and scripts call the same button select. The names follow the wiring: swapButtons does not rename them.
• Only http://, no https:// and no login, so keep the listener in your home network. An https:// URL sends nothing.
• No answer needed – AWTRIX ignores the answer, does not follow redirects and does not retry.
• Answer quickly. AWTRIX calls in the background, so the display never waits. It gives up after 1 s to connect and 2 s for the answer. While your listener is slow, AWTRIX keeps up to 16 calls waiting and drops further presses.
• uid is the clock's MAC address, so several clocks can share one listener.

With MQTT you may not need this at all – state/buttons/<button> reports the same presses, and Home Assistant finds them by itself. event/knob reports the knob turns.

The debounce time and the double-press time are fixed and cannot be changed.

Mirroring¶

Shows the display of one clock on other clocks with a panel of the same size. The port for it, UDP 4212, is open only while mirrorShare is on or mirrorFrom names a clock. All six keys apply at once.

What a mirroring clock shows, and the state in GET /api/v1/device, are described in Mirroring.

Miscellaneous¶

Install, read and remove scripts with /api/v1/apps/script/{name}; the script language is described in the Scripting guide.

The color settings colorCorrection and colorTint are in Settings, not here.

Wi-Fi scan¶

GET /api/v1/system/wifi-scan searches for Wi-Fi networks.

curl http://<awtrix-ip>/api/v1/system/wifi-scan

The first call starts a search and answers 202. Ask again until you get 200.

[
  { "ssid": "MyNetwork", "rssi": -52, "enc": true },
  { "ssid": "GuestWiFi", "rssi": -78, "enc": false }
]

enc is true for a network with a password and false for an open one. After the list has been returned once, it is gone; the next request starts a new search.

Searching does not work while the setup hotspot is open (503 scanUnavailable). Type the network name by hand. Searching works once the clock is connected to a network.

Persistence and resets¶

Every PUT is saved at once. A field you have never written keeps its default, so a firmware update that adds a new field does not change your existing configuration.

curl -X POST http://<awtrix-ip>/api/v1/device/factory-reset

Factory reset works only over HTTP. Restart, sleep and settings reset also work over MQTT.

Related¶

• Settings – brightness, apps, transitions and colors
• Device state – live values such as batteryPercent and lowBattery
• MQTT topics
• Errors – PUT /api/v1/system