How the display works¶

This page explains what AWTRIX shows, where things sit on the display, and which text moves by itself. The pages about text, drawings and scripts build on it.

The display¶

The display is a grid of pixels, 32 wide and 8 tall. A DIY clock with several panels chained is wider, and still 8 tall.

• x counts the columns from the left, starting at 0.
• y counts the rows from the top, starting at 0. A larger y is lower.
• Anything outside the display is cut off. That is never an error.

This script lights the four corners:

class Corners
  def draw()
    pixel(0, 0, 0xFF0000)
    pixel(width() - 1, 0, 0x00FF00)
    pixel(0, height() - 1, 0x0088FF)
    pixel(width() - 1, height() - 1, 0xFFFF00)
  end
end

return Corners()

Red is (0, 0). Yellow is (31, 7).

Apps take turns¶

AWTRIX shows one app at a time. The apps take turns in the rotation: each one stays for a while, 7 seconds unless you change it, then the next one comes.

• Built-in apps come with AWTRIX, for example the time and the date.
• Pushed apps are sent to AWTRIX by something else, for example Home Assistant. See Pushed apps.
• Scripts are small programs that run on AWTRIX itself. See the Scripting guide.

A notification is shown once, on top of the rotation. When it is over, the rotation goes on.

An app whose text moves can keep its turn until the text was read: with repeat in a pushed app or a notification, and with scroll_text() and {"repeat": 1} in a script. Without it, the next app comes after the usual time, even in the middle of the text.

Ways to show something¶

There are three ways to put your own content on the display. They differ in who decides where things go, and in what happens to text that is too long.

A pushed app can have text and drawing commands together.

The same text, too long for the display, in each way:

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/news \
  -H 'Content-Type: application/json' \
  -d '{"text":"THIS TEXT IS TOO LONG"}'

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/news \
  -H 'Content-Type: application/json' \
  -d '{"draw":[["text",0,1,"THIS TEXT IS TOO LONG"]]}'

class News
  def draw()
    text(0, 6, "THIS TEXT IS TOO LONG")
  end
end

return News()

class News
  def draw()
    scroll_text("THIS TEXT IS TOO LONG")
  end
end

return News()

Text¶

Where text sits¶

• Text and icon: AWTRIX places the text, in the middle of the free space or at the side textAlign names, always on the same rows. You cannot move it up or down.
• Drawing commands: y = 1 puts the letters on the rows of the app's own text, in every font. A larger y moves them down. In the default font small, y is the top row of the letters.
• Script: y is the baseline, the line the letters stand on. The table below shows which rows each font fills.

These two put the same letters on the same rows. The script names the baseline, row 6. The drawing command names the top row in the default font, row 1:

class Hi
  def draw()
    text(1, 6, "Hi 42")
  end
end

return Hi()

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/hi \
  -H 'Content-Type: application/json' \
  -d '{"draw":[["text",1,1,"Hi 42"]]}'

Which rows a font fills. The y in this table puts a script's line where apps put theirs. A smaller y moves the line up.

Letters such as g and y reach lower than the capitals.

When text moves¶

• Text from the text key moves only when it does not fit. Short text stands still. Scrolling, or not has the options.
• Drawing commands and a script's text() never move. What does not fit is cut off at the edge.
• scroll_text() stands still, in the middle, when the text fits, and moves when it does not. A script can move two texts at a time, each in its own place: another y, or other columns.

A frame is one still picture. A script's draw() paints a new frame about 40 times a second. To move something without scroll_text(), draw it a little further along in each frame:

class Go
  var start

  def init()
    self.start = 0
  end

  def on_show()
    self.start = now_ms()
  end

  def draw()
    var x = width() - (now_ms() - self.start) / 40 % (width() + 12)
    text(x, 6, "GO", 0x00FF00)
  end
end

return Go()

on_show() runs each time the app appears, so now_ms() - self.start counts the milliseconds since then, and / 40 moves the word one column every 40 ms. Berry divides whole numbers without a remainder: multiply before you divide, or a small result becomes 0.

Areas side by side¶

Icon and text¶

An icon takes the left 8 columns and a gap of 1. The text uses the rest. Charts start after the icon too, and a progress bar starts right at its edge. Drawing commands ignore the icon: their positions count from the left edge of the display.

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

sun is an icon from the AWTRIX Hub.

Moving text next to something else¶

In a script, scroll_text(x, y, w, text, color) moves the text only through the columns x to x + w - 1. Draw your icon or symbol beside them: the moving text never touches it.

class Room
  def draw()
    circle_fill(3, 3, 3, 0xFFC000)
    scroll_text(9, 6, width() - 9, "Living room 21.5°C", 0x00AAFF)
  end
end

return Room()

What is drawn on top¶

• Pushed app and notification: first the background or the effect, then drawing commands, progress bar, bar chart and line chart, then the icon. The text lies under charts and drawings unless textInFront is on. A weather overlay covers everything. Layering has the details.
• Script: each call paints over what is already there. Call effect() first and overlay() last.

Related¶

• Text & colors: fonts, colors and scrolling
• Charts & drawing: every drawing command
• Scripting: Drawing: every drawing call in a script
• Icons: getting icons onto the clock