Display - NeoPixel Matrix

NeoPixel Matrix display

Plugin details

Type: Display

Name: NeoPixel Matrix

Status: NEOPIXEL

GitHub: P131_NeoPixelMatrix.ino

Maintainer: tonhuisman

Used libraries: https://github.com/adafruit/Adafruit_NeoMatrix

Description

The popular NeoPixel multi-color leds are available in many configurations, either as separate leds or led-stripes and also in a pre-mounted matrix configuration. They are easy to implement, as they only require a single GPIO pin to control up to several hundreds of these pixels.

This plugin is created to use 1 or more matrices of NeoPixels, and allows to draw graphic elements, write text or display bmp files, with a configurable brightness.

When using multiple matrices, we use the term ‘Tile’ in this context, they need to use the same layout and rectangular size per matrix. The Tiles are also configurable in layout and rectangular size.

This plugin uses the same AdafruitGFX_Helper module, as used in some other Display plugins, like Display - TFT ILI934x/ILI948x and Display - ST77xx TFT, and implements the same graphic commands. The AdafruitGFX_Helper module is ‘limited’ to 65535 (RGB565 coded) colors, but the used library uses a smart color mapping scheme to display colors as accurate as possible.

Matrix and Tile layouts

Several Matrix and Tile layout configurations are possible, and supported. Reasons for having a specific layout are usually driven by the challenges of mechanical construction for these types of display. Common requirement is that all matrices and tiles are electrically connected as a single, uninterrupted, serial stream of NeoPixel leds.

Note

Credits: Most of this layout-description and the images are based on and copied from the documentation available at the Adafruit NeoPixel Uber-guide

Matrix: A Matrix is a rectangular set of NeoPixel leds, with configurable width, height, starting led, orientation and direction.

Tile: A Tile is a rectangular set of same size/layout Matrices, with configurable width, height, starting matrix, orientation and direction.

The plugin handles both single matrices - all NeoPixels in a single uniform grid - and tiled matrices - multiple matrices combined into a larger display:

Leds single versus tiled

Let’s begin with the declaration for a single matrix, because it’s simpler to explain. We’ll be using an 8*5 matrix of NeoPixels. When looking at this matrix with the text in a readable orientation, the first pixel, #0, is at the top left. Each successive pixel is right one position - pixel 1 is directly to the right of pixel 0, and so forth. At the end of each row, the next pixel is at the left side of the next row. This isn’t something we decide in code… it’s how the NeoPixels are hard-wired in this circuit board comprising the matrix.

Matrix with horizontal layout

The first pixel is in Top/Left postition. We refer to this layout as Row mode and Progressive. Row mode means the pixels are arranged in horizontal lines (the opposite, in vertical lines, is column mode). Progressive means each row proceeds in the same direction. Some matrices will reverse direction on each row, as it can be easier to wire that way, especially when using a very wide matrix. We call that a zigzag layout.

However, if we want to use this matrix in the “tall” direction, so the display is standing up on the desk with the Din connection at the right-top. When we turn the board this way, the matrix layout changes:

Matrix with vertical layout

Now the first pixel is at Top/Right. Pixels increment top-to-bottom - it’s now in Column mode. The flow-direction of the columns is still Progressive though.

Similar configuration options are available for tiles. Making more specific mounting configurations possible, like this:

Specific Matrix and Tile configuration

As shown in these examples, neither a Matrix nor a Tile has to be square, though both have to be rectangular to result in a correct display setup.

NB: The maximum number of matrices/NeoPixels that can be connected is not determined, though when having > 1500 NeoPixels on a single GPIO pin, this can cause timing issues when the ESP is not fast enough to update all leds within the available time-window, resulting in the content being distorted.

Signal wiring

Note

If the matrices use a VCC higher than 3.3V, f.e. 5V (and they usually do), a level converter for 3V3 to 5V should be used when connecting the display to the ESP, as the ESP might be damaged, or the logic levels don’t match the requirements of the display (high level ~70% of VCC = 3.5V @ VCC 5V), and may not work properly.

ESP        Level converter    5V   NeoMatrix 1  5V    NeoMatrix 2  5V    NeoMatrix n
----       ---------------    |    -----------  |     -----------  |     -----------
3V3   -->  LV           HV  <-+->  VCC          +->   VCC          +->   VCC ...
GND   ---  GND ------- GND   ---   GND - GND    ---   GND - GND    ---   GND ...
GPIO  -->  LV1 ------> HV1 -[470]- DIN - DOUT   -->   DIN - DOUT   -->   DIN ...

NB: It is advised to use a single 220 to 470 ohm resistor in the wiring from ESP (after the level converter) to the first NeoPixel Din for better signal stability.

Power consumption

By the physical design of these modules, using NeoPixel leds for display that can consume up to 60 mA each, the power consumption is dependent on the number of neopixels that are activated and the brightness that is set. On a set of NeoPixels, like consisting of 64 pixels, the max. power used 60 mA * 64 = 3840 mA @ 5V = 19.2 watt with all leds on at max brightness (255), so it requires an adequate power supply, preferably separate from the power supply used to power the ESP.

When reducing the brightness to 40% (0.4 * 255 = 102), that power is reduced to ca. 1.5 A @ 5V = ca. 7.5 watt. 40% is usually enough during daylight conditions, at night the brightness can often be reduced to 20%.

For a set of 300 pixels, the max. power would count up to 300 * 60 mA @ 5V = 90 W. At 40% brightness, that is reduced to 36 W.

Reasoning back from the available power supply max. load (f.e. 30 W), the max. allowed brightness can be calculated by dividing the max. load by the voltage (5V) and the number of pixels (300) = 20 mA, 60 / 20 = 3 = ~33% brightness = 85. That will still be bright enough, but will put quite a strain at the power supply.

Also, when using several matrices sequentially, separate wiring should be added for VCC and GND to each group of matrices, to avoid burning out the pcb traces of the matrix where the power is connected. For groups of 4 to 8 matrices, it is advised to use separate wiring for power to each group, and only connect the GND and signal connections Dout/GND to Din/GND of the next group, but never the VCC pins.

Configuration

Device configuration

Task settings

  • Name The name of the task. This should be unique for all devices that are configured. (Initially empty)

  • Enabled For the device to work it has to be enabled. When checked, the device will be started as soon as the ESP starts. If desired, the device can also be enabled from f.e. a rule by using the TaskEnable,<tasknr> or TaskEnable,<taskname> command, or disabled using the corresponding TaskDisable,<tasknr>|<taskname> commands.

Actuator

  • GPIO -> DIN Select the GPIO pin that’s wired to the DIN input on the first matrix.

  • Strip Type: Select the type of the LEDs mounted on the matrices:

The Strip type options

GRB : Most commonly, the LEDs are of GRB type.

GRBW : If the LEDs also support Brightness control, then the GRBW type should be selected.

Matrix

  • Matrix width: The number of NeoPixels that form the width of 1 Matrix. Range: 1..100.

  • Matrix height: The number of NeoPixels that form the height of 1 Matrix. Range: 1..100.

  • Matrix start-pixel: The location of the first NeoPixel of the Matrix. Available options:

Start options
  • Matrix Rows/Columns mode: The direction of how the pixels are installed in the Matrix. Available options:

Rows/Columns mode options
  • Matrix flow-direction: The flow of the pixels on the Matrix. Available options:

Flow-direction options

Multiple matrices: Tiles

  • Tile width: The number of Matrices that form the width of the Tile. Range: 1..32.

  • Tile height: The number of Matrices that form the height of the Tile. Range: 1..32.

  • Tile start-matrix: The location of the first Matrix in the Tile. Available options:

Start options
  • Matrix Rows/Columns mode: The direction of how the Matrices are connected in the Tile. Available options:

Rows/Columns mode options
  • Matrix flow-direction: The flow of the Matrices in the Tile. Available options:

Flow-direction options

Display

  • Rotation Depending on how the display is to be mounted/installed, it may be needed to rotate the content, or with a non-square resolution, to use the display in Landscape layout instead of the default Portrait.

Available options:

Rotation

The available options rotate the display in a clock-wise direction.

NB: Because of the above Matrix & Tile configuration, this option is less relevant for this display, but available in the AdafruitGFX_Helper module, so still included here as the accompanying rot subcommand is also supported.

  • Text print Mode Defines the handling of text when predefined text or text via the txt or txtfull subcommands (see below) is displayed.

Available options:

Text print mode
  • Continue to next line Simply ‘prints’ all text to the display, with automatic overflow to the next line(s) if the text doesn’t fit on the current line.

  • Truncate exceeding message (Default) Display the provided message, but any excess at the right border of the display is discarded.

  • Clear then truncate exceeding message Clear from the current cursor position to the width of the display, then display the provided message, but any excess at the right border of the display is discarded.

Default setting is Continue to next line.

  • Initial brightness: The brightness that the display is initially set to. Default is 40, to protect both the eyes and the power-supply powering the display. Range: 0..255.

  • Maximum allowed brightness: The brightness that is the maximum it can be set to, either from UI or via the brightness command, to optionally help protect both the eyes and the power-supply powering the display. Default is 255. Range: 1..255.

  • Font scaling The scaling factor for the currently active font. Select a factor between 1 and 4.

  • Clear display on exit When checked, will clear the display when the task is disabled, either from settings or via the TaskDisable command. This will fill the display with black pixels, turning all NeoPixels off.

  • Write Command trigger The command to handle any commands for this device can be selected here. This way you can have different commands when multiple displays are configured. It is processing most commands via the ESPEasy Adafruit Graphics helper class.

Available options:

Write-command trigger
  • neomatrix

  • neo

The command is handled non-case sensitive. See below for available commands and subcommands.

Content

  • Foreground color

  • Background color

These are the default colors, used to display the content as configured below (if any).

Colors can be specified in 3 ways:

  • Color name Some named colors are recognized: White, Black, Red, Green, Blue, Yellow, Orange, Navy, Darkgreen, Cyan, Darkcyan, Maroon, Purple, Olive, Magenta, Lightgrey, Darkgrey, Pink and Greenyellow. If any of these colors is recognized, the name will be shown.

  • #RGB565 A # prefixed, 1 to 4 digit, hex-coded color value in RGB565 format (5 bits red, 6 bits green, 5 bits blue) giving the max. number of 65535 colors. This is the value that is shown after the settings are saved, and it is not one of the known color names.

  • #RRGGBB A # prefixed, 6 digit, hex coded RGB color value. Will be transformed to an RGB565 value on save!

If the Foreground and Background colors are the same, the background color will become transparent. If the Foreground color is empty, as a default white will be set.

Lines

  • Line 1..n Predefined content can be specified. The number of lines shown depends on the Tile height of the display.

The usual variables, like [Taskname#Valuename], or %v1%, system variables, formulas and functions can be used.

Input length is limited to 50 characters per line. If a longer calculated text is needed for a line, then it should be set from the rules or from an external source via http commands.

Per Line you can define if Scrolling should be used for displaying the content. When enabled, the other available options will be used to scroll the text.

  • Scroll: Enables (horizontal) scrolling of the content. NB: Scrolling will only be enabled if the content length won’t fit on the display!

  • Empty start: When checked, the display will start empty, and the text will be scrolled in. It will also scroll out until the display is empty again. (Default enabled). When unchecked, the display will start with the content that fits on the display, and scroll until the ‘other’ end of the text is visible. The display won’t be empty when having this setting off.

  • Scroll right: By default, scrolling will be from right to left, when this option is checked, scrolling will be from left to right direction.

  • Stepsize: The number of pixels that each step will scroll. Range 1..16, default 1.

  • Speed: The number of 0.1 seconds before the next scroll step will be applied. Range 1..600 (0.1 second to 60 seconds), default 10 (1 step per second).

If more then 1 line is shown, next to the last Line the remaining capacity in characters is displayed.

The total combination of lines * input length can not exceed 1000 characters (sized dynamically), as there is limited storage per task available for these settings. An error message will be shown after (trying to) save the settings, any excess content will be discarded!

Example:

Save error
  • Interval By default, Interval will be set to 0. If set to a non-zero value, the pre-configured content will be updated automatically using that interval (seconds). Depending on the Text print Mode setting, content that may have been draw from rules or external commands, may be erased.

Commands

Command Syntax

Extra information

This plugin allows dynamic configuration of the command-trigger. Available triggers are:

  • neomatrix

  • neo

The default trigger is neomatrix

Some commands are postfixed with cmd, indicating device specific commands. Not device-specific commands are genericly applicable to all Adafruit Graphics Helper enabled devices, using the ESPEasy AdafruitGFX_helper module.

neomatrixcmd,clear
Clear the display, using the default background color.
neomatrixcmd,bright[,<brightness>]
Set the level of display brightness, range: 1..255. If no brightness or 0 is provided, the Initial brightness setting is used.
The maximum brightness allowed is determined by the Maximum allowed brightness setting.
neomatrixcmd,settext,<line>,<text>
Set the text for a specific line of the matrix. When Scroll is enabled for that line, the text will be scrolled as configured.
neomatrixcmd,setscroll,<line>,<0|1>
Set scrolling off or on for the text of a specific line of the matrix. When Scroll is enabled the text will be scrolled if it doesn’t fit on the display.
neomatrixcmd,setempty,<line>,<0|1>
Set scrolling with empty start off or on for the text of a specific line of the matrix.
neomatrixcmd,setright,<line>,<0|1>
Set scrolling to right off or on for the text of a specific line of the matrix.
neomatrixcmd,setstep,<line>,<1..16>
Set the scroll step size for a line. Range is from 1 .. 16 pixels.
neomatrixcmd,setspeed,<line>,<1..600>
Set the scroll speed for a line. Range is from 1 .. 600 x 0.1 second (0.1 .. 1 minute/step).
NB: The settings changed via neomatrixcmd,set*... commands will not be reflected in the device configuration!

Generic commands: <trigger> is the command-trigger, documented above.

Generic notes:

  • If a text has comma’s or spaces, then it should be ‘wrapped’ in either double quotes ", single quotes ' or back-ticks `.

  • For color arguments, see how colors can be defined in the txc subcommand description.

  • Commands and subcommands are not case-sensitive.

<trigger>,clear[,<color>]

Clear the screen using last set background color, or a specified color. Background color is either from configuration or txc subcommand.

<trigger>,rot,<rotation>

Rotate the display orientation clock-wise from the initial position, where rotation can be: (current display content will stay as-is!)

  • 0 : No rotation

  • 1 : 90 degrees

  • 2 : 180 degrees

  • 3 : 270 degrees

<trigger>,tpm,<TextPrintMode>

Select the Text print Mode

  • 0 : Continue to next line (wrap text onto the next line)

  • 1 : Truncate exceeding message (cut-off text that won’t fit on the screen width)

  • 2 : Clear then truncate exceeding message (Clear to width of screen, then print the message)

  • 3 : Truncate and center message in available space, when maxTextWidthPixels is provided in txtfull subcommand. Will act like 1 : Truncate exceeding message if no width provided.

<trigger>,txt,<text>

Write simple text (entire rest of the text provided), use last position, color and size. Color is either from configuration or txc subcommand.

<trigger>,txp,<x>,<y>

Set text position (move the cursor). Depending on the setting Text Coordinates in col/row, these coordinates are pixels (default) or column/rows.

<trigger>,txz,<x>,<y>,<text>

Set text position (move the cursor) and print the text. Combines the txp and txt commands in 1. Depending on the setting Text Coordinates in col/row, these coordinates are pixels (default) or column/rows.

<trigger>,txl,[<line>],<text>[,[<line>],<text>...]

Print 1 or more texts on specified lines, starting at column 1. If a <line> is not specified (the comma must still be there!) the next display-line will be used, depending on current font-height, if the initial <line> is not specified, starts at line 1. <line> must be a positive integer value.

Always uses column/rows mode (and restores the currently active pixels or column/rows mode).

<trigger>,txc,<foreColor>[,<backgroundColor>]

Set text color (background is transparent if not provided, or the same as the foreground color).

Colors can be specified in 3 ways:

  • Color name Some named colors are recognized:
    • Full color display: White, Black, Red, Green, Blue, Yellow, Orange, Navy, Darkgreen, Cyan, Darkcyan, Maroon, Purple, Olive, Magenta, Lightgrey, Darkgrey, Pink and Greenyellow.

    • 7-color (eInk) displays: White, Black, Red, Green, Blue, Yellow and Orange

    • Monochrome (eInk, 1 add. color, and 1 or 2-tone greyscale) displays: White, Black, Inverse, Red, Light and Dark

  • #RGB565 A # prefixed, 1 to 4 digit, hex-coded color value in RGB565 format (5 bits red, 6 bits green, 5 bits blue) giving the max. number of 65535 colors.

  • #RRGGBB A # prefixed, 6 digit, hex coded RGB color value. Will be transformed to RGB565!

<trigger>,txs,<size>

Set font scaling option. Only values from 0 to 10 are accepted. 0 assumes 1 by default.

Some display types may limit or extend the maximum accepted size.

<trigger>,txtfull,<x>,<y>,<size=1>,<foreColor=current>,<backColor=foreColor>, <textPrintMode=current>,<maxTextWidthPixels=0>,<text>

Write text at position X/Y with all options. Depending on the setting Text Coordinates in col/row, these coordinates are pixels (default) or column/rows.

All options that have a default specified (size, foreColor, backColor) can be left out, but text is expected. ForeColor and BackColor use the last set Foreground and Background colors (that will by default be white and transparent if not provided).

textPrintMode can be passed an invalid value (f.e. -1) to use the current setting.

maxTextWidthPixels can be used to have textPrintMode > 0 (see tpm subcommand) but clear only a limited area width instead of clearing until the right edge of the screen. 0 implies that the right edge of the screen is used.

<trigger>,asciitable[,<offset>,<fontscaling>]

Show an ascii table on the display, starting at position 0,0. Display is not cleared before drawing the table.

offset is in steps of 32 characters (0x20), and by default starts at 0x80, showing the ‘high ascii’ characters for the current font. Applicable range is -4..3, allowing to view the entire supported character set. The CR (0x0D) and LF (0x0A) characters are replaced by a space to not disturb the table on screen.

fontscaling can be changed, from the default value 2, to enlarge the characters (possibly rendering less characters of the table, hence the offset can be applied). Does not change the current fontscaling setting.

This command is not available in builds that use the LIMIT_BUILD_SIZE compile-time option, as it is intended for debugging/development use.

<trigger>,font,<fontname>

Switch to font. Also applies font settings to recalculate the max. column and row settings.

Depending on compile-time settings, none or multiple fonts are available.

  • default The default 6 * 10 font, includes most of the special characters like degrees centigrade and a few valuta symbols.

Enabled by default, but disabled in memory-challenged builds: (most extra fonts do not include special symbol characters)

  • sevenseg24 A rather large 7-segment 21 * 48 font

  • sevenseg18 A somewhat less large 7-segment 16 * 34 font

  • freesans A sans-serif 10 * 21 font

Usually disabled fonts: (can be enabled in a Custom build, default enabled in the MAX builds)

  • angelina8prop A proportional, handwriting, 6 * 16 font

  • novamono8pt A modern 9 * 16 font

  • unispace8pt A modern 12 * 24 font

  • unispaceitalic8pt A modern italic (slanted) 12 * 24 font

  • whiterabbit8pt A modern 12 * 24 font

  • robotomono8pt A modern 8 * 10 font

  • angelina12prop A proportional, handwriting, 8 * 24 font

  • novamono12pt A modern 13 * 34 font

  • repetitionscrolling12pt A modern 13 * 24 font

  • unispace12pt A modern 13 * 18 font

  • unispaceitalic12pt A modern italic (slanted) 13 * 18 font

  • whiterabbit12pt A modern 13 * 18 font

  • robotomono12pt A modern 13 * 18 font

  • amerikasans16pt A proportional 17 * 20 font

  • whiterabbit16pt A modern 16 * 20 font

  • robotomono16pt A modern 16 * 20 font

  • whiterabbit18pt A modern 18 * 22 font

  • whiterabbit20pt A modern 20 * 24 font

Standard disabled fonts (even on MAX builds), that can be enabled in a custom build:

  • roboto8pt A modern 9 * 16 font (proportionally spaced)

  • roboto12pt A modern 13 * 18 font (proportionally spaced)

  • roboto16pt A modern 16 * 20 font (proportionally spaced)

  • robotocond8pt A modern 9 * 16 font (Roboto Condensed, proportionally spaced)

  • robotocond12pt A modern 13 * 18 font (Roboto Condensed, proportionally spaced)

  • robotocond16pt A modern 16 * 20 font (Roboto Condensed, proportionally spaced)

NB: Roboto is used as the default Android font since Android 4.1, and very readable, even when using small fonts on a small display.

<trigger>,l,<x1>,<y1>,<x2>,<y2>,<color>

Draw a simple line between point x1,y1 and x2,y2, using the (required) color, 1 pixel wide.

<trigger>,lh,<y>,<width>,<color>

Draw a horizontal line (width = Line ‘width’ in pixels (positive = right of first point, negative = left of first point).

<trigger>,lv,<x>,<height>,<color>

Draw a vertical line (height= Line ‘height’ in pixels (positive = below first point, negative = above first point).

<trigger>,lm,<color>,<x1>,<y1>,<x2>,<y2>[,<colorN>][,<xN>,<yN>[,...]|c]

Draw a continuous multi-line between point x1,y1, x2,y2, x3,y3, etc. using the (required) color, 1 pixel wide. The segments of line are drawn straight.

If the last y argument is missing, then the last x argument will be ignored.

If the argument value c is used, the multi-line is closed to the original starting coordinate, and drawing is stopped.

If <colorN> is used, then from the next segment that color will be used. Color can be changed multiple times if desired.

<trigger>,lmr,<color>,<x>,<y>,<dx1>,<dy1>[,<colorN>][,<dxN>,<dyN>[,...]|c]

Draw a continuous multi-line starting at point x,y, moving relatively using the delta-x (dx) and delta-y (dy) values, etc. using the (required) color, 1 pixel wide. The segments of line are drawn straight.

If the last dy argument is missing, then the last dx argument will be ignored.

If the argument value c is used, the multi-line is closed to the original starting coordinate, and drawing is stopped.

If <colorN> is used, then from the next segment that color will be used. Color can be changed multiple times if desired.

<trigger>,r,<x>,<y>,<width>,<height>,<color>

Draw a rectangle.

<trigger>,rf,<x>,<y>,<width>,<height>,<bordercolor>,<innercolor>

Draw a filled rectangle.

<trigger>,c,<x>,<y>,<radius>,<color>

Draw a circle.

<trigger>,cf,<x>,<y>,<radius>,<bordercolor>,<innercolor>

Draw a filled circle.

<trigger>,t,<x1>,<y1>,<x2>,<y2>,<x3>,<y3>,<color>

Draw a triangle.

<trigger>,tf,<x1>,<y1>,<x2>,<y2>,<x3>,<y3>,<bordercolor>,<innercolor>

Draw a filled triangle.

<trigger>,rr,<x>,<y>,<width>,<height>,<corner_radius>,<color>

Draw a rounded rectangle.

<trigger>,rrf,<x>,<y>,<width>,<height>,<corner_radius>,<bordercolor>,<innercolor>

Draw a filled rounded rectangle.

<trigger>,px,<x>,<y>,<color>

Print a single pixel.

<trigger>,pxh,<x>,<y>,<color1>[,<color2>,...]

Print a horizontal chain of colored pixels (left to right, starting at position x,y). Just supply as many colors as pixels that need to be painted.

<trigger>,pxv,<x>,<y>,<color1>[,<color2>,...]

Print a vertical chain of colored pixels (top to bottom, starting at position x,y). Just supply as many colors as pixels that need to be painted.

<trigger>,bmp,<x>,<y>,<filename.bmp>

Display a bmp file (with 24 or 1 bit colors, uncompressed data) with left/top at position x,y, with the current Rotation setting accounted for.

x and/or y can be negative to apply an offset for display. Width or height can not be adjusted, the full width & height of the bitmap are used.

The bitmap overwrites anything that was already displayed in the now overwritten area. After a bitmap is displayed, text/graphics can be placed on top of it using the available text and drawing commands, as listed above. By using the same background color as the foreground color (transparent), the image ‘behind’ the added text/graphics will stay intact.

The file will be read from SD-card, when available, and the bmp file is not found on the internal file storage.

<trigger>,btn,<state>,<mode>,<x>,<y>,<w>,<h>,<id>,<type>,<ONcolor=blue>,<OFFcolor=red>, <CaptionColor=white>,<fontsize>,<ONcaption>,<OFFcaption>,<BorderColor=white>, <DisabledColor=0x9410>,<DisabledCaptionColor=0x5A69>,<TaskIndex>,<Group>, <SelectGroup>,<objectname>

As a companion to the ESPEasy_TouchHelper, the AdafruitGFX_helper takes care of drawing button objects via this subcommand.

All arguments must be provided, though most can be empty, but all separator-commas must still be provided.

  • state : 0 = off, 1 = on, -1 = off + disabled, -2 = on + disabled.

  • mode : 0 = normal, -1 = initial, -2 = clear button area.

  • x,y,w,h : button left-top coordinate, width and height.

  • id : object id nr. Not used for drawing the button, but passed to be used in rules from the ESPEasy_TouchHelper.

  • type : combination (addition/and operation) of button type (bits 0..3) and button layout (bits 4..7), when negative (multiplied by -1) will clear the button area.

    • button types : 0 = none, 0x01 = rectangle, 0x02 = rounded rectangle, 0x03 = circle, 0x04 = left arrow, 0x05 = up arrow, 0x06 = right arrow, 0x07 = down arrow.

    • button layouts : 0 = center aligned, 0x10 = left aligned, 0x20 = top aligned, 0x30 = right aligned, 0x40 = bottom aligned, 0x50 = left top aligned, 0x60 = right top aligned, 0x70 = right bottom aligned, 0x80 = left bottom aligned, 0x90 = no caption, 0xA0 = bitmap (see ONcaption / OFFcaption).

  • ONcolor / OFFcolor : fill color when button state is on or off and enabled.

  • CaptionColor : color used for caption text.

  • fontsize : size of the font for writing the caption, range 1..10.

  • ONcaption / OFFcaption : The caption to show when state is on or off, when empty the objectname will be used. For button layout = bitmap a .bmp filename should be entered, that is available on the filesystem, optionally prefixed with an x and y offset, in pixels, to enable f.e. drawing a small bitmap centered on a button. The format with these optional arguments is: [<x>[,<y>],]bmpfile.bmp

    • If a caption contains space(s), comma(s) or quote(s), it must be quoted with a different quote (double/single/backtick).

    • Captions can use variables as available in rules, like plugin values via [taskname#valuename], %vNN%, %<systemvariable>% and {<function>} formats.

  • BorderColor, DisabledColor, DisabledCaptionColor : A separate border color can be specified, and a fill-color and caption color for disabled buttons.

  • TaskIndex : The Task number for the display the button is to be drawn on. Not used, but passed to be used in rules from the ESPEasy_TouchHelper.

  • Group : The group this button is a member of. Not used for drawing the button, but passed to be used in rules from the ESPEasy_TouchHelper.

  • SelectGroup : The group that will be activated by this button. Not used for drawing the button, but passed to be used in rules from the ESPEasy_TouchHelper.

  • objectname : Required The name of the button object, will be used as a caption if no ONcaption and/or OFFcaption are provided. Not required if both an ONcaption and OFFcaption are provided.

NB: This command wil only draw a button, it will not respond to any action. The action is usually provided by a touch screen like Touch - XPT2046 touchscreen on TFT display and P123_page.

<trigger>,defwin,<x>,<y>,<w>,<h>,<windowId>[,<rotation>]

Example: (Display Task is named st7796, using trigger st77xx)

on window1 do
  if %eventvalue1|1%=1 // on = default
    st77xx,defwin,20,50,390,219,1,1 // Window 1, using rotation 1
    st77xx,win,1 // Select window
    st77xx,rot,1 // Select rotation
    st77xx,clear // Clear area
    st77xx,r,0,0,[st7796#width],[st7796#height],white // Draw a white border
    st77xx,win,0 // Return to Window 0
  else
    asyncevent,removewindow=1 // Remove Window 1
  endif
endon
on removewindow do
  if [st7796#iswin,%eventvalue1|-1%]=1 // Does the Window exist?
    st77xx,win,%eventvalue1% // Select window
    st77xx,clear // Clear area
    st77xx,delwin,%eventvalue1% // Delete Window
    st77xx,win,0 // Return to Window 0
  endif
endon

Define Window.

When enabled, the Window feature of the plugin can be used to define custom areas of the screen as a window. Any printing and drawing can then be limited to that area, having a coordinate system from 0,0 to <w>,<h>.

Window 0 is the default window, having the native size of the display. The coordinates, width and height for the defwin subcommand must be specified in pixels.

  • x,y: The top-left coordinate of the window, according to the native resolution of the screen. This coordinate will become the 0,0 coordinate of the new window.

  • w,h: The width and height of the window.

  • windowId: The Id of the new window, can be any value from 1 to 255. When re-using an Id, the previous definition will be overwritten.

  • rotation: Optional. The rotation, identical to the rot subcommand, that the window dimensions are related to. When not specified, the current rotation setting will be used. Internally, the dimensions are transformed to the dimensions for rotation 0, and on each change of rot, all windows will be re-calculated to have the dimensions corresponding with the new rotation setting.

<trigger>,delwin,<windowId>

Delete Window.

When no longer needed, a window definition can be deleted using this subcommand.

  • windowId: The window Id of a previously defined window.

<trigger>,win,<windowId>

Select Window.

To make a window active, is must be selected using this subcommand.

  • windowId: The window Id of a previously defined window.

Values

Generic variables, available for all AdafruitGFX_Helper enabled plugins, currently: Display - TFT ILI934x/ILI948x, P096_page, Display - ST77xx TFT, Display - NeoPixel Matrix and Display - PCD8544 Nokia 5110 LCD.

Generic notes:

  • If an argument has comma’s or spaces, then that part should be ‘wrapped’ in either double quotes ", single quotes ' or back-ticks `.

  • The <taskname> part is the name of the Device task.

  • True(1)/False(0) values can optionally return -1 to indicate an invalid request, like a missing Window Id.

  • All sizes, lengths etc. are returned in pixels.

[<taskname>#win]

Get the currently active Window Id, expected range: 0..255.

[<taskname>#iswin,<windowId>]

Is the request Window Id valid, expected result: 1 = true, 0 = false.

[<taskname>#width]

Get the width of the currently active Window and rotation, expected range 0..<largest display dimension>.

[<taskname>#height]

Get the height of the currently active Window and rotation, expected range 0..<largest display dimension>.

[<taskname>#length,"<text to measure>"]

Get the length of the text in pixels for the current font and text scaling. Needs quotes if text contains space(s), comma(s) or quote(s).

[<taskname>#textheight,"<text to measure>"]

Get the height of the text in pixels for the current font and text scaling. Needs quotes if the text contains space(s), comma(s) or quote(s).

[<taskname>#rot]

Get the currently active rotation, expected range 0..3 (0 = 0 degrees, 1 = +90 degrees, 2 = +180 degrees, 3 = +270 degrees).

[<taskname>#txs]

Get the currently active text scaling, expected range 1..10, limited to the max. font scaling allowed for the display.

[<taskname>#tpm]

Get the currently active text print mode, expected range 0..3, see the tpm subcommand for details.

Example rules for centering a value (time) in a window:

on centertime do  // NB: Comments & extra spaces should be removed to reduce rules size!
  if [st7796#iswin,%eventvalue1|2%]=1 // default window: 2
    let,120,[st7796#win]              // store current window
    st77xx,win,%eventvalue1|2%        // switch to window
    let,121,[st7796#txs]              // store textscaling
    st77xx,txs,3                      // set text scaling
    let,122,[st7796#rot]              // store rotation
    st77xx,rot,%eventvalue2|0%        // set rotation, default: 0
    let,123,([st7796#width]-[st7796#length,%systm_hm%])/2      // (width - textlength)/2
    let,124,([st7796#height]-[st7796#textheight,%systm_hm%])/2 // (height - textheight)/2
    st77xx,txtfull,[int#123],[int#124],3,red,black,%systm_hm%  // Display time red on black
    st77xx,rot,%v122%                 // restore rotation
    st77xx,txs,%v121%                 // restore text scaling
    st77xx,win,%v120%                 // restore window
  endif
endon
on Clock#Time=All,**:** do
  asyncevent,centertime=2             // Update the display every minute
endon

Display Task is named st7796, using trigger st77xx

Usage: asyncevent,centertime[=<win>[,<rot>]]

Change log

Changed in version 2.0:

added 2022-04-16 New plugin.