Skip to content

Limits

Every cap AWTRIX enforces: how big or how many something may be, and what happens when you reach it.

Requests

Limit Cap When you hit it
JSON request body (HTTP) 8192 bytes 413 payloadTooLarge, nothing is applied
MQTT command payload 8192 bytes for the whole message, topic included the message is dropped unread: no error, no /result reply
App and script names 1–32 characters of A–Z, a–z, 0–9, _, - 400 invalidName
JSON nesting 16 levels of objects and arrays 400 invalidJson

There is no cap on how many keys or array entries a body may hold, as long as it fits the size limit.

What AWTRIX publishes to you over MQTT has no size limit. Only what you send to it is capped.

Apps and notifications

Limit Cap When you hit it
Pushed apps resident 50 507 insufficientStorage, nothing is stored - delete an app first
Notification queue 32, counting the one shown a new notification with stack: true gets 507 insufficientStorage; stack: false replaces the one shown and always works
Notifications per request 1 422 validationFailed - send one per request
barChart / lineChart points 16 the 17th and later entries are dropped; the chart still draws
Additional positioned icons (icons) 4 per pushed app or notification, plus the ordinary icon 422 validationFailed on icons; the whole request is rejected

The 50 counts new names only. Replacing a pushed app that already exists always works.

An array payload is all-or-nothing: if its new names would take the total past 50, the whole request gets 507 and none of its apps are created or updated.

Scripting

These caps apply to Berry scripts. How to work within them is explained in the Scripting guide.

Limit Cap When you hit it
Instructions per entry 200 000 the script stops until you save a new version, save its settings or data, or restart the device; nothing else is affected
Shared script memory 96 KiB (98304 bytes) without usable PSRAM, about half the free PSRAM with it. Read the value in scriptHeapBudgetBytes new installs are refused until memory is free again; installed scripts keep running
Free memory to install about 8 KB plus the size of the source; re-saving an existing script, about 4 KB plus the source the install is refused with 507 - see what helps
Memory in one piece at least the size of the source the install is refused with 507 and "heap too fragmented to compile" - restart AWTRIX and try again
Memory held back while a script compiles 24 KiB (24576 bytes), on a board without usable PSRAM the install fails with out of memory
HTTP response body 8 KB, or cap if the request sets one - lowered to the free memory when the answer starts the body is cut at that size. To keep only the part you need, use find
Free memory while a response arrives enough for the rest of the body the whole request fails: the callback gets nil and the real status code
HTTP connect and read timeout 5 s each the callback gets nil, 0
HTTP request unanswered 30 s the callback gets nil, 0
HTTP requests in flight 8 per script http.get() calls back nil, 0 at once
Script timers 8 per app, 32 in total; each 25 ms to 1 day timer.after() and timer.every() return nil
MQTT subscriptions 8 per script further mqtt.subscribe() calls are ignored
MQTT messages waiting 32, shared by all scripts the oldest waiting message is dropped
Setting key 1–24 characters of A–Z, a–z, 0–9, _, starting with a letter the line is skipped and the settings show why
Setting text value 256 characters, or maxlen= if you set one 422, nothing is saved
Shared key names 1–24 characters of A–Z, a–z, 0–9, _, - shared.set() returns false, nothing changes
Different script icons per frame 4 icon IDs icon() returns false for a 5th different ID in the same draw()

The instruction limit counts per entry into your script: each draw(), each loop(), each button press and each HTTP callback starts again at the platform's limit. A try/except cannot catch it.

The same script icon ID drawn at several positions counts as one icon. All copies animate together.

Sounds

The messages for rejected sounds are listed in Audio playback errors.

Limit Cap When you hit it
Melody source 512 characters 422 validationFailed
Melody name 1–24 characters of A–Z, a–z, 0–9, _, - 422 validationFailed
MP3 name 1–32 characters of A–Z, a–z, 0–9, _, - 400 invalidName, the upload is refused
MP3 and melody names an MP3 in /MP3 and a melody never share a name 409 nameTaken, nothing is stored
Entries in a sound list 1–4 422 validationFailed
DFPlayer track 1–2999 422 validationFailed

Storage

Limit Cap When you hit it
Icon and file storage the free space on AWTRIX. The storage area is 512 KB on a 4 MB board, 4.5 MB on 8 MB, 12.5 MB on 16 MB 507 insufficientStorage; no half-written file is left behind

Which file formats are accepted is listed in Icons.

Backup restore

Limit Cap When you hit it
manifest.json 4 KiB the whole backup is rejected
Each settings, configuration, app-order or radio JSON file in the backup 64 KiB that file is skipped with a warning
config/icon-origins.json 16 KiB that file is skipped with a warning
Detailed restore warnings 128 one extra message says how many more were left out

Icons, sounds and other asset files have no size cap of their own here. They only need to fit the free storage and follow their format's rules. If a file cannot be written, the old file stays.

A restore is applied file by file. If it stops halfway, the files restored before that point are already changed.

Display

Limit Cap When you hit it
Panel width panelWidth × panels, default 32 × 1, total 32–128 422 validationFailed
Display height 8, cannot be changed -
Total pixels at most 1024 (128 × 8) follows from width and height. Read the limits of your device in capabilities.display
GIF size the display's width and height resize larger GIFs before uploading; every frame must fit

What is not limited

  • Requests per second. Neither HTTP nor MQTT limits how often you send.
  • Messages AWTRIX publishes. state/device and state/screen are sent at whatever size they are.
  • How long a script runs in total. Only a single entry into the script is capped. A script that returns quickly can run for as long as AWTRIX is on.