Visual reference¶

This page lists every visual name AWTRIX NG understands – effects, overlays, palettes and transitions – and shows what each one looks like. It also covers colors, text and fonts.

There are four separate lists of names. They do not mix:

Upper and lower case never matter – "matrix", "Matrix" and "MATRIX" are the same effect. This page uses the spelling that GET /api/v1/capabilities lists and the API returns.

Ripple and Fade are in two lists – as a background effect and as a transition – and the two look different. Random is only a transition. What a name means depends on the key you use it with.

Background effects¶

A background effect fills the display behind text, icons and charts. Set it per app with the effect key.

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/demo \
  -H 'Content-Type: application/json' \
  -d '{"text":"HELLO","effect":"Pacifica"}'

AWTRIX has 19 background effects:

Every effect fills the whole display. In a pushed app or a notification it is drawn at double size on the 26×8 grid while enlargeApps is on, the default. In a layout, in a script and in an app that keeps its full size, it uses all 52×16 pixels: LookingEyes and the squares of Checkerboard are drawn twice as large, BrickBreaker, PingPong and Snake play on the bigger field, and the other effects use the extra pixels for more detail. Weather overlays always use single pixels.

An empty effect, or no effect key, means no background.

The effects marked no always use their own colors. If you send a palette with them, the request succeeds but nothing changes on the display.

An unknown name ("Plasm") is rejected with 422 {"code":"validationFailed","field":"effect"} and nothing is stored – with a list of apps, none of them is stored. Upper and lower case are not a typo: "pacifica" works. Check the spelling with GET /api/v1/capabilities.

Effect settings¶

An effect takes two things from its payload: its own speed, and the app's palette, which it shares with the text and the charts.

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/demo \
  -H 'Content-Type: application/json' \
  -d '{"text":"HI","effect":"Plasma","effectSpeed":0.4,"palette":"Lava"}'

How effectSpeed works¶

Each effect and overlay has its own normal speed. effectSpeed multiplies it: 2.0 runs twice as fast, 0.5 half as fast. At 1 all effects feel about equally fast, but they still differ in character – storm falls faster than drizzle.

A value outside 0.1 … 10 is not rejected; AWTRIX uses the nearest limit.

effectSpeed also sets the speed of an overlay named in the same payload, so storm at 2 falls twice as fast. The overlay for the whole device has its own speed, set with overlaySettings on PATCH /api/v1/display.

How palette works¶

You can give a palette in three ways:

{"palette": "Heat"}

{"palette": ["#FF0000", "#00FF00", [0,0,255], ["HSV",60,100,100]]}

{"palette": [{"color": "#FF0000", "pos": 0},
             {"color": "#FFFF00", "pos": 70},
             {"color": "#FFFFFF", "pos": 100}]}

One palette serves the whole app. To paint text or a chart from it, set that color key to the string "palette":

{"palette": "Heat", "textColor": "palette", "chartColor": "palette"}

Effects that use palettes take it automatically.

The palette is per app¶

The palette and effectSpeed you send belong only to that app. If app A and app B both use Plasma and app B sets palette: "Lava", app A keeps its own colors. When you delete an app, its palette goes with it.

Weather overlays¶

An overlay is drawn on top of the app. Text and icons stay visible underneath.

AWTRIX has 6 weather overlays:

At each step every drop moves down one pixel, so rain crosses the 16-pixel display in about one second. Heavier weather falls faster. The speed factor (effectSpeed on a payload, speed in overlaySettings) changes the speed; for frost it is the speed of the shimmer. The drops fall at random places, so the pattern never repeats.

A palette changes the colors of all six overlays, frost too. Without a palette they keep their normal colors.

# red rain
curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/weather \
  -H 'Content-Type: application/json' \
  -d '{"text":"7C","overlay":"rain","palette":"Lava"}'

Setting an overlay per app¶

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

An unknown overlay name is rejected with 422 {"code":"validationFailed","field":"overlay"} and nothing is stored.

Setting the global overlay¶

PATCH /api/v1/display sets an overlay for the whole device. null removes it.

curl -X PATCH http://<awtrix-ip>/api/v1/display \
  -H 'Content-Type: application/json' \
  -d '{"overlay":"rain"}'

# remove it
curl -X PATCH http://<awtrix-ip>/api/v1/display \
  -H 'Content-Type: application/json' \
  -d '{"overlay":null}'

Both keys are checked. An overlay that is neither a string nor null gives 422 {"overlay","must be a string or null"}; an unknown name gives 422 {"overlay","unknown overlay"}; an overlaySettings that is not an object gives 422 {"overlaySettings","must be an object"}. The PATCH is applied completely or not at all.

# slow the global rain down to a third of its speed
curl -X PATCH http://<awtrix-ip>/api/v1/display \
  -H 'Content-Type: application/json' \
  -d '{"overlay":"rain","overlaySettings":{"speed":0.3}}'

overlaySettings belong to the overlay you set them for. {"overlay":null} removes them too, so the next overlay you pick starts fresh.

GET /api/v1/display returns both: overlay (null when none) and overlaySettings with the current speed, palette (null when not set) and blend.

In the web UI, the speed is the Overlay speed slider under Display → Weather overlay, in percent: 100 % is the overlay's normal speed.

Which overlay wins¶

• Pushed apps and notifications: an overlay in the app's payload or in its layout wins over the global one. The global overlay shows only when neither has an overlay.
• Built-in apps (time, status): only the global overlay shows, because these apps have no payload.
• Speed and colors come with the overlay. An overlay from a payload uses that payload's effectSpeed and palette. The global overlay uses overlaySettings, whatever app is shown.

Palettes¶

A palette is a set of 16 colors. Effects, overlays and text that use a palette take their colors from it.

8 built-in palettes can be used by name in palette:

What blend changes¶

While an effect runs, it moves through the 16 colors in order and starts over after the last one.

• paletteBlend: true (default) – the color changes smoothly from one to the next, like a gradient.
• paletteBlend: false – only the 16 colors themselves are used, so you see 16 hard bands.

Custom palettes¶

1. Create a text file with one color per line, one to sixteen lines. Lines after the sixteenth color are ignored.
2. Upload it to AWTRIX as /PALETTES/<name>.txt.
3. Use <name> (without .txt) as palette.

A leading # on a line is allowed and empty lines are skipped. Names with / or .. are rejected. Upper and lower case in the name do not matter.

Each line has one of two forms:

FF0000@0
FFFF00@70
FFFFFF@100

The lines are color stops of a gradient across all 16 colors: a three-line file gives a three-color gradient. With positions, you decide how much room each part gets – the example above uses 70 % of the gradient to go from red to yellow. Before the first and after the last stop the color stays the same. Two stops at the same position make a hard edge.

Either every line has a position or none has; mixing is rejected. Stops out of order are sorted. A file with any other error – a line that is not six hex digits, a position above 100 – cannot be used. Any payload that names it is rejected with 422 on the palette field.

A file may have the same name as a built-in palette. It then replaces the built-in until you delete the file. This is how you change a built-in palette: the palette editor saves such a file for you. A name that matches neither a file nor a built-in is rejected with 422 validationFailed on the palette field.

Transitions¶

A transition is the animation between one app and the next. It is one setting for the whole device; you cannot give one app its own transition.

transitionEffect and transitionDirection are names (strings), sent to PATCH /api/v1/settings:

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H 'Content-Type: application/json' \
  -d '{"transitionEffect":"Slide","transitionDirection":"reverse","transitionDurationMs":600}'

reverse flips sideways movement left/right and vertical movement up/down. It does not change the app order: Next and automatic switching still go to the same app, and Previous still moves the other way. Transitions marked no below look the same either way.

22 transitions:

An unknown name is rejected with 422 validationFailed. The message starts with must be one of: and lists the names above.

Flash makes the whole display nearly white for a moment.

Pacing¶

Every transition takes exactly transitionDurationMs, and they are tuned to feel equally long:

• Slides and wipes start slowly, speed up and slow down at the end.
• Fades and dissolves (Dim, Zoom, Pixelate, Blink, Fade, Blocks, Flash) run at an even speed.
• Rain and Melt start each column a little later, but all columns fall at the same speed and the last one lands exactly at the end.

Colors¶

Every color key in the whole API – payload keys, settings, palette colors, draw commands – accepts the same forms.

Accepted input forms¶

An 8-digit #RRGGBBAA value is rejected – there is no transparency.

HSV values: h is the hue in degrees; values outside 0…359 wrap around (-30 becomes 330). s and v are percentages from 0 to 100, not 0…255. Larger values count as 100, so ["HSV",0,100,100] and ["HSV",0,100,255] are both pure red.

Output form¶

Colors always come back as "#RRGGBB" in capitals, whatever form you sent. Optional colors that are not set come back as JSON null.

Nullable colors¶

Send null to get this behavior back. Only null means this – #000000 and #FFFFFF are normal colors and come back as themselves.

A malformed color is rejected everywhere¶

Settings, indicators, the mood light and app/notification payloads all reject a color they cannot read. The answer is 422 validationFailed with the key in field, and nothing is stored. The message differs: settings, indicators and the mood light say must be a color; a color in an app or notification payload says invalid color. In your own code, check the code and field, not the message text.

Display colors¶

Four settings change how the whole display looks. They do not change what the apps show – only how the colors come out of the LEDs. Types, ranges and defaults are in Settings – Color.

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H 'Content-Type: application/json' \
  -d '{"saturation":40,"gamma":2.2,"colorCorrection":"#FFB0F0","colorTint":null}'

Good to know:

• The settings affect everything on the display: apps, icons, notifications and the mood light.
• Changes show at once.
• A screenshot from GET /api/v1/display/screen or the web UI preview does not include these settings. That is why a screenshot can look different from the real display.

The default text settings – textColor, uppercase and scroll – are in Settings – Global text. A payload can override each of them.

Text¶

Encoding¶

Send text as UTF-8. This applies to plain text, to each {"text":…} part, to text in draw commands and to text from scripts.

A character the font does not have is shown as one ? – one per character. "Hi 🎉" shows as "Hi ?".

What is mapped¶

Every font has the same characters – small, large and all ten Matrix-Fonts.

An accented letter sits on the same line as the letter without accent, with the accent above it. In small, the Latin-1 accents fit into the five rows of a normal letter (the letter gets one row shorter). Latin Extended-A, Ё ё, accented Greek capitals and Vietnamese capitals with a horn or two accents use one extra row at the top of the display (row 0). In large all accents fit into the same seven rows.

Font¶

Two standard fonts and the Matrix-Fonts below. A pushed app or a notification picks one with the font key.

small uses the AWTRIX font for ASCII and Matrix-Fonts for everything else – accents, Cyrillic, punctuation. large uses Matrix-Fonts for everything. The fonts are licensed under the SIL Open Font License 1.1; Trip5 and the original font authors are credited in the license notices that come with the firmware source and the update package. AWTRIX NG itself has its own license.

Both fonts have the same characters. The choice changes only the height – and, because the text width changes, whether a text scrolls.

large leaves only the bottom row free. If your app draws its own graphics along the top, use small.

Pushed apps, notifications, layout text regions and the script function font(name) can all use Matrix-Fonts. GET /api/v1/capabilities lists each available font ID with ascent, descent and lineHeight in pixels. In a pushed app or a notification, ascent and descent decide where the text sits: the font's rows are centered in the height of the display.

See the font selection for what each font looks like.

The Matrix-Fonts keep all their original characters and spacing, including characters wider than eight pixels. Missing characters were added in each font's own style, so every font has all the characters above and changing the font never turns a character into ?. In layout text regions, vertical alignment takes accents and descenders into account. Font sources and credits are in the font catalog record.

Palette text¶

Set textColor to the string "palette" to paint the text with the app's palette instead of one color. The colors change column by column, so the gradient is even whatever the letter widths are.

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H 'Content-Type: application/json' \
  -d '{"text":"PARTY TIME","palette":"Rainbow","textColor":"palette","paletteSpan":24,"paletteSpeed":1}'

paletteSpan is the width in pixels of one full run through the palette. 0 (the default) stretches one run across the whole text. paletteSpeed moves the colors by that many runs per second, independent of effectSpeed.

All keys a payload can have – text, colors, charts, effects, palettes and draw commands – are in App & notification payload. This page shows what they look like on the display.

Scrolling¶

One scroll object sets how text moves. It means the same in a payload and in the settings. The fields, ranges and defaults are in Payload – Scrolling. The four modes look like this:

In a payload every field is optional and uses the device default when left out, so {"scroll":{"mode":"bounce"}} bounces at your usual speed. A plain string sets only the mode: "scroll": "bounce" means "scroll": {"mode": "bounce"}. An unknown field, an unknown value or a negative number gives 422 validationFailed with the key in field – in PATCH /api/v1/settings and in a payload alike. In a payload, the whole app or notification is rejected.

Every pause lasts holdMs; entry: offscreen skips the first one. Exact positions: Payload → Scrolling.

Draw commands¶

The draw list knows 9 commands. Each command is a list with the command name first:

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/box \
  -H 'Content-Type: application/json' \
  -d '{"draw":[["rect",0,0,32,8,"#00FF00"],["pixel",16,4,[255,0,0]]]}'

Every draw color can use any color form. Without a color, the command uses the app's text color. An unreadable color or an unknown command name is rejected with 422 validationFailed and "field":"draw[<index>]".

Discovering the names¶

GET /api/v1/capabilities returns the current name lists, so your tools do not need to copy them:

curl http://<awtrix-ip>/api/v1/capabilities

{
  "effects": ["BrickBreaker", "Checkerboard", "..."],
  "paletteEffects": ["Checkerboard", "ColorWaves", "..."],
  "transitions": ["Random", "Slide", "Dim", "..."],
  "overlays": ["drizzle", "frost", "rain", "..."],
  "palettes": ["Cloud", "Lava", "Ocean", "Forest", "Stripe", "Party", "Heat", "Rainbow"]
}

Use paletteEffects for a palette picker – the effects with fixed colors are in effects but not here. The names are spelled the way the API returns them; upper and lower case do not matter when you send them.

palettes lists only the built-in palettes. Palettes you upload as /PALETTES/*.txt work everywhere a built-in name works, but they are not in this list – list them with GET /api/v1/files?dir=/PALETTES.

The same JSON is published, retained, to MQTT <prefix>/state/capabilities every time AWTRIX connects, and fills the Home Assistant select lists.

Related¶

• App & notification payload – every key a payload can carry
• Settings – transitions, text defaults and display colors
• Effects & overlays
• Palette editor