Merge pull request #4554 from tonhuisman/feature/P036-show-content-on…

…-devices-page

[P036][P023] Show current on-display content on Devices page

docs/source/Plugin/P023.rst

@@ -1,4 +1,4 @@
-.. include:: ../Plugin/_plugin_substitutions_p02x.repl
+.. include:: ../Plugin/_plugin_substitutions_p02x.repl
 .. _P023_page:
 
 |P023_typename|
@@ -21,20 +21,65 @@ Maintainer: |P023_maintainer|
 
 Used libraries: |P023_usedlibraries|
 
-Supported hardware
-------------------
+Description
+-----------
 
-|P023_usedby|
+This plugin features a basic display of a text template, including device values, on black and white OLed displays, using the SSD1306 and SH1106 controllers.
 
-.. Commands available
-.. ^^^^^^^^^^^^^^^^^^
+Configuration
+-------------
 
-.. .. include:: P023_commands.repl
+.. image:: P023_DeviceConfiguration.png
 
-.. Events
-.. ~~~~~~
+* **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.
+
+I2C Options 
+^^^^^^^^^^^^
+
+The available settings here depend on the build used. At least the **Force Slow I2C speed** option is available, but selections for the I2C Multiplexer can also be shown. For details see the :ref:`Hardware_page`
+
+Device Settings
+^^^^^^^^^^^^^^^
+
+.. image:: P023_ControllerOptions.png
+
+* **Controller**: Select the controller chip that is used for the display. There are 2 options available, ``SSD1306`` and ``SH1106``.
+
+.. image:: P023_RotationOptions.png
+
+* **Rotation**: Select if the display is mounted normally or upside-down (rotated 180 degrees).
+
+.. image:: P023_DisplaySizeOptions.png
+
+* **Display Size**: Select the pixel resolution of the display.
+
+.. image:: P023_FontWidthOptions.png
+
+* **Font Width**: The ``Normal`` option uses a mono-spaced font to display the text, where ``Optimized`` is similar to a proportionally spaced font, where each character uses only the pixels it needs.
+
+* **Line 1** .. **Line 8**: All user defined texts may contain references to system variables or task values which will be interpreted when displayed on screen.
+
+For example: ``[bme#Temp#D2.1] {D}C [bme#Hum]%``
+
+
+* **GPIO <- Display button(optional)**: Setting up a ``Display Button``, allows to configure a Display Timeout and wake the display on demand, either by a button, or by using some presence detection.
+
+* **Display Timeout**: The numbers of seconds after which the display is turned off. When set to 0 no timeout is active.
+
+* **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).
+
+
+
+General
+-------
+
+Commands available
+^^^^^^^^^^^^^^^^^^
+
+.. include:: P023_commands.repl
 
-.. .. include:: P023_events.repl
 
 Change log
 ----------

docs/source/Plugin/P023_commands.repl

@@ -0,0 +1,30 @@
+.. csv-table::
+  :header: "Command", "Extra information"
+  :widths: 20, 30
+
+  "
+  ``oledcmd,off``
+  ","
+  Turn the display off.
+  "
+  "
+  ``oledcmd,on``
+  ","
+  Turn the display on.
+  "
+  "
+  ``oledcmd,clear``
+  ","
+  Remove all content from the screen.
+  "
+  "
+  ``oled,<line>,<column>,<content>``
+
+  ``<line>``: The line to place the content on, range: 1..8.
+
+  ``<column>``: The column to start writing the content. The number of characters that can be displayed can vary, depending on the ``Font Width`` setting.
+
+  ``<content>``: The text content to place on the display. Can include system variables, taskvalue references, etc.
+  ","
+  Write a line of text on the display, at the given position.
+  "

docs/source/Plugin/P036.rst

@@ -30,59 +30,116 @@ The Framed OLED plugin does allow a bit more fancy look and feel compared to P02
 The plugin allows to show several "pages or frames" of information.
 The number of pages depends on the number of set lines of text and the font size.
 
-The maximum number of 'Lines per frame' depends on the display size (height).
-Checkbox 'Reduce no. of lines to fit font' (default: off) can be used to reduce the lines per frame to fit the set font for the lines.
-If not checked the maximum used font size is limited.
+Configuration
+-------------
 
-Switching between pages can be "instant" or "scrolling".
-Please note that scrolling may need more resources of the ESP, which can have an effect on other active tasks of the node.
-If 'Disable all scrolling while WiFi is disconnected' is checked switching between the pages is always "instant" and long lines are not scrolling as long as no Wifi connection is established.
-The Wifi connection attempts use a lot of resources and the scrolling looks ugly.
+.. image:: P036_DeviceConfiguration.png
 
-Setting up a 'Display Button', allows to configure a Display Timeout and wake the display on demand.
-'Inversed Logic' should be checked when using a button that connects the input to ground when pressed.
+* **Name**: A unique name should be entered here.
 
-When enabling 'Step through pages with Display button', the button can also be used to step through the pages, when having multiple pages, to display the content on demand. If this option is unchecked, then, when available, the next page will be displayed after Interval seconds have passed. Pressing the button restarts the Display Timeout timer. When holding the button pressed, the next page will be shown after a 1 second delay.
+* **Enabled**: The device can be disabled or enabled. When not enabled the device should not use any resources.
 
-The 'Display Timeout' setting sets the numbers of seconds after which the display is turned off. When set to 0 no timeout is active.
+I2C Options 
+^^^^^^^^^^^^
 
-The plugin allows for a header line, which may show some user selectable information. And an optional footer line that can show a page indicator, when using a 128x64 display.
+The available settings here depend on the build used. At least the **Force Slow I2C speed** option is available, but selections for the I2C Multiplexer can also be shown. For details see the :ref:`Hardware_page`
 
-Checkbox 'Wake display on receiving text' (default: on) allows to not wake up the display when a text is sent from a remote source, and Display Timeout is set.
+Device Settings
+^^^^^^^^^^^^^^^
 
-'Align content (global)' can be used to align all lines, but there are also individual align and font settings for each line. 
+.. image:: P036_ControllerOptions.png
 
-All user defined texts may contain references to system variables or task values which will be interpreted when displayed on screen.
+* **Controller**: Select the controller chip that is used for the display. There are 2 options available, ``SSD1306`` and ``SH1106``.
 
-For example: ``[bme#T#D2.1] {D}C [bme#H]%``
+.. image:: P036_DisplaySizeOptions.png
 
-The user defined texts may also contain a split token '<|>' to display the line splitted, one part on the left the other one on the right side of the display.
+* **Display Size**: Select the pixel resolution of the display.
 
-Depending on the build used (NORMAL and CUSTOM), an option to generate events can be set, that will generate an event if the display is turned on or off, the contrast setting is changed, a new frame is shown, the number of lines per frame is changed or a line is updated using the ``oledframedcmd,<line>,<text>`` command.
+.. image:: P036_RotationOptions.png
 
-The device setting:
+* **Rotation**: Select if the display is mounted normally or upside-down (rotated 180 degrees).
 
-.. image:: P036_GenerateEvents.png
+* **Lines per Frame**: The maximum number of 'Lines per frame' depends on the display size (height). Select from 1..4. This determines the number of frames, so there can be 12 frames of 2 line, 6 frames of 2 lines, 4 frames of 3 lines, or 4 frames of 3 lines.
 
-Available options:
+* **Reduce no. of lines to fit font**: (default: off) can be used to reduce the lines per frame to fit the set font for the lines. If not checked the maximum used font size is limited.
+
+.. image:: P036_ScrollOptions.png
+
+* **Scroll**: Switching between pages can be "instant" or "scrolling". Please note that scrolling will need more resources of the ESP, which can have an effect on other active tasks of the node.
+
+* **GPIO <- Display button**: Setting up a ``Display Button``, allows to configure a Display Timeout and wake the display on demand, either by a button, or by using some presence detection.
+
+.. image:: P036_PinModeOptions.png
+
+* **Pin mode**: Select how the button pin is to be configured, either regular input, using an external pull-up resistor, or using the ESP internal pull-up resistor. When using wiring > 30 cm. an external pull-up resistor of ~10k is advised to be used.
+
+* **Inversed Logic**: Should be checked when using a button that connects the input to ground when pressed. Default a high signal is used to wake the display, as that is the standard output for most IR detection sensors.
+
+* **Step through pages with Display button**: When enabled the button can also be used to step through the pages (frames), when having multiple pages, to display the content on demand. If this option is unchecked, then, when available, the next page will be displayed after Interval seconds have passed. Pressing the button restarts the Display Timeout timer. When holding the button pressed, the next page will be shown after a 1 second delay.
+
+* **Display Timeout**: The numbers of seconds after which the display is turned off. When set to 0 no timeout is active.
+
+.. image:: P036_ContrastOptions.png
+
+* **Contrast**: Select the desired contrast. To prolong the working life of the display, it is advised to use a low/medium contrast level, and turn off the display automatically after some time.
+
+* **Disable all scrolling while WiFi is disconnected**: When checked switching between the pages is always "instant" and long lines are not scrolling as long as no Wifi connection is established. The Wifi connection attempts use a lot of resources and the scrolling may be disturbed by that.
 
 .. image:: P036_GenerateEventsOptions.png
 
+* **Generate Events**: Depending on the build used (NORMAL and CUSTOM), an option to generate events can be set, that will generate an event if the display is turned on or off, the contrast setting is changed, a new frame is shown, the number of lines per frame is changed or a line is updated using the ``oledframedcmd,<line>,<text>`` command.
+
+Content
+^^^^^^^
+
+* **Hide header**: When checked the Header that is normally shown will be suppressed. This will aloow more content on the display, or the content to be displayed in a larger font.
+
+* **Hide indicator**: When checked will not show the page indicator at the bottom of the screen, again to fit more content on the screen or use a larger font. On the 128x32 display this option is always enabled, as that display is rather small.
+
+.. image:: P036_HeaderOptions.png
+
+* **Header** / **Header (alternate)**: The plugin allows for a header line, which may show some user selectable information. When using a different setting for **Header (alternate)**, the header will be updated halfway of the Interval time.
+
+* **Scroll long lines**: When checked, lines that won't fit on the display will be scrolled to be completely shown.
+
+* **Wake display on receiving text**: (default: on) Allows to not wake up the display when a text is sent from a remote source or rules, when Display Timeout is set, by unchecking this option.
+
+Lines
+^^^^^
+
+.. image:: P036_AlignContentOptions.png
+
+* **Align content (global)**: this setting will be used to align all lines that use the **Use global** setting, but there are also individual align and font settings for each line.
+
+* **Line 1..12**: All user defined texts may contain references to system variables or task values which will be interpreted when displayed on screen.
+
+For example: ``[bme#Temperature#D2.1] {D}C [bme#H]%``
+
+The user defined texts may also contain a split token ``<|>`` to display the line splitted, the left part left-aligned and the other part right-aligned on the display. This will override the Alignment setting.
+
+.. image:: P036_ModifyFontOptions.png
+
+* **Modify Font**: For each line, the font to be used can be selected, from the options shown here.
+
+.. image:: P036_AlignmentOptions.png
+
+* **Alignment**: For each line, the alignment to be used can be selected, or the global setting can be used.
+
+* **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).
 
-Supported hardware
-------------------
 
-|P036_usedby|
+General
+-------
 
 Commands available
 ^^^^^^^^^^^^^^^^^^
 
 .. include:: P036_commands.repl
 
-.. Events
-.. ~~~~~~
+Events
+~~~~~~
 
-.. .. include:: P036_events.repl
+.. include:: P036_events.repl
 
 Change log
 ----------

docs/source/Plugin/P036_events.repl

@@ -0,0 +1,29 @@
+.. csv-table::
+  :header: "Event", "Example"
+  :widths: 30, 20
+
+  "
+  ``OLedFramed#display=<on|off>``
+  Will trigger when the display is turned on(1) or off(0).
+  ","
+  "
+  "
+  ``OLedFramed#frame=<framenr>``
+  Will trigger when the displayed frame is changed.
+  ","
+  "
+  "
+  ``OLedFramed#line=<linenr>``
+  Will trigger when a line is updated via the ``OLedFramedCmd,<linenr>,'<content>'`` command.
+  ","
+  "
+  "
+  ``OLedFramed#linecount=<count>``
+  Will trigger when the number of lines to display is changed via the ``OLedFramedCmd,linecount,<count>`` command, and when the display is initialized.
+  ","
+  "
+  "
+  ``OLedFramed#contrast=<contrast>``
+  Will trigger when the contrast of the display is changed.
+  ","
+  "

docs/source/Reference/Command.rst

@@ -267,10 +267,10 @@ P022 :ref:`P022_page`
 .. include:: ../Plugin/P022_commands.repl
 
 
-.. P023 :ref:`P023_page`
-.. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+P023 :ref:`P023_page`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. .. include:: ../Plugin/P023_commands.repl
+.. include:: ../Plugin/P023_commands.repl
 
 
 .. P024 :ref:`P024_page`

docs/source/Reference/Events.rst

@@ -224,10 +224,10 @@ Besides the internal events there's also plugin specific events. These are liste
 .. .. include:: ../Plugin/P035_events.repl
 
 
-.. P036 :ref:`P036_page`
-.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+P036 :ref:`P036_page`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. .. include:: ../Plugin/P036_events.repl
+.. include:: ../Plugin/P036_events.repl
 
 
 .. P037 :ref:`P037_page`

src/Custom-sample.h

@@ -376,6 +376,8 @@ static const char DATA_ESPEASY_DEFAULT_MIN_CSS[] PROGMEM = {
 // #define USES_P033   // Dummy
 // #define USES_P034   // DHT12
 // #define USES_P036   // FrameOLED
+// #define P036_FEATURE_DISPLAY_PREVIEW   1 // Enable Preview feature, shows on-display content on Devices overview page
+// #define P036_FEATURE_ALIGN_PREVIEW     1 // Enable center/right-align feature when preview is enabled (auto-disabled for 1M builds)
 // #define USES_P037   // MQTTImport
 //   #define P037_MAPPING_SUPPORT 1 // Enable Value mapping support
 //   #define P037_FILTER_SUPPORT  1 // Enable filtering support