Coming from AWTRIX 3¶

This page helps you move your AWTRIX 3 automations to AWTRIX NG.

On AWTRIX 3 you pushed custom apps. In AWTRIX NG they are called pushed apps. The idea is the same: your automation sends a JSON object, and AWTRIX adds it to the rotation as an app and shows it until you update or remove it. What differs is the address you send to, the names of the keys, and how strictly the payload is checked.

Three changes cover almost everything:

1. New endpoint. POST /api/custom?name=x became PUT /api/v1/apps/pushed/x.
2. New key names. Everything is camelCase, durations are milliseconds with an ...Ms suffix, and numeric mode switches became words: lifetimeMode: 1 is lifetimeExpiry: "mark".
3. Strict validation. AWTRIX 3 ignored keys it did not know. AWTRIX NG rejects the whole payload with 422 and names the unknown key. Your old payload will not half-work. The error tells you exactly what still needs renaming.

Convert a flow automatically¶

Paste an old flow and get it back in the NG dialect. A flow can be a Home Assistant automation or blueprint, a Node-RED or n8n export, a curl command, or a bare JSON payload. Endpoints, MQTT topics and payload keys are rewritten in place. Your comments, templates and formatting around them stay as they are. Anything that cannot be converted safely is left untouched and listed as a warning that links to the matching section below: JavaScript that builds payloads, template expressions, and keys with no NG equivalent.

Where to send¶

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/weather \
  -H "Content-Type: application/json" \
  -d '{"text":"21.5C","icon":"2422"}'

Before and after¶

The same weather app, in both dialects:

{
  "text": "21.5 C",
  "icon": "2422",
  "color": "#00AAFF",
  "duration": 8,
  "lifetime": 300,
  "lifetimeMode": 1,
  "pushIcon": 2,
  "scrollSpeed": 50
}

{
  "text": "21.5 C",
  "icon": "2422",
  "textColor": "#00AAFF",
  "durationMs": 8000,
  "lifetimeMs": 300000,
  "lifetimeExpiry": "mark",
  "iconMode": "push",
  "scroll": { "speed": 50 }
}

Same content, same icon, same behavior: every value found a new home. Colors carry over unchanged. Hex strings and [r, g, b] arrays both work (color forms).

The key map¶

Every AWTRIX 3 custom-app key, and where it went. The full definition of each new key is in App & notification payload.

Text and styling¶

Icon¶

Timing and lifetime¶

Charts and progress bar¶

Effects and overlay¶

Drawing¶

Notification-only keys¶

Persistence¶

The tricky ones, explained¶

Gradients, rainbow, blink and fade¶

AWTRIX 3 had four text stylings that excluded one another: gradient, rainbow, blinkText and fadeText. Gradient and rainbow became one key, the app palette:

{ "text": "OVERHEAT", "palette": ["#FFFF00", "#FF0000"], "textColor": "palette" }

{ "text": "PARTY", "palette": "Rainbow", "textColor": "palette" }

The palette does more than the old keys did. It can hold up to 16 stops, repeat and move along the text (paletteSpan, paletteSpeed), and the same ramp also colors charts, the progress bar and the background effect. Blink and fade stayed what they were, as textBlinkMs and textFadeMs. When both a palette and a blink or fade are set, the palette wins. The precedence table has the exact order.

Four keys became one scroll object¶

noScroll, scrollSpeed and the fixed scroll behavior are one scroll object in AWTRIX NG. It has modes AWTRIX 3 did not have: wrap, loop, bounce, direction, entry from outside the display and a hold time:

{ "text": "A LONG HEADLINE", "scroll": { "mode": "bounce", "speed": 50 } }

The two direct translations: "noScroll": true → "scroll": {"mode": "static"}, and "scrollSpeed": 50 → "scroll": {"speed": 50}. Every field you leave out inherits from the global scroll setting.

Draw commands: arrays instead of objects¶

Each command is now an array that names the command first, instead of an object keyed by a two-letter code:

{ "draw": [
  { "dp": [28, 4, "#FF0000"] },
  { "dr": [20, 2, 4, 4, "#0000FF"] },
  { "dt": [0, 0, "Hi", "#00FF00"] }
] }

{ "draw": [
  ["pixel", 28, 4, "#FF0000"],
  ["rect", 20, 2, 4, 4, "#0000FF"],
  ["text", 0, 0, "Hi", "#00FF00"]
] }

The codes map one to one: dp → pixel, dl → line, dr → rect, df → rectFill, dc → circle, dfc → circleFill, dt → text, db → bitmap. There is also a new pixels command for many dots of one color. Arguments and clipping rules: Draw commands.

pos became the order call¶

AWTRIX NG has no pos key. The rotation order is set once, for all apps, with a single call. Unlike pos, it is stored on the device and survives reboots:

curl -X PUT http://<awtrix-ip>/api/v1/apps/order \
  -H "Content-Type: application/json" \
  -d '{"order":["Time","weather","Date"],"disabled":[]}'

A name in the order that does not exist yet simply waits, so your daily pushed app lands in its slot the moment the automation sends it. Switching off is its own disabled list beside order, and is required with it. Send no order call at all and your apps rotate in the order they arrive, the way AWTRIX 3 sorted them in. Everything the order call can do, such as switching off and duplicates for more display time, is in Pushed apps → Reordering.

save is gone - scripts took its place¶

On AWTRIX 3, save: true stored a custom app so it survived a reboot. In AWTRIX NG, pushed apps are not kept across a restart: your automation pushes again and the app comes back with current data instead of an old stored copy (why).

For content that should come back by itself, such as a label, a logo or anything else that needs no outside data, write a script. A script is a small program stored on the device that makes its own content. It also replaces AWTRIX 3's MQTT-placeholder .json files: a script can subscribe to MQTT topics and show the values in any format.

Checks that are stricter than you remember¶

AWTRIX 3 accepted almost anything and quietly skipped what it did not understand. Here the rule is all or nothing: the whole payload is applied, or the whole payload is rejected and nothing changes. The upside is that every rejection names the culprit:

{ "error": { "code": "validationFailed", "message": "unknown key", "field": "pushIcon" } }

What most commonly trips a freshly ported payload:

• An old key name: 422, with the AWTRIX 3 key in field. Rename it per the table above.
• A form Content-Type header, which curl -d sends by default: 415 or 400 (why both).
• A notification key on a pushed app: hold, stack, wakeup and the sound keys are notification-only, as in AWTRIX 3. Sending one to an app is an error in AWTRIX NG, where AWTRIX 3 ignored it.
• A payload over 8192 bytes: 413. Base64-encode bitmaps and see keeping payloads small.

The complete rule set is under payload → Errors.

Migration checklist¶

1. Rewrite the endpoint: POST /api/custom?name=x → PUT /api/v1/apps/pushed/x, or the MQTT topic custom/x → cmd/apps/pushed/x.
2. Add the Content-Type: application/json header to every HTTP request.
3. Rename the keys using the key map.
4. Multiply duration and lifetime by 1000: all durations are in milliseconds.
5. Turn numbers into words: textCase, pushIcon→iconMode, lifetimeMode→lifetimeExpiry.
6. Convert draw objects to arrays, if you draw.
7. Replace deletes: over HTTP an empty body does not remove an app. Use DELETE /api/v1/apps/{name}.
8. Re-create persistence: drop save, and push on a schedule or move the app to a script. Set the rotation once with PUT /api/v1/apps/order.
9. Send it and read the errors: each 422 names the next key to fix.

Your display type¶

AWTRIX 3 picked the display with a single number, MATRIX_LAYOUT 0, 1 or 2. Here you describe the display by its parts, in the web UI under System → Panel. Find your old number in the first column and set the fields next to it:

Leave Mirror and Rotate 180° off. They turn the picture, not the wiring, and AWTRIX 3 had nothing like them. The Display size line above the fields does the sum while you type. It should read 32 × 8 = 256 LEDs for all three.

Everything except the total width takes effect at once, so you can watch the display while you switch Serpentine on and off. Changing Panel width × Panels needs a restart.

The same three, over the API:

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

Every field, with ranges: Panel and orientation.

Beyond apps¶

• Device settings do not import. Set the device up fresh. Battery calibration in particular works differently (Coming from an AWTRIX 3 device).
• Home Assistant: automations built on the AWTRIX 3 endpoints need the same endpoint and key changes. See Home Assistant for working examples.
• Icons: the same 8×8 icon files work, with the same IDs. See Icons.

Related¶

• Pushed apps - the full guide to what custom apps became
• App & notification payload - every key, exactly specified
• Visual reference - colors, effects, palettes, overlays
• Scripting guide - self-contained apps that survive reboots