Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[P104] Add Dot subcommand to draw individual dots in a zone #4762

Merged
merged 5 commits into from
Sep 17, 2023
Merged

[P104] Add Dot subcommand to draw individual dots in a zone #4762

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0be0f49
[P104] Add Dot subcommand to draw individual dots in a zone
tonhuisman Aug 13, 2023
af847f4
[P104] Update documentation
tonhuisman Aug 13, 2023
ff18247
[P104] Code improvements and a bugfix
tonhuisman Aug 13, 2023
4b8d2ad
Merge branch 'mega' into feature/P104-add-dot-subcommand
tonhuisman Aug 18, 2023
795c3c0
Merge branch 'mega' into feature/P104-add-dot-subcommand
tonhuisman Aug 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 33 additions & 31 deletions docs/source/Plugin/P104.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ This specific hardware setup can be somewhat confusing when initially setting up
Zones
~~~~~~

A Zone is a set of modules, electrically adjecent to each other, that can be configured to display a sinlge type of content. A zone consists of at least 1 and max. 255 modules.
A Zone is a set of modules, electrically adjacent to each other, that can be configured to display a single type of content. A zone consists of at least 1 and max. 255 modules.

There is at least 1 zone, up to 8 zones can be configured on an ESP8266, and up to 16 zones on an ESP32. This limitation for ESP8266 is related to the amount of memory used by the libraries and the plugin.

Expand Down Expand Up @@ -90,19 +90,19 @@ After adding the plugin to the Devices page, the configuration is shown: (Name w
Task settings
~~~~~~~~~~~~~~

* **Name** The name of the task. This should be unique for all devices that are configured. (Initially empty)
* **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.
* **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 -> CS** Select the GPIO pin that's wired to the ``CS`` input on the first MAX72xx module.
* **GPIO -> CS**: Select the GPIO pin that's wired to the ``CS`` input on the first MAX72xx module.

Device settings
~~~~~~~~~~~~~~~~

* **Hardware type** Selects the type of hardware.
* **Hardware type**: Selects the type of hardware.

The list of available types is:

Expand All @@ -117,45 +117,45 @@ All modules I ordered from Aliexpress so far work with the ``FC16`` hardware typ

If multiple modules are to be connected daisy-chained, they all need to be of the same hardware type, as the Parola library that is used doesn't support different hardware types per zone. When multiple hardware types are to be used, then a separate Task (Devices tab) can be created matching those settings, and a separate GPIO pin should be configured for the ``CS`` pin.

* **Clear display on disable** When enabled, the display will be cleared when the task is disabled.
* **Clear display on disable**: When enabled, the display will be cleared when the task is disabled.

* **Log all displayed text (info)** When enabled, all content that is displayed, also when the Repeat option is used, are logged at Info level. The content will only be visible in the log if that is at Info level, or a more detailed level, configurable on the Tools/Advanced page.
* **Log all displayed text (info)**: When enabled, all content that is displayed, also when the Repeat option is used, are logged at Info level. The content will only be visible in the log if that is at Info level, or a more detailed level, configurable on the Tools/Advanced page.

Content options
~~~~~~~~~~~~~~~~

The content options are global to all zones.

* **Clock with flashing colon** When enabled, the Clock content options will show a flashing colon between the Hour and Minute digits (1 second on, 1 second off). Enabled by default.
* **Clock with flashing colon**: When enabled, the Clock content options will show a flashing colon between the Hour and Minute digits (1 second on, 1 second off). Enabled by default.

* **Clock 12h display** When enabled, the Clock content options will use 12 hour display, instead of 24 hour.
* **Clock 12h display**: When enabled, the Clock content options will use 12 hour display, instead of 24 hour.

* **Clock 12h AM/PM display** When enabled, with also **Clock 12h display** enabled, will suffix the Clock content with ``a`` for AM and ``p`` for PM time.
* **Clock 12h AM/PM display**: When enabled, with also **Clock 12h display** enabled, will suffix the Clock content with ``a`` for AM and ``p`` for PM time.

* **Date format** Select the type of display for all Date and Date/time content types.
* **Date format**: Select the type of display for all Date and Date/time content types.

Available options:

.. image:: P104_DateFormatOptions.png
:alt: Date format options

* **Date separator** Select the separator to use for Date content types.
* **Date separator**: Select the separator to use for Date content types.

Available options:

.. image:: P104_DateSeparatorOptions.png
:alt: Date separator options

* **Year uses 4 digits** When enabled, the Date yr and Date/time content types use a 4 digit year display instead of 2 digits.
* **Year uses 4 digits**: When enabled, the Date yr and Date/time content types use a 4 digit year display instead of 2 digits.

*(NB: On some challenged bin-size builds these Content options can be unavailable, then default settings will be used.)*

Zones
~~~~~~

* **Zones** Select the number of zones you want to configure. Adding or deleting a zone can also be done using the Actions column (when available). The maximum number of zones depends on the type of ESP used, on ESP8266 between 1 and 8 zones can be configured, and on ESP32, up to 16 zones can be set. When changing the number of zones, the page will be reloaded to reflect the new configuration.
* **Zones**: Select the number of zones you want to configure. Adding or deleting a zone can also be done using the Actions column (when available). The maximum number of zones depends on the type of ESP used, on ESP8266 between 1 and 8 zones can be configured, and on ESP32, up to 16 zones can be set. When changing the number of zones, the page will be reloaded to reflect the new configuration.

* **Zone order** As described above, the logical ordering of the modules is from bottom right to top left. For a more intuitive display of the zones, they can be shown from high to low instead of in numeric, low to high, order. The Actions column does take this setting into account when Add above or Add below is selected. When changing the Zone order, the page will be reloaded to show the zones in the new order.
* **Zone order**: As described above, the logical ordering of the modules is from bottom right to top left. For a more intuitive display of the zones, they can be shown from high to low instead of in numeric, low to high, order. The Actions column does take this setting into account when Add above or Add below is selected. When changing the Zone order, the page will be reloaded to show the zones in the new order.

Available choices:

Expand All @@ -167,11 +167,11 @@ Zone configuration

For each Zone there are a number of settings that can be configured.

* **Modules** The number of modules that are in this zone. The maximum that can be set here is 255.
* **Modules**: The number of modules that are in this zone. The maximum that can be set here is 255.

* **Text** If a pre-defined text should be displayed for the zone, it can be set here. The usual variables and functions, as shown on the Tools/System Variables page can be used, as well as the ``[Task#<variable>]`` and ``[Var#<n>]``, ``[Int#<n>]`` and ``%v<n>%`` variables. The system variables that produce special characters, like ``{D}`` etc., actually generate Unicode characters, and that is not supported by the, ASCII based, fonts used. To use any special characters look them up in the font tables, below, to have the desired characters displayed. This field is also used by the Bar graph content type for any predefined bar graph display. Maximum length of this field is 100 characters. If longer contents needs to be set, it can be set from the rules using the ``DotMatrix,<zone>,txt,"<text content>"`` command. (``txt`` and ``settxt`` subcommands).
* **Text**: If a pre-defined text should be displayed for the zone, it can be set here. The usual variables and functions, as shown on the Tools/System Variables page can be used, as well as the ``[Task#<variable>]`` and ``[Var#<n>]``, ``[Int#<n>]`` and ``%v<n>%`` variables. The system variables that produce special characters, like ``{D}`` etc., actually generate Unicode characters, and that is not supported by the, ASCII based, fonts used. To use any special characters look them up in the font tables, below, to have the desired characters displayed. This field is also used by the Bar graph content type for any predefined bar graph display. Maximum length of this field is 100 characters. If longer contents needs to be set, it can be set from the rules using the ``DotMatrix,<zone>,txt,"<text content>"`` command. (``txt`` and ``settxt`` subcommands).

* **Content** Select the type of content shown in the zone.
* **Content**: Select the type of content shown in the zone.

This are the available options:

Expand All @@ -193,16 +193,16 @@ Content types can not be combined in a single zone.

Content type: Bar graph: See below in the Commands section for a full description of the graph string options.

* **Alignment** The alignment of the content, except Bar graph, selected for the zone.
* **Alignment**: The alignment of the content, except Bar graph, selected for the zone.

Available options:

.. image:: P104_ZoneAlignmentOptions.png
:alt: Zone alignment options

* **Animation In** The animation that is used to put the content into the zone. Default is Print, that just puts the content according to the alignment, in the zone. Animation option None is not available for **Animation In**, as the zone would not display anything.
* **Animation In**: The animation that is used to put the content into the zone. Default is Print, that just puts the content according to the alignment, in the zone. Animation option None is not available for **Animation In**, as the zone would not display anything.

* **Animation Out** The animation used to 'remove' the content from the zone. If set to None (the default), the content will stay in the zone until it is changed, or updated when the **Repeat (sec)** option is used.
* **Animation Out**: The animation used to 'remove' the content from the zone. If set to None (the default), the content will stay in the zone until it is changed, or updated when the **Repeat (sec)** option is used.

Available options:

Expand All @@ -216,11 +216,11 @@ The exact effect of each animation can best be seen by experimenting with them.

Some animations are marked with an asterisk ``*`` as a warning that they should not be combined with a **Special Effects** setting that is *also* marked with an asterisk. The result is undefined, and may result in a distorted display.

* **Speed** The speed setting is used to control the speed factor of the animation in the zone in milliseconds. It is used for both the In and Out animations. When set to 0, the delay between each animation step is ~25 msec.
* **Speed**: The speed setting is used to control the speed factor of the animation in the zone in milliseconds. It is used for both the In and Out animations. When set to 0, the delay between each animation step is ~25 msec.

* **Pause** The delay after completing the **Animation In** before starting the **Animation Out**, in milliseconds. If no Out animation is set, this still adds to the time of completing the animation (before a next Repeat would be started).
* **Pause**: The delay after completing the **Animation In** before starting the **Animation Out**, in milliseconds. If no Out animation is set, this still adds to the time of completing the animation (before a next Repeat would be started).

* **Font** The font used to display the content. A few special fonts are available, allowing special characters to be displayed, and also a double-height font can be used to create a larger display where two similar zones are physically mounted above each other (as shown in the image in the Description section). When using a double-height font, also the **Layout** option should be set accordingly, and the **Content** setting should be the same, as well as any text. Bar graphs do not use a font, so when set for a zone, the **Font** and **Layout** settings are ignored.
* **Font**: The font used to display the content. A few special fonts are available, allowing special characters to be displayed, and also a double-height font can be used to create a larger display where two similar zones are physically mounted above each other (as shown in the image in the Description section). When using a double-height font, also the **Layout** option should be set accordingly, and the **Content** setting should be the same, as well as any text. Bar graphs do not use a font, so when set for a zone, the **Font** and **Layout** settings are ignored.

Available options:

Expand All @@ -247,7 +247,7 @@ Font overview:

.. spacer

* **Layout** Determines wether the standard layout should be used, or the Upper/Lower part of a double-height font.
* **Layout**: Determines wether the standard layout should be used, or the Upper/Lower part of a double-height font.

Available options:

Expand All @@ -260,7 +260,7 @@ Available options:

.. spacer

* **Inverted** With the Inverted option the text or bargraph on the display is either light on a dark background (Normal) or black on a light background (Inverted).
* **Inverted**: With the Inverted option the text or bargraph on the display is either light on a dark background (Normal) or black on a light background (Inverted).

.. warning::

Expand All @@ -276,7 +276,7 @@ Available options:

.. spacer

* **Special Effects** These effects can be used to turn a display 'upside down', in left/right 'mirror-image' or both.
* **Special Effects**: These effects can be used to turn a display 'upside down', in left/right 'mirror-image' or both.

Available options:

Expand All @@ -290,11 +290,11 @@ Available options:

.. spacer

* **Offset** The offset can be used to skip a number of modules before a zone, f.e. when displaying a smaller zone on a larger set of displays, or when a module has a defect. A value between 0 and 254 kan be used here.
* **Offset**: The offset can be used to skip a number of modules before a zone, f.e. when displaying a smaller zone on a larger set of displays, or when a module has a defect. A value between 0 and 254 kan be used here.

.. spacer

* **Brightness** Sets the brightness of the display, and thus highly influences the power required by a zone. Valid values are from 0 to 15, where 0 is very dimmed, and 15 is *very* bright (though that might differ per unit).
* **Brightness**: Sets the brightness of the display, and thus highly influences the power required by a zone. Valid values are from 0 to 15, where 0 is very dimmed, and 15 is *very* bright (though that might differ per unit).

Measurements have been done to determine the current per pixel, when used at 5V:

Expand All @@ -314,11 +314,11 @@ Measurements have been done to determine the current per pixel, when used at 5V:

(Other brightness levels can be interpolated)

* **Repeat (sec)** Allows to repeat the current content of a zone to be redisplayed, using the animations as configured. Value is in seconds accuracy. The default value -1 indicates that repeat is disabled for the zone.
* **Repeat (sec)**: Allows to repeat the current content of a zone to be redisplayed, using the animations as configured. Value is in seconds accuracy. The default value -1 indicates that repeat is disabled for the zone.

This will also repeat any content (usually *Text* or *Bar graph*) that is set using the corresponding commands (see below), or refresh a *Bar graph* on a regular interval. The initially set content is re-evaluated before it's displayed.

* **Action** These actions are related to changing the configuration of zones, not related to the display or content of a zones.
* **Action**: These actions are related to changing the configuration of zones, not related to the display or content of a zones.

Available actions:

Expand Down Expand Up @@ -347,4 +347,6 @@ Change log
.. versionchanged:: 2.0
...

|added| 2023-08-13 Add ``Dot`` subcommand.

|added| 2020-06-13 Initial version for ESPEasy.
17 changes: 17 additions & 0 deletions docs/source/Plugin/P104_commands.repl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,3 +190,20 @@
+-- Zero-point

"
"
``DotMatrix,Dot,<zone>,<r>,<c>[,0][,...]``

``r`` Row coordinate, range 1..8.

``c`` Column coordinate, range 1..8 x module-count.

``0`` Optional zero value to turn the dot off.
","
Draw individual dots on the display, in a row/column fashion, where an optional 0 can be added to turn a dot off, as the default is to turn a dot on. The row/column data doesn't have to be quoted.

The row and colum have to stay within the confines of the zone. Each zone is 8 dots high, and a multiple of 8 dots wide, depending on the number of modules in the zone.

While drawing the dots, the zone is paused, so there is no animation effect while drawing the dots.

Dots can be drawn independent of the type of content set for the zone, but once the original content is being updated or redrawn, the dots will be overwritten.
"
17 changes: 11 additions & 6 deletions src/_P104_max7219_Dotmatrix.ino
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,16 @@
// 2: dotted line, alternating, only if the bar is wider than 1 pixel
// Up to 8 graph-strings can be provided and must be separated by a pipe |
// The bar width is determined by the number of graph-strings
// dot,<zone>,<r>,<c>[,0][,...] : Draw dot(s) at the row/column positions provided, adding a 0 after a coordinate will turn that dot off.
// Default is to turn a dot On (no argument needed).
// Row/col must fit within the zone (r = 1..8, c = 1..8 * modules), double-height parts are separate zones!
// Display of the selected zone is suspended until all provided dots are drawn. No quotes are needed around
// the coordinate set.
//
// History:
// 2023-08-13 tonhuisman: Add Dot subcommand for pixel-drawing in a zone. Can be applied on any type of zone (so can be overwritten by the
// original content when that's updated...)
// Set default Hardware type to FC16, as that's the most used for modules found on Aliexpress
// 2023-03-07 tonhuisman: Parse text to display without trimming off leading and trailing spaces
// 2022-08-12 tonhuisman: Remove [DEVELOPMENT] tag
// 2021-10-03 tonhuisman: Add Inverted option per zone
Expand Down Expand Up @@ -138,7 +146,8 @@ boolean Plugin_104(uint8_t function, struct EventStruct *event, String& string)
}

case PLUGIN_SET_DEFAULTS: {
CONFIG_PORT = -1;
CONFIG_PORT = -1;
P104_CONFIG_HARDWARETYPE = static_cast<int>(MD_MAX72XX::moduleType_t::FC16_HW);
break;
}

Expand Down Expand Up @@ -243,11 +252,7 @@ boolean Plugin_104(uint8_t function, struct EventStruct *event, String& string)
# ifdef P104_DEBUG

if (loglevelActiveFor(LOG_LEVEL_INFO)) {
String log;
log.reserve(38);
log = F("dotmatrix: PLUGIN_INIT numDevices: ");
log += numDevices;
addLogMove(LOG_LEVEL_INFO, log);
addLogMove(LOG_LEVEL_INFO, concat(F("dotmatrix: PLUGIN_INIT numDevices: "), numDevices));
}
# endif // ifdef P104_DEBUG

Expand Down
Loading