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, web port and login, sensor and battery calibration, the auto-brightness range, the panel layout and the pin map. 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. How your clock is built and wired belongs here.

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",
  "webPort": 80,
  "minBrightness": 10,
  "maxBrightness": 220,
  "pinMatrix": 21
}

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 and Errors – GPIO validation.

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. Every pin* field takes -1 (not connected) or a GPIO of the chip, 0–48. GPIO 22–25 do not exist. See GPIO & boards.

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 three name fields (panelStart, panelWiring, panelColorOrder), the IP address fields and the rules in the next section, text fields are not checked. Unknown keys are ignored. The pin rules (no duplicates, reserved pins, the LED matrix list) are checked separately and answer 400 invalidPinConfig; the rules and messages are in GPIO & boards.

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.

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}'

Sensor calibration¶

AWTRIX finds the temperature sensor by itself at startup (BME280, BMP280, HTU21DF, SHT31). You only set the pins, not the sensor type.

To calibrate the battery divider, read batteryPinMillivolts from GET /api/v1/device with a fully charged battery. Then set ratio = 4.2 / (batteryPinMillivolts / 1000).

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"tempOffset":-2.5,"batteryDividerRatio":1.79}'

The battery percentage is estimated from the battery voltage using a typical Li-Ion curve, not a straight line. The curve is in Power & battery.

Auto-brightness¶

These six fields control auto-brightness. They are used only when autoBrightness is on in Settings and the device has a light sensor. Otherwise the display uses the brightness setting. All six apply at once – no restart.

lightLevel is a relative value from 0 to 100, not lux.

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"minBrightness":5,"maxBrightness":180,"ldrGamma":2.2}'

minBrightness must not be greater than maxBrightness. This is checked against the stored value too, so it also catches a write that sets only one of them. Equal values are allowed and give a fixed brightness.

{ "error": { "code": "validationFailed",
             "message": "must be <= maxBrightness",
             "field": "minBrightness" } }

Without a light sensor (pinLdr: -1) these six fields have no effect. autoBrightness is accepted, but the display uses brightness. GET /api/v1/device leaves out lightLevel and ldrRaw, and the web UI hides these fields.

See Brightness & sensors.

Panel and orientation¶

Your LED matrix is described as panels: how wide one panel is, how many panels the data cable runs through, where the cable enters, and how the LED strip runs inside a panel. The total width is panelWidth × panels. Every panel is 8 pixels high. All panels form one row, left to right, on one data pin.

The keys fall into three groups:

• panelStart, panelWiring, panelColorOrder and panelSerpentine describe the wiring inside a panel.
• panelChainReverse and panelChainSerpentine describe how the panels are connected. With a single panel they change nothing.
• mirror and rotate change how the picture is shown. Only rotate swaps the buttons; panelStart: bottomRight only describes the cable, not the picture.

Wiring changes show on the next frame. A new total width needs a restart (POST /api/v1/device/reboot).

The panel is 8 pixels high and 32–128 pixels wide, so at most 1024 LEDs. If AWTRIX cannot use the stored size at startup, it shows 32×8 instead and keeps your stored values. If even that fails, the panel stays dark, but the web UI and API still work.

GET /api/v1/capabilities reports the size in use (display.width / height), the saved size (requestedWidth / requestedHeight), restartRequired, ready, and the limits minWidth, maxWidth, minHeight, maxHeight and maxPixels.

Wider panels update a little less often. Sending the data to an LED chain takes about 30 µs per pixel: about 8 ms for 256 pixels and about 31 ms for 1024. The capability estimatedWireTimeUs gives this estimate for your panel (it does not include drawing time).

The wirings people actually have¶

curl -X PUT http://<awtrix-ip>/api/v1/system   -H "Content-Type: application/json"   -d '{"panelWidth":8,"panels":4,"panelSerpentine":false}'

If the picture is scrambled, try panelSerpentine first, then panelStart, then panelWiring. If each panel then looks right but the panels are in the wrong order, or every second panel is upside down, try panelChainReverse and panelChainSerpentine. The web UI's Panel section shows the resulting size (32 × 8 = 256 LEDs) while you edit.

If the picture is right but some colors are wrong, change panelColorOrder. Red and green swapped usually means an RGB panel with the default GRB order.

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.

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. Use blockNavigation if the buttons 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 and rotate do 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 waits at most 300 ms to connect and 300 ms for the answer, and the display pauses while it waits. A listener that does not answer can freeze the display for up to about 0.6 s per press or release.
• 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.

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

Sound hardware¶

The default pins set pinDfRx and pinDfTx even on boards without a DFPlayer. With dfplayer: false these two pins stay unused.

See Sound.

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.

Art-Net¶

Art-Net lets lighting software send pictures to the panel over the network. It is off by default; while it is off, no extra port is open.

Universe and pixel mapping, the five-second hold time and security notes are in Art-Net.

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.

GPIO map¶

PUT /api/v1/system also holds the sixteen pin fields (pinMatrix, pinBtnLeft, pinBtnSelect, pinBtnRight, pinBattery, pinLdr, pinBuzzer, pinI2cSda, pinI2cScl, pinDfRx, pinDfTx, pinI2sBclk, pinI2sLrclk, pinI2sDout, pinI2sMclk, pinAmpEnable). -1 means "not connected" (not allowed for pinMatrix). Every pin change needs a restart.

AWTRIX checks the pins you send together with the stored ones. A problem is answered with 400 invalidPinConfig, naming the field, and nothing is saved. If the stored map is not valid at startup, AWTRIX uses the default pins of its chip.

The pin table, defaults, the allowed LED matrix pins, all rules with their exact error messages and the AWTRIX 2 pin fix are in GPIO & boards.

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.

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.

The panel wiring is part of the system configuration, so a settings reset keeps it. Only a factory reset sets it back to the defaults.

Coming from an AWTRIX 3 device¶

Nothing is imported. Set AWTRIX up in the web UI or with PUT /api/v1/system like a new device.

Battery calibration does not carry over: AWTRIX 3's min_battery/max_battery are raw sensor limits, while AWTRIX NG calculates the battery percentage from the battery voltage, calibrated with batteryDividerRatio – see Sensor calibration.

Related¶

• GPIO & boards – every pin rule
• Settings – brightness, apps, transitions and colors
• Device state – live values such as lightLevel and batteryPinMillivolts
• MQTT topics
• Errors – PUT /api/v1/system