Migrating from AWTRIX 3¶

On AWTRIX 3 you pushed custom apps; here the same thing is called a pushed app. The idea is unchanged - your automation sends a JSON object, AWTRIX puts a page for it into the app loop and keeps showing it until you update or remove it. What changed is the address you send to, the names of the keys, and how strictly the payload is checked.

This page walks you through converting an existing custom app. 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 now lifetimeExpiry: "mark".
3. Strict validation. A key AWTRIX does not know is no longer ignored - the whole payload is rejected with 422 and the name of the offending key. Your old payload will not half-work; it will tell you exactly what still needs renaming.

Convert a flow automatically¶

Paste an old flow - a Home Assistant automation or blueprint, a Node-RED or N8N export, a curl command, or a bare JSON payload - and get it back in the NG dialect. 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 - JavaScript that builds payloads, template expressions, keys with no NG equivalent - is left untouched and listed as a warning that links to the matching section below.

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 behaviour - every value found a new home. Colors themselves carry over unchanged: hex strings and [r, g, b] arrays are both still accepted (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 competing text stylings - gradient, rainbow, blinkText, fadeText - that excluded one another. Gradient and rainbow merged into one mechanism, 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/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 behaviour are now one scroll object with modes AWTRIX 3 did not have - wrap, loop, bounce, direction, off-screen entry 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¶

The experimental pos key is gone. The loop order is set once, for all apps, with a single call - and 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 - switching off, duplicates for extra screen time - is in Pushed apps → Reordering.

save is gone - scripts took its place¶

save: true wrote a custom app to flash so it survived a reboot. Pushed apps here are deliberately RAM-only: after a restart your automation pushes again and the app comes back with current data instead of a stale stored copy (why).

For content that should come back by itself - a label, a logo, anything needing no outside data - write a script: a small program stored on the device that generates its own content. That is also the successor to AWTRIX 3's MQTT-placeholder .json files - a script can subscribe to MQTT topics and render the values however it likes, where the old placeholders allowed no formatting at all.

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 missing Content-Type: application/json header - 415 or 400 (why both).
• A notification key on a pushed app - hold, stack, wakeup and the sound keys are notification-only, same as before, but now sending one to an app is an error instead of a no-op.
• 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 milliseconds now.
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 no longer removes an app; use DELETE /api/v1/apps/{name}.
8. Re-create persistence - drop save, 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 panel type¶

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

Leave Mirror and Rotate 180° off - they are about the picture, not the cable, and AWTRIX 3 had no equivalent. The Matrix 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 on the next frame, so you can watch the panel while you switch Serpentine on and off. Changing Panel width × Panels needs a reboot.

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 IDs and files work; see Icons & assets.

Related¶

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