Merge branch 'mega' into feature/P044-led-and-events-without-client

TD-er · Dec 28, 2023 · 97bb276 · 97bb276
2 parents 68a0578 + 08e1144
commit 97bb276
Show file tree

Hide file tree

Showing 20 changed files with 504 additions and 58 deletions.
diff --git a/docs/source/Plugin/P043.rst b/docs/source/Plugin/P043.rst
@@ -1,4 +1,4 @@
-.. include:: ../Plugin/_plugin_substitutions_p04x.repl
+.. include:: ../Plugin/_plugin_substitutions_p04x.repl
 .. _P043_page:
 
 |P043_typename|
@@ -21,27 +21,87 @@ Maintainer: |P043_maintainer|
 
 Used libraries: |P043_usedlibraries|
 
-Supported hardware
-------------------
-
 |P043_usedby|
 
-.. Commands available
-.. ^^^^^^^^^^^^^^^^^^
+Description
+-----------
+
+Every minute the set schedule will be checked for a match, and if a value for a scheduled time is set, the GPIO will be set to that state (On/Off) when configured, or when no GPIO is configured and the value is not 0 or empty, an event is generated with the field number that caused the trigger, and another event with the set value if the Number Output Values is set to Dual or higher.
+
+Configuration
+-------------
+
+.. image:: P043_DeviceConfiguration.png
+
+* **Name**: Required by ESPEasy, must be unique among the list of available devices/tasks.
+
+* **Enabled**: The device can be disabled or enabled. When not enabled the device should not use any resources.
+
+Sensor
+^^^^^^
+
+* **GPIO -> Clock event** Select a GPIO that will get the stated as configured for the Day,Time. When a GPIO is configured, the allowed valies for a scheduled time will be empty, Off and On only.
+
+Device Settings
+^^^^^^^^^^^^^^^
+
+* **Nr. of Day,Time fields**: Select a number between 1 and 16 for the number of Day,Time fields to be available. Will be applied after the page is submitted. (Default: 8)
+
+* **Value input On/Off only**: When checked, the selection for Value will be for On/Off (or empty) only, to avoid misconfiguration for less experienced users, and the Output variable response the same as if a GPIO was selected. The default is unchecked.
+
+.. image:: P043_GPIO_Enabled.png
+
+* **Day,Time X**: Select the Day and Time that should be checked. For Limited builds the day and time have to be entered manually, for other builds, the Day can be selected from a combobox, and the time can be selected from a predefined list and set to a desired time.
+
+For Day, the available options are All, Sun, Mon, Tue, Wed, Thu, Fri, Sat, Wrk (workday), Wkd (weekend).
 
-.. .. include:: P043_commands.repl
+.. image:: P043_DayOptions.png
 
-.. Events
-.. ~~~~~~
+For time, besides the 24h HH:MM notation, there can also be chosen to use ``%sunrise%`` or ``%sunset%``, optionally with an offset in hours, minutes or seconds like ``%sunrise-1h%`` or ``%sunset+30m%``.
 
-.. .. include:: P043_events.repl
+.. image:: P043_TimeOptions.png
+
+Output Configuration
+^^^^^^^^^^^^^^^^^^^^
+
+* **Number Output Values**: Select Single (default), Dual, Triple or Quad. The Triple and Quad options aren't actually used in this plugin.
+
+Data Acquisition
+^^^^^^^^^^^^^^^^
+
+This group of settings, **Single event with all values** and **Send to Controller** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
+
+Values
+^^^^^^
+
+The default names for the values are named ``Output``, and get a numeric suffix for the Dual, Triple and Quad configuration.
+
+Commands available
+^^^^^^^^^^^^^^^^^^
+
+.. include:: P043_commands.repl
+
+Events
+~~~~~~
+
+.. include:: P043_events.repl
+
+Get Config Values
+^^^^^^^^^^^^^^^^^
+
+Get Config Values retrieves values or settings from the sensor or plugin, and can be used in Rules, Display plugins, Formula's etc. The square brackets **are** part of the variable. Replace ``<taskname>`` by the **Name** of the task.
+
+.. include:: P043_config_values.repl
 
 Change log
 ----------
 
 .. versionchanged:: 2.0
   ...
 
+  |added| 2023-12-16:
+  Selectors for Day and Time, ``%sunrise%`` and ``%sunset%`` support, ``config`` command and get config values.
+
   |added|
   Major overhaul for 2.0 release.
 

diff --git a/docs/source/Plugin/P043_DayOptions.png b/docs/source/Plugin/P043_DayOptions.png
diff --git a/docs/source/Plugin/P043_DeviceConfiguration.png b/docs/source/Plugin/P043_DeviceConfiguration.png
diff --git a/docs/source/Plugin/P043_GPIO_Enabled.png b/docs/source/Plugin/P043_GPIO_Enabled.png
diff --git a/docs/source/Plugin/P043_TimeOptions.png b/docs/source/Plugin/P043_TimeOptions.png
diff --git a/docs/source/Plugin/P043_commands.repl b/docs/source/Plugin/P043_commands.repl
@@ -0,0 +1,33 @@
+.. csv-table::
+    :header: "Command Syntax", "Extra information"
+    :widths: 30, 20
+
+    "
+    | ``config,task,<taskName>,SetTime,<timeIndex>,<timeString>[,<value>]``
+
+    Change the configuration of the plugin for the timeIndex provided:
+
+    ``config,task``: The Config command to change a setting for a task. Not case-sensitive.
+
+    ``<taskName>``: The name of the task to be changed.
+
+    ``SetTime``: Literal command-text recognized by the plugin to set the time and optional value. Not case-sensitive.
+
+    ``<timeIndex>``: The Day,Time fields *number* as shown in the UI. Has to be within the allowed range 1..Nr. of Day,Time field setting.
+
+    ``<timeString>``: A time string as can be entered in the UI, a day (All,Sun, Mon,Tue,Wed,Thu,Fri,Sat,Wrk (workday),Wkd (weekend)) and a time (HH:MM or %Sunrise%/%Sunset%). When configuring for sunrise of sunset, an offset in hours, minutes or seconds can be provided by using ``%sunrise-1h%`` or ``%sunset+30m%`` etc. To avoid the sunrise or sunset time of today to be inserted, instead of ``%`` a ``$`` must be used! If an invalid ``<timeString>`` is provided, ``All,00:00`` will be stored!
+
+    ``<value>``: The value to be set. If a GPIO is configured or the setting 'Value input On/Off only' is enabled, a 0 will configure Off and 1 will configure On. When not using a GPIO or the 'Value input On/Off only' setting is unchecked, the value will be stored as provided. When having value 0 set, **no event will be generated** when this time is triggered!
+    ","
+    This (generic) command allows to update the configuration.
+
+    .. warning:: Every time this command is used, the configuration is saved to flash storage. When changing this often, the flash memory may wear out quickly!
+
+
+
+    Example command to use, when using ``%Sunrise%``/``%Sunset%``:
+
+    - ``config,task,Clock,settime,1,Wrk,$sunrise-1h$,1``
+
+    Will be stored like ``Wrk,%sunrise-1h%`` in Day,Time field 1, and Value set to 1, or ``On`` when having a GPIO configured or **Value input On/Off only** enabled.
+    "
diff --git a/docs/source/Plugin/P043_config_values.repl b/docs/source/Plugin/P043_config_values.repl
@@ -0,0 +1,23 @@
+.. csv-table::
+    :header: "Config value", "Information"
+    :widths: 20, 30
+
+    "
+    ``[<taskname>#GetTimeX]``
+    ","
+    Returns the configured Day,Time string for line X (Range: 1..Nr. of Day,Time fields), as shown in the UI.
+
+    Examples:
+
+    - ``All,06:00``
+    - ``Wrk,%sunset-1h%``
+    "
+    "
+    ``[<taskname>#GetValueX]``
+    ","
+    Returns the configured value for line X (Range: 1..Nr. of Day,Time fields), with a twist:
+
+    If a GPIO is configured, or the setting 'Value input On/Off only' is checked, a 0 is returned for Off and 1 for On (the stored value is actualy 1 higher)
+
+    When no GPIO is configured and the setting 'Value input On/Off only' is unchecked, the shown value is returned.
+    "
diff --git a/docs/source/Plugin/P043_events.repl b/docs/source/Plugin/P043_events.repl
@@ -0,0 +1,14 @@
+.. csv-table::
+  :header: "Event", "Example"
+  :widths: 30, 20
+
+  "
+  ``clock#Output`` The value provided with this event is the field (1..Nr. of Day,Time fields) that was triggered.
+
+  ``clock#Output2`` When the 'Number Output Values' is set to Dual, Triple or Quad, and a GPIO is configured or 'Value input On/Off only' is checked the On (1) or Off (0) value is included as an event argument (``%eventvalue1%``).
+
+  If no GPIO is configured and 'Value input On/Off only' is unchecked, the configured value is provided as ``%eventvalue1%``.
+
+  Events are only generated if the value is not set to 0 or empty.
+  ","
+  "
diff --git a/docs/source/Reference/Command.rst b/docs/source/Reference/Command.rst
@@ -387,10 +387,10 @@ P038 :ref:`P038_page`
 .. .. include:: ../Plugin/P042_commands.repl
 
 
-.. P043 :ref:`P043_page`
-.. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+P043 :ref:`P043_page`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. .. include:: ../Plugin/P043_commands.repl
+.. include:: ../Plugin/P043_commands.repl
 
 
 .. P044 :ref:`P044_page`

diff --git a/docs/source/Reference/Events.rst b/docs/source/Reference/Events.rst
@@ -272,10 +272,10 @@ P037 :ref:`P037_page`
 .. .. include:: ../Plugin/P042_events.repl
 
 
-.. P043 :ref:`P043_page`
-.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+P043 :ref:`P043_page`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. .. include:: ../Plugin/P043_events.repl
+.. include:: ../Plugin/P043_events.repl
 
 
 .. P044 :ref:`P044_page`

diff --git a/platformio_esp82xx_envs.ini b/platformio_esp82xx_envs.ini
@@ -417,7 +417,7 @@ build_flags               = ${normal_ir_extended_no_rx.build_flags}
                             ${esp8266_4M2M.build_flags}
                             ${limited_build_size.build_flags}
                             -DLIMIT_BUILD_SIZE
-                            -DKEEP_RTTTL
+                            ; -DKEEP_RTTTL
 extra_scripts             = ${esp8266_4M2M.extra_scripts}
                             pre:tools/pio/ir_build_check.py