letscontrolit · TD-er · Aug 10, 2022 · Jan 9, 2022 · Jan 9, 2022 · Jan 9, 2022
diff --git a/docs/source/Plugin/AdaGFX_commands.repl b/docs/source/Plugin/AdaGFX_commands.repl
@@ -33,6 +33,7 @@
     * 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>``
@@ -69,11 +70,15 @@
     Set font scaling option. Only values from 0 to 10 are accepted. 0 assumes 1 by default.
     "
     "
-    ``<trigger>,txtfull,<x>,<y>,<size=1>,<foreColor=white>,<backColor=transparent>,<text>``
+    ``<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>]``

diff --git a/docs/source/Plugin/P095.rst b/docs/source/Plugin/P095.rst
@@ -24,21 +24,170 @@ Used libraries: |P095_usedlibraries|
 Description
 -----------
 
-This plugin allow to control a TFT screen (ILI9341) through HTTP API
+The ILI9341, ILI9342, ILI9481, ILI9486 and ILI9488 chip families drive color TFT displays in a few resolutions, and support 65535 colors (RGB565 coded).
 
-## Environment
-Tested with WEMOS D1 Mini Pro and Wemos TDFT 2.4
-Tested with ESPEasy 2.4.2  -tag mega-201902225)
+This plugin supports these display models:
+
+* **ILI934x** with resolution 240 x 320 pixels
+* **ILI948x** with resolution 320 x 480 pixels
+
+The plugin can be configured to show predefined text, a reservation for up to 24 lines is made, but only the lines that can fit on-screen will be shown, or via commands, sent via http or from rules, text or graphical elements like lines, rectangles, circles, pixels, etc., can be shown.
+
+Hardware
+--------
 
 TFT Shield : https://docs.wemos.cc/en/latest/d1_mini_shiled/tft_2_4.html
 Price : ~ 5.40€/$ (https://fr.aliexpress.com/item/32919729730.html)
 
+Connections
+^^^^^^^^^^^
+
+These displays are connected using the SPI interface, minimally with 3 signal wires, though usually also support the ``CS`` signal, so 4-wire SPI can be used, to allow multiple SPI-connected devices.
+
+The text on most displays is somewhat confusing, as not the usual SPI names are used:
+
+.. code-block:: none
+
+  ESP         TFT
+  --------    ------
+  3V3     --- VCC (most displays only support 3.3V)
+  GND     --- GND
+  MOSI    --> SDA/SDI
+  CLK     --> SCL/SCK
+  (gpio)  --> DC
+  (gpio)  --> CS
+  (gpio)  --> RES/RST/RESET (optional, Reset)
+  (gpio)  --> BLK/LED (optional, Backlight, TFT-pin can also be connected to VCC for always-on)
+
+  (gpio) = configurable GPIO pin.
+
+
+Device configuration
+--------------------
+
+.. image:: P095_DeviceConfiguration.png
+   :alt: Device configuration
+
+* **Name** A unique name should be entered here.
+
+* **Enabled** The device can be disabled or enabled. When not enabled the device should not use any resources.
+
+Actuator
+^^^^^^^^
+
+* **GPIO -> TFT CS** Select the GPIO pin to use for the ``CS`` connection. If the display doesn't have a ``CS`` connection it can be set to *None*.
+* **GPIO -> TFT DC** The GPIO pin to use for the ``DC`` connection (Data/Command).
+* **GPIO -> TFT RST** Select the GPIO pin to use for the ``RES`` (reset) connection. If the display doesn't have a ``RES`` (or RST) connection, or no free pin is available, it can be set to *None*. If it is set to None, for proper operation it may need too be wired to the Reset connection on the ESP, so the device is initialized correctly.
+* **GPIO -> Backlight (optional)** Select the GPIO pin to use for controlling the backlight. To save power, the backlight can be dimmed, or turned off if the display is turned off. If set to *None*, usually the max. brightness is used for the backlight.
+* **Backlight percentage** The backlight can be controlled via PWM modulation on the Backlight (BLK) pin of the display. This is set as a percentage between 1 and 100.
+* **Display button** A GPIO pin can be configured to wake the display on demand. This, combined with the **Display Timeout** setting, can preserve the lifetime of the display, and save some power.
+* **Inversed Logic** When checked, reverses the pin-state action of the **Display button** gpio. This allows an external circuit, f.e. an IR sensor, that may provide a *high* signal when activated, to wake the display.
+* **Display Timeout** Select the timeout in seconds to turn off the display after the last update or wake-up. Only used if the **Display button** is *also* configured.
+* **TFT Display model** Select the hardware model that is connected. Currently there are only preset resolutions available.
+
+Available options:
+
+.. image:: P095_TFTDisplayModelOptions.png
+   :alt: TFT Display model options
+
+.. warning:: 
+   The **ILI9481** display controller does have issues when rotating, by using the ``<trigger>,rot,<n>`` command, to change the display orientation after some content is already displayed on the screen (content may move, rotate and/or mirror unexpectedly). It is advised to clear the screen after changing the rotation setting.
+
+Layout
+^^^^^^^^
+
+* **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:
+
+.. image:: P095_RotationOptions.png
+   :alt: Rotation
+
+The available options rotate the display in a clock-wise direction.
+
+* **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:
+
+.. image:: P095_TextPrintModeOptions.png
+   :alt: 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* 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 end of the display, then display the provided message, but any excess at the right border of the display is discarded.
+* *Truncate, centered if maxWidth set* Like *Truncate exceeding message* but centered in available width when that is provided (in ``txtfull`` subcommand).
+
+Default setting is *Continue to next line*.
 
+* **Font scaling** The scaling factor for the currently active font. Select a factor between 1 and 10.
 
-Supported hardware
-------------------
+* **Show splash on start** When available, and enabled, will show an ESPEasy & plugin name text-splash during start of the plugin. If also some content is configured, this will be written over the splash, as that is not cleared after being displayed.
 
-|P095_usedby|
+* **Clear display on exit** When checked, will clear the display when the task is disabled, either from settings or via the ``TaskDisable`` command. The screen will be turned off, and when a backlight pin is configured, also the backlight is turned off.
+
+* **Write Command trigger** The command to handle any commands for this device can be selected here. This can make the commands compatible with other (tft) displays, using the same command structure via the ESPEasy Adafruit Graphics helper class.
+
+Available options:
+
+.. image:: P095_WriteCommandTriggerOptions.png
+   :alt: Write-command trigger
+
+* *tft*
+* *ili9341*
+* *ili9342*
+* *ili9481*
+* *ili9486*
+* *ili9488*
+
+The command is handled non-case sensitive. See below for available commands and subcommands.
+
+* **Wake display on receiving text** When checked, the display will be enabled once any content is written to the screen, either triggered by the Interval, or from a command. Default checked.
+
+* **Text Coordinates in col/row** When checked, the coordinates for the ``txp``, ``txz`` and ``txtfull`` subcommands will be handled in cursor columns & rows, instead of pixels. Column and row are calculated from the current font size and font scaling settings.
+
+* **Use -1px offset for txp & txtfull** For backward compatibility with the previous, non-AdafruitGFX_helper based, plugin implementation, that used 0-based coordinates, an offset of -1 pixel can be applied to the ``txp``, ``txz`` and ``txtfull`` subcommands. This option is enabled by default.
+
+* **Background-fill for text** When checked, for any text-line sent to the screen, the entire background (including top and bottom lines) will have the provided background color, *unless* transparent is used (Background color == Foreground color). Default checked.
+
+Content
+^^^^^^^^
+
+* **Foreground color**
+* **Background color**
+
+These are the default colors, used to display the content as configured below (if any). The background color is also used as the Clear screen color.
+
+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!
+
+If the Foreground and Background colors are the same, the background color will become ``transparent``. If the Forground color is empty, as a default ``white`` will be set.
+
+* **Line 1..24** Predefined content can be specified. The number of lines available depends on the size of the display, the font used, the font scaling that is set and the selected rotation.
+
+The usual variables, like ``[Taskname#Valuename]``, or ``%v1%``, system variables, formulas and functions can be used.
+
+Input length is limited to 60 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.
+
+Next to Line 24, 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:
+
+.. image:: P095_SaveError.png
+   :alt: 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.
+
+Values
+^^^^^^
+
+The current text-cursor position is available in 2 variables **CursorX** and **CursorY**, that will be updated on every change of text or received command. **No** events are generated, and these values will never be sent to controllers.
+
+The values can be used in rules, if desired. They will follow the **Text Coordinates in col/row** setting.
 
 Commands available
 ^^^^^^^^^^^^^^^^^^
@@ -54,4 +203,6 @@ Change log
 .. versionchanged:: 2.0
   ...
 
-  |added| 2020-04-20
+  |added| 2020-04-20 Initially added
+
+  |added| 2022-04-23 Rewrite of the plugin based on AdafruitGFX_helper, udated documentation based on shared settings with :ref:`P116_page` and AdafruitGFX_helper
diff --git a/docs/source/Plugin/P095_DeviceConfiguration.png b/docs/source/Plugin/P095_DeviceConfiguration.png
diff --git a/docs/source/Plugin/P095_RotationOptions.png b/docs/source/Plugin/P095_RotationOptions.png
diff --git a/docs/source/Plugin/P095_SaveError.png b/docs/source/Plugin/P095_SaveError.png
diff --git a/docs/source/Plugin/P095_TFTDisplayModelOptions.png b/docs/source/Plugin/P095_TFTDisplayModelOptions.png
diff --git a/docs/source/Plugin/P095_TextPrintModeOptions.png b/docs/source/Plugin/P095_TextPrintModeOptions.png
diff --git a/docs/source/Plugin/P095_WriteCommandTriggerOptions.png b/docs/source/Plugin/P095_WriteCommandTriggerOptions.png
diff --git a/docs/source/Plugin/P095_commands.repl b/docs/source/Plugin/P095_commands.repl
@@ -1,69 +1,40 @@
 .. csv-table::
-   :header: "Command", "Extra information"
-   :widths: 20, 30
-
-   "
-   ``TFTCMD,<tftcmd_subcommand>``
-   ","
-   Control the screen (on, off, clear,..) 
-
-   Examples:
-
-   - ``tftcmd,on``           Switch display on.
-   - ``tftcmd,off``          Switch display off.
-   - ``tftcmd,clear``        Clear whole display.
-   - ``tftcmd,clear,green``  Clear whole display with green color.
-   - ``tftcmd,inv,1``        Invert the dispaly (value:0 normal display, 1 inverted display)
-   - ``tftcmd,rot,2``        Rotate display (value from 0 to 3 inclusive) 
-   "
-   "
-   ``TFT,<tft_subcommand>,....``
-   ","
-   Draw line, rect, circle, triangle and text
-
-   Subcommands:
-
-   - ``tft,txt,<text>``  Write simple text (use last position, color and size)
-   - ``tft,txp,<X>,<Y>``  Set text position (move the cursor)
-   - ``tft,txc,<foreColor>,<backgroundColor>``  Set text color (background is transparent if not provided
-   - ``tft,txs,<SIZE>``  Set text size
-   - ``tft,txtfull,<row>,<col>,<size=1>,<foreColor=white>,<backColor=black>,<text>``  Write text with all options
-   - ``tft,l,<x1>,<y1>,<2>,<y2>,<color>``  Draw a simple line
-   - ``tft,lh,<y>,<width>,<color>``  Draw an horizontal line (width = Line width in pixels (positive = right of first point, negative = point of first corner).
-   - ``tft,lv,<x>,<height>,<color>``  Draw a vertical line (height= Line height in pixels (positive = below first point, negative = above first point).
-   - ``tft,r,<x>,<y>,<width>,<height>,<color>``  Draw a rectangle
-   - ``tft,rf,<x>,<y>,<width>,<height>,<bordercolor>,<innercolor>``  Draw a filled rectangle
-   - ``tft,c,<x>,<y>,<radius>,<color>``  Draw a circle
-   - ``tft,cf,<x>,<y>,<radius>,<bordercolor>,<innercolor>``  Draw a filled circle
-   - ``tft,t,<x1>,<y1>,<x2>,<y2>,<x3>,<y3>,<color>`` Draw a triangle
-   - ``tft,tf,<x1>,<y1>,<x2>,<y2>,<x3>,<y3>,<bordercolor>,<innercolor>``  Draw a filled triangle
-   - ``tft,rr,<x>,<y>,<width>,<height>,<corner_radius>,<color>``  Draw a round rectangle
-   - ``tft,rrf,<x>,<y>,<width>,<height>,<corner_radius>,<bordercolor>,<innercolor>``  Draw a filled round rectangle
-   - ``tft,px,<x>,<y>,<color>``  Print a single pixel
-   - ``tft,font,<fontname>``  Switch to font - SEVENSEG24, SEVENSEG18, FREESANS, DEFAULT
-   "
-
-Examples:
-
-Write Text :
-    ``tft,txtfull,0,0,HelloWorld``
-
-Write Text another place:
-    ``tft,txtfull,100,40,HelloWorld``
-
-Write bigger Text :
-    ``tft,txtfull,0,0,3,HelloWorld``
-
-Write RED Text :
-    ``tft,txtfull,0,0,3,HelloWorld``
-
-Write RED Text (size is 1):
-    ``tft,txtfull,0,0,1,RED,HelloWorld``
-
-Write RED Text on YELLOW background (size is 1):
-    ``tft,txtfull,0,0,1,RED,YELLOW,HelloWorld``
-
-Select font :
-
-- ``tft,font,SEVENSEG24`` 
-- ``tft,txtfull,0,0,1,RED,17.0``
+    :header: "Command Syntax", "Extra information"
+    :widths: 20, 30
+
+    "
+    This plugin allows dynamic configuration of the command-trigger. Available triggers are:
+
+    * ``tft``
+    * ``ili9341``
+    * ``ili9342``
+    * ``ili9481``
+    * ``ili9486``
+    * ``ili9488``
+
+    The default trigger is ``tft``
+    ","
+    Some commands are postfixed with ``cmd``, indicating device specific commands. Not device-specific commands are genericly applicable to all *Adafruit Graphics* enabled devices, using the ESPEasy ``AdafruitGFX_helper`` module.
+
+    If one of the alternative **Write Command trigger** options is selected, then also the plugin specific commands change from ``tftcmd`` to f.e. ``ili9481cmd``.
+    "
+    "
+    | ``tftcmd,on``
+    ","
+    | Switch the display on.
+    "
+    "
+    | ``tftcmd,off``
+    ","
+    | Switch the display off. If the Backlight is connected and configured, that will also be turned off.
+    "
+    "
+    | ``tftcmd,clear``
+    ","
+    | Clear the display, using the default background color.
+    "
+    "
+    | ``tftcmd,backlight,<percentage>``
+    ","
+    | Set the level of backlight brightness, from 1..100%. Only applicable if a backlight pin is configured.
+    "
diff --git a/docs/source/Plugin/_plugin_substitutions_p09x.repl b/docs/source/Plugin/_plugin_substitutions_p09x.repl
@@ -59,9 +59,9 @@
 .. |P094_compileinfo| replace:: `.`
 .. |P094_usedlibraries| replace:: `.`
 
-.. |P095_name| replace:: :cyan:`TFT 2.4 inches ILI9341`
+.. |P095_name| replace:: :cyan:`TFT ILI934x/ILI948x`
 .. |P095_type| replace:: :cyan:`Display`
-.. |P095_typename| replace:: :cyan:`Display - TFT 2.4 inches ILI9341`
+.. |P095_typename| replace:: :cyan:`Display - TFT ILI934x/ILI948x`
 .. |P095_porttype| replace:: `.`
 .. |P095_status| replace:: :yellow:`DISPLAY, COLLECTION`
 .. |P095_github| replace:: _P095_ILI9341.ino
@@ -70,7 +70,7 @@
 .. |P095_shortinfo| replace:: `.`
 .. |P095_maintainer| replace:: `TD-er`
 .. |P095_compileinfo| replace:: `.`
-.. |P095_usedlibraries| replace:: `Adafruit GFX, Adafruit ILI9341`
+.. |P095_usedlibraries| replace:: `Adafruit GFX, Adafruit ILI9341 (locally extended copy)`
 
 .. |P097_name| replace:: :cyan:`Touch ESP32`
 .. |P097_type| replace:: :cyan:`Internal`

diff --git a/lib/Adafruit_ILI9341/.gitignore b/lib/Adafruit_ILI9341/.gitignore
@@ -0,0 +1,4 @@
+# Our handy .gitignore for automation ease
+Doxyfile*
+doxygen_sqlite3.db
+html