Definition
What is an AWTRIX-compatible display?
An AWTRIX-compatible display is an LED matrix that accepts the AWTRIX 3 local HTTP and MQTT calls (notify, custom apps, switch, settings, power) so existing AWTRIX 3 scripts and Home Assistant automations keep working; Perchi Matrix implements an authenticated subset.
POST /api/notify {"text": "HI", "icon": "bell"}
What is AWTRIX in the first place?
AWTRIX is firmware for an ESP32 driving WS2812 LED panels, written by Blueforcer and best known on the Ulanzi TC001 pixel clock (8x32, 256 pixels), which Ulanzi supports flashing officially. Its local HTTP and MQTT API became the way a whole community of Home Assistant users pushes notifications and custom apps to a desk display.
In 2026 the picture changed. The AWTRIX 3 repository is marked deprecated and archived, with users pointed at AWTRIX NG: a rewrite from scratch for ESP32 and ESP32-S3 with 32 to 128 by 8 panels, on-device scripting, a web UI and Home Assistant discovery, under the PolyForm Noncommercial 1.0.0 licence. Its API v1 is, in its own words, incompatible with v3: nothing carries over. An AWTRIX-compatible display keeps the AWTRIX 3 surface working so the scripts and automations people already wrote do not have to be rewritten. Facts as read on GitHub on 2026-09-18.
Which calls make a display AWTRIX-compatible?
Five groups of calls cover almost everything an AWTRIX 3 script or Home Assistant automation does. Perchi Matrix answers all 5 over HTTP on the LAN at mx-<id>.local and over MQTT, and advertises itself by mDNS with api=awtrix3 so tools that look for an AWTRIX device find it.
- Notify
- /api/notify, /api/notify/dismiss
- A one-off message with text, icon, colour and effect for 1 to 30 seconds; dismiss ends it early.
- Custom apps
- /api/custom?name=
- Creates or updates a named app in the rotation with the JSON keys AWTRIX 3 scripts already send: text, icon, progress, bar, draw and the rest.
- Switch and navigate
- /api/switch, /api/nextapp, /api/previousapp, /api/apps
- Jumps to a named app, steps through the rotation, lists what is installed.
- Settings and power
- /api/settings, /api/power, /api/indicator1 to 3, /api/stats
- Brightness, transitions, scroll speed, text colour; display on or off; the three indicators; uptime and status.
- MQTT
- <prefix>/custom/<app>, /notify, /notify/dismiss, /switch, /settings, /power
- The same commands over MQTT, a stats topic every 60 seconds, a status topic, and Home Assistant discovery for a light, a text entity, an app selector and sensors.
Does the size of the display matter?
Not exactly. 32x8 is the native AWTRIX geometry, so scripts assume 32 columns. Perchi Matrix launches as 24x8 (192 LEDs), where a 32x8 layout is cropped at the edges; the 32x8, 64x16 and 64x32 sizes run the same firmware and open later on the waitlist, and the 32x8 shows AWTRIX layouts in full.
Size is set at the factory. Which size to wait for, and what each needs for power, is on the sizes page. What happened to AWTRIX 3 and what to do with a Ulanzi you already own is in AWTRIX 3 is archived: what it means for you.
Where is the term used on myperchi.com?
These pages use the definition at the top of this page and link back here rather than redefining it.
- Perchi Matrixthe product page: 24x8 at launch, apps, price and specs
- Home Assistant appthe endpoint list and whether your AWTRIX 3 automations keep working
- AWTRIX alternativeswhat to run after the AWTRIX 3 archive, flashed or ready-made
- Perchi Matrix vs AWTRIXthe firmware on a Ulanzi against the finished display
- DevelopersREST API, webhooks, MCP, SDK and CLI alongside the local API
Related definitions: What is a desk companion? and What is a Phone Nap?
Questions about the term
Is AWTRIX a device or firmware?
Firmware. AWTRIX runs on an ESP32 driving WS2812 LED panels; the Ulanzi TC001 pixel clock (8x32, 256 pixels) is the hardware most people flash it onto, with Ulanzi's official support. An AWTRIX-compatible display speaks the same API without that flash.
Does AWTRIX NG keep the AWTRIX 3 API?
No. AWTRIX NG is a rewrite with a new API v1 that its own README calls incompatible with v3: nothing carries over and v3 integrations must be reworked. AWTRIX 3 itself is archived upstream. Perchi Matrix keeps the AWTRIX 3 surface alive; it does not implement the NG API.
Which calls does Perchi Matrix accept?
An authenticated subset of AWTRIX 3: notify and dismiss, custom apps, switch, next and previous app, the apps list, settings, power, indicators and stats, over HTTP on the LAN and over MQTT with Home Assistant discovery. The screen endpoint is not supported; the endpoint-by-endpoint list is on the Home Assistant app page.
Is the local API on Perchi Matrix on by default?
No. An owner or admin turns it on per display in the dashboard; the token is shown once and is scoped to that one display, and requests use bearer or Basic auth with an optional signed mode. It is plain HTTP on your LAN, rate-limited to 30 requests a second, and unavailable in safe mode.
Batch 2 - estimated 2 to 3 weeks, no payment today
Reserve your Perchi
Perchi Matrix is ₹4,499 incl. GST (MRP ₹4,999). No subscription needed.
No payment today. We email a checkout link when your unit is bench-tested; current estimated wait 2 to 3 weeks from the day you reserve. Cancel any time before then.