System configuration¶

GET/PUT /api/v1/system is the system configuration of AWTRIX: Wi-Fi, MQTT and Home Assistant, NTP and timezone, identity, web port and authentication, sensor and battery calibration, the auto-brightness range, panel layout, and the complete runtime GPIO map.

It is 67 flat fields, one JSON object, no nesting. This page documents every one of them.

Settings is a different resource: it controls how the display behaves - brightness, apps, transitions - and is written with PATCH /api/v1/settings. How your panel is built and wired belongs here.

Most system fields are read once at boot. Reboot after changing them: curl -X POST http://<awtrix-ip>/api/v1/device/reboot. The "reboot" column in every table below says which fields are the exception.

Read the whole configuration¶

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

Returns 200 with the full configuration as a flat JSON object, keyed by the field names in this page:

{
  "wifiSsid": "MyNetwork",
  "netStatic": false,
  "mqttHost": "192.168.1.10",
  "mqttPort": 1883,
  "hostname": "kitchen-clock",
  "webPort": 80,
  "minBrightness": 10,
  "maxBrightness": 220,
  "pinMatrix": 32
}

wifiPass, mqttPass and authPass are secrets and are omitted from a plain GET. Add the secrets query parameter - GET /api/v1/system?secrets=1 - to get their stored values back as well; that is how the web UI's backup export writes an archive you can restore from. The parameter is ignored while AWTRIX is in provisioning AP mode, where the open access point would otherwise hand the credentials to anyone in range. A PUT response never includes them.

Write a configuration¶

PUT accepts a partial object. Send only the keys you want to change; absent keys keep their stored value, and unknown keys are ignored without 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 resulting configuration (same shape as GET, secrets still omitted). The write is persisted immediately.

A rejected write changes nothing. The statuses this route answers and every validation message it produces are in Errors - PUT /api/v1/system and Errors - GPIO validation.

The Content-Type header is mandatory on every PUT.

What PUT checks¶

Every numeric field is type- and range-checked before anything is stored. A bad value is rejected with 422 validationFailed naming the offending field, exactly like 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" } }

Each field's accepted range is the "Range" column of its own table below. Every pin* field takes -1 (disabled) or a GPIO within the chip's range - 0–39 on the ESP32, 0–48 (22–25 do not exist) on the ESP32-S3; see GPIO & boards.

Integer fields also reject a non-integer ({"mqttPort":"eighty"} and {"tempDecimals":1.5} both fail with 422); the float fields accept any number in range.

What PUT does not check¶

Beyond the numeric ranges, the two enums (panelStart, panelWiring), the dotted-quad address fields and the blanking rules below, strings are not validated, and unknown keys are ignored without error - the resource is a merge, not a replacement. The deeper GPIO rules (duplicates, input-only pins, the matrix whitelist) are separate and answer 400 invalidPinConfig; the rules and their exact messages are in GPIO & boards.

Switches, blank fields and secrets¶

Each of the two optional subsystems has its own boolean gate: mqttEnabled runs the MQTT client, authEnabled requires HTTP Basic auth. The subsystem runs only while its flag is true; turning it off keeps the stored host / username / password, so re-enabling needs no retyping. The switch, not the emptiness of a field, decides whether the subsystem runs, so mqttHost and authUser can be blanked freely.

A gate may only be armed when it has what it needs, checked with 422 validationFailed:

One string is load-bearing: wifiSsid. A blank SSID is the "no network → AP mode" signal, so PUT refuses to blank it (422, field: wifiSsid) and points at POST /api/v1/device/factory-reset.

The three secret fields ignore a blank value and leave the stored secret intact, so a PUT can set or change a password but never clear one. To disable a subsystem, flip its gate off; to wipe stored secrets entirely, use POST /api/v1/device/factory-reset.

Nothing on the wire tells you a reboot is needed, and the web UI's "reboot required" banner is unconditional - it appears after any successful save, including changes to fields that apply live. 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"}'

Static addressing 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"}'

The /24 suffix names the mask; "ip":"192.168.1.50","subnet":"255.255.255.0" is the same request in longhand.

Wi-Fi station tuning is not configurable. Modem power-saving is always off, channels 12 and 13 are usable, and a dropped link is checked every 5 s and reconnected.

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, flip the gate and reboot for it to take effect - the host, port, prefix and credentials stay stored, so switching it back on later needs no retyping:

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 needs no setting of its own: the changeover dates are the M rules inside the POSIX string.

Writing tz alone is fine - the web UI falls back to naming the first zone that runs on the rule it finds. Writing tzName alone changes nothing about the clock. The web UI's timezone picker writes both together.

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

Auth takes effect on the very next request - including the response to this PUT. To turn it back off, flip the gate. The route sits behind the auth check itself, so this needs the credentials that are currently set; the stored username and password survive:

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

Sensor calibration¶

I²C sensors are auto-detected at boot (BME280, BMP280, HTU21DF, SHT31) - only the pins are configurable, not the sensor type.

Calibrating the battery divider: read batteryPinMillivolts from GET /api/v1/device with a full cell, then ratio = 4.2 / (batteryPinMillivolts / 1000). The default 1.79 suits a stock Ulanzi TC001.

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

Battery percent is read off the cell voltage against a resting Li-Ion discharge curve, not a linear map. The curve is in Power & battery.

Auto-brightness¶

These six fields shape auto-brightness. They are consulted only when autoBrightness is enabled in Settings; otherwise the panel uses the brightness setting directly. All six apply live, on the 100 ms light-sensor tick - no reboot.

lightLevel is a relative 0–100 measure, 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 and maxBrightness are range-checked individually (0–255), and the relationship is checked as well - on the merged configuration, so a partial write that sets only one of the two is caught too. Equal values are allowed and give a fixed brightness.

{ "error": { "code": "validationFailed",
             "message": "must not be greater than maxBrightness",
             "field": "minBrightness" } }

On a board with no light sensor (pinLdr: -1) the reading looks exactly like a pitch-dark room, so with autoBrightness on the panel sits at minBrightness and never moves. Turn autoBrightness off and set brightness yourself instead. GET /api/v1/device omits lightLevel and ldrRaw entirely on such a board, so there is no reading to check.

See Brightness & sensors.

Panel and orientation¶

Your matrix is described as panels: how wide one panel is, how many of them the data cable runs through, where that cable enters, and how the strip is laid out inside a panel. The total width follows from the first two - panelWidth × panels - and the height is always 8 pixels.

panelStart, panelWiring and panelSerpentine describe how a panel is wired; panelChainReverse and panelChainSerpentine describe how the panels are chained; mirror and rotate describe how the picture is drawn on the result. They compose - the display transform is applied first, then the chain order, then the wiring map inside a panel. Only rotate moves the buttons; a panelStart of bottomRight is a statement about the cable, not about the image. On a single-panel device the two chain keys cannot change anything.

Wiring is re-applied on the next frame, so you can try a setting and look at the panel. The one exception is the total width, which is fixed at boot: a change to panelWidth × panels needs POST /api/v1/device/reboot.

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 comes out scrambled, the wiring keys are what to try: panelSerpentine first, then panelStart, then panelWiring. If those leave each panel correct but the panels in the wrong order, or every second panel upside down, reach for panelChainReverse and panelChainSerpentine. The web UI's Panel section shows the resulting size (32 × 8 = 256 LEDs) while you edit.

Buttons¶

buttonCallback lets the buttons trigger something in your house - a lamp, a scene, a Node-RED flow. Set it to the URL of your listener and AWTRIX sends it a POST with Content-Type: application/x-www-form-urlencoded and this body:

button=<left|middle|right>&state=<1|0>&uid=<mac>

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

What to expect from it:

• One press is two calls - state=1 when the button goes down, state=0 when it is released. Act on state=1 and ignore the other, or measure the gap to detect a hold.
• The buttons keep their normal job. The webhook runs alongside app switching; use blockNavigation if left/right should only drive your automation.
• middle, not select - MQTT and scripts use select for the same button. The names follow the wiring: swapButtons and rotate do not rename them.
• Plain http:// only, no TLS and no auth header, so keep the listener on your own network. An https:// URL sends nothing at all.
• Fire and forget - the response is ignored, redirects are not followed and nothing is retried. Answer immediately: timeouts are 300 ms each and the request runs on the display task, so a dead host costs up to about 0.6 s of stutter per edge.
• uid is this panel's MAC, so several panels can share one endpoint.

With a broker running you may not need it at all - state/buttons/<button> carries the same edges, retained, and Home Assistant discovers them on its own.

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

Sound hardware¶

The flag is what keeps two GPIOs free on every board that has no module: the ESP32 defaults name pinDfRx and pinDfTx whether or not one is attached.

See Sound.

Art-Net¶

An optional network listener, off by default. With the flag off no extra port is open.

The universe and pixel mapping, the five-second hold window and the security implications are in Art-Net.

Miscellaneous¶

scriptLimit is a count, not the on/off switch - that is scriptingEnabled. Behind the count there is also a memory ceiling, listed in Limits: once the resident scripts reach it a new install is refused, and nothing already running is thrown out. Read freeHeapBytes and largestFreeBlockBytes from GET /api/v1/device before raising the limit.

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

Colour control is not on this route: colorCorrection and colorTint live on Settings.

GPIO map¶

PUT /api/v1/system also carries the fourteen int GPIO fields (pinMatrix, pinBtnLeft, pinBtnSelect, pinBtnRight, pinBattery, pinLdr, pinBuzzer, pinI2cSda, pinI2cScl, pinDfRx, pinDfTx, pinI2sBclk, pinI2sLrclk, pinI2sDout). -1 disables a feature (except pinMatrix, which cannot be disabled), and every change requires a reboot.

The map is validated against the fully merged configuration, so a partial PUT is checked against the stored rest. A rejection answers 400 invalidPinConfig and names the offending field before anything is persisted. An invalid map found at boot falls back to the compiled defaults.

The per-chip field table, defaults, the list of pins the matrix driver accepts, the validation rules in order with their exact error strings, and the AWTRIX 2 SDA-collision fix are all written out once in GPIO & boards - that page is the one to read on GPIO, for both the ESP32 and the ESP32-S3.

Wi-Fi scan¶

GET /api/v1/system/wifi-scan - an asynchronous scan, used by the provisioning UI.

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

The first call starts a scan and returns 202; poll until you get 200.

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

enc is a boolean (encrypted or open), not an auth-mode number. Results are discarded after being served, so the next request starts a fresh scan.

Persistence and resets¶

Every PUT is persisted at once; nothing is batched or deferred. Each field is stored on its own, and a field that has never been written keeps its built-in default, so a firmware upgrade that adds a field does not disturb existing configuration.

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

Factory reset is available over HTTP only. Reboot, sleep and a settings reset can also be sent over MQTT.

The panel wiring is system configuration, so a settings reset leaves it alone; only a factory reset returns it to the defaults.

Coming from an AWTRIX 3 device¶

Nothing is imported. Set AWTRIX up through the web UI or PUT /api/v1/system as you would a new one.

Battery calibration in particular does not carry over: AWTRIX 3's min_battery/max_battery are raw-ADC limits, and battery percent here is derived from cell voltage, calibrated with batteryDividerRatio - see Sensor calibration.