Home

256-1024 pixels on your desk, and you decide what they say.
Push text and numbers from Home Assistant, a shell script, anything that speaks HTTP or MQTT. Or write the app yourself, directly on AWTRIX, and let it run on the clock.

AWTRIX NG is a complete new development - firmware written from scratch, the successor to the well-known AWTRIX 3.

• Source code - the firmware, the web UI and these pages
• AWTRIX Flows - user-made scripts and automations for your AWTRIX
• Discord - ask, report, show what you built
• Support - support the development

Two ways to make it yours¶

1 · Push to it from outside¶

Home Assistant, a shell script, Node-RED, or your own code - if it speaks HTTP or MQTT, it can drive AWTRIX with a single request. There are two things you can send it.

A pushed app is content that stays. You PUT it under a name of your choosing, it takes a slot in the app rotation, and you send the same request again whenever the number changes:

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

A notification is a one-shot interruption. You POST it, it paints over whatever the rotation was showing, and when its time is up it is gone:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world","textColor":"#FF0000"}'

Both take the same payload keys - text, colors, icons, charts, effects (App & notification payload). The difference is lifetime: an app is a place in the rotation you own and refresh, a notification is a single message that comes and goes.

2 · Run your app on AWTRIX¶

Write it in Berry - a small, Python-shaped language - paste it into the web UI's editor, and it joins the app rotation. It is stored on AWTRIX and keeps running even when nothing else on your network is:

class Hello
  def draw()
    text(1, 6, "HELLO", 0x00FFAA)
  end
end
return Hello()

What it does¶

Supported hardware¶

One firmware image per chip, not per board: commercial 32×8 clocks, AWTRIX 2 mainboard conversions and DIY panels all flash the same file. The GPIO map is a setting, so you set your pins in the web UI under System → GPIO.

Which pins are usable and how to describe your panel are in GPIO & boards.

If you are building your own, an ESP32-S3 with PSRAM has the most room: dozens of scripts instead of a careful handful, and it is the only board that can play internet radio. Everything else works the same on a plain ESP32.

Driving the API¶

Building an integration? A handful of rules - camelCase keys, millisecond durations, the color forms, the mandatory Content-Type, the shape of an error - hold across every route and payload. They are stated once in Conventions and assumed everywhere else.

From there, the HTTP API and MQTT topics document every route and topic, and Limits collects every cap AWTRIX enforces - body sizes, app and notification counts, script memory - with what it answers when you reach one.

Start here¶

License¶

AWTRIX NG is licensed under the PolyForm Noncommercial License 1.0.0: free for any noncommercial purpose, including schools, public research and government, but not for commercial use without a separate agreement. Copyright © Stephan Mühl (Blueforcer).