Merge branch 'mega' into feature/esp-now-controller

docs/source/Plugin/P036_commands.repl

@@ -42,6 +42,14 @@
         The line text can also be restored from the settings by the command ``restore``.
 
         All template notations can be used, like system variables, or reference to a task value.
+        They will be interpreted once (while issuing the command) to generate the new line content.
+
+        To use template notations that are to be reinterpreted each time before the line is displayed, the **<line> parameter must be negative**.
+
+        Additionally to the **negative** <line> parameter following conditions must also be met:
+                * use ``\%<sysvar>\%`` instead of ``%<sysvar>%`` for system variables
+                * use ``\[<TaskName>#<TaskValue>\]`` instead of ``[<TaskName>#<TaskValue>]`` for task values
+                * use ``\{some_function\}`` instead of ``{some_function}`` for function calls
 
         After receiving text this way, the frame where the text is placed is shown, if the setting for 'Wake display on receiving text' is checked.
         "
@@ -79,15 +87,21 @@
         ``oledframedcmd,userDef1,'<user Defined Header1>'``
         ","
         Set the user defined header nr. 1 with any desired text value.
+                * use ``\%<sysvar>\%`` instead of ``%<sysvar>%`` for system variables
+                * use ``\[<TaskName>#<TaskValue>\]`` instead of ``[<TaskName>#<TaskValue>]`` for task values
+                * use ``\{some_function\}`` instead of ``{some_function}`` for function calls
 
-        Use ``$<sysvar>$`` instead of ``%<sysvar>%`` to use system variables.
+        **Note:** The use of ``$<sysvar>$`` instead of ``%<sysvar>%`` to use system variables will be deprecated in the near future.
         "
         "
         ``oledframedcmd,userDef2,'<user Defined Header2>'``
         ","
         Set the user defined header nr. 2 with any desired text value.
+                * use ``\%<sysvar>\%`` instead of ``%<sysvar>%`` for system variables
+                * use ``\[<TaskName>#<TaskValue>\]`` instead of ``[<TaskName>#<TaskValue>]`` for task values
+                * use ``\{some_function\}`` instead of ``{some_function}`` for function calls
 
-        Use ``$<sysvar>$`` instead of ``%<sysvar>%`` to use system variables.
+        **Note:** The use of ``$<sysvar>$`` instead of ``%<sysvar>%`` to use system variables will be deprecated in the near future.
         "
         "
         ``oledframedcmd,restore,<line>``

docs/source/Plugin/P113.rst

@@ -28,6 +28,8 @@ This I2C sensor with 2 ranges offers distance measurement based on a Laser Time-
 
 The VL53L1X sensor can measure either 0 - 130cm (Normal range) or 0 - 400cm (Long range), where the closely related VL53L0X can measure up to 200cm. The API's for these sensors are not compatible, so different libraries are used.
 
+The VL53L1X sensor allows for the Region of Interest (ROI) to be configured, resulting in a smaller Field of View (FoV).
+
 Configuration
 --------------
 
@@ -77,6 +79,33 @@ Device Settings
 
 NB: This setting is ignored if 'Send event when value unchanged' is checked!
 
+Region Of Interest (ROI)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+For reducing the Field of View (FoV) angle of the sensor from 27 degrees to a more narrow angle, the number of actually used SPADs (Single Photon Avalance Diode) can be configured, to limit the FoV angle to as low as 15 degrees. See the **Field of View considerations** section, below.
+
+To divert the Optical Center of the selected, rectangle, group of SPADs from the physical center of the sensor, the desired position can be selected from a table, shown below. If the ``x`` or ``y`` ROI settings are set \> 10, the Optical Center index is fixed to index 199, the physical center, by the low-level driver, to ensure that the configured number of SPADs can be used.
+
+* **ROI 'x' SPADs**: Select the number of SPADs in ``x`` direction. Default and max. value is 16, lowest value is 4.
+
+* **ROI 'y' SPADs**: Select the number of SPADs in ``y`` direction. Default and max. value is 16, lowest value is 4.
+
+* **Optical Center index for ROI**: Select the Optical Center index for the ROI area configured. The current Optical Center position is marked in the table by changing the font to Italic and Underscored.
+
+The Region of Interest area can be selected by click&select in the table, shown. The minimum selected area has to cover 4x4 SPADs, else the previous selection will be restored. When selecting an area this way, the values for **ROI x**, **ROI y** and **Optical Center** are updated automatically.
+
+If a ROI of less than 11x11 SPADs is selected, the Optical Center can be changed from the default value 199 (device center). The Optical Center can also be changed via double-click on the desired cell, or by alt-clicking (press the Alt key on the keyboard and click the mouse-button).
+
+When any of the values is changed manually, the selected area in the table will be adjusted to match the current settings.
+
+If a value is selected that's invalid, like when the optical center is too close to the borders of the table, the value(s) will be adjusted as needed, specified in the datasheet of the sensor.
+
+* **Use click-lock**: For touch-only devices, like tablets and mobile phones, where no mouse is available, this checkbox can be enabled to start the selection by the first click on a table-cell, and completing the selection by clicking another cell. The same validations are applied, like minimum 4x4 SPAD selection, and resetting the Optical Center to 199 when either the **ROI x** or **ROI y** values exceed 10 SPADs. The selection-rectangle shown when using click&select ROI selection is not shown for touch-only devices, due to technical limitations. The state of this checkbox is *not* saved.
+
+.. note:: To not overly complicate/expand the used javascript code, ROI selection works from left-top to right-bottom, and not in other directions.
+
+Data Acquisition
+^^^^^^^^^^^^^^^^
 
 The Data Acquisition, Send to Controller and Interval settings are standard available configuration items. Send to Controller only when one or more Controllers are configured.
 
@@ -91,19 +120,49 @@ The Ambient lighting condition during measurement is available in ``Ambient``. T
 
 Value ``Direction`` holds the direction relative to the *previous* distance value: ``-1`` = smaller distance, ``0`` = unchanged distance, ``1`` = greater distance.
 
+In selected builds, per Value are a **Stats** and **Hide** checkbox available, and a coordinate Chart Axis combo, that when Stats is checked, gathers the data and presents recent data in a graph, as described here: :ref:`Task Value Statistics:  <Task Value Statistics>`
+
 .. Events
 .. ~~~~~~
 
 .. .. include:: P113_events.repl
 
+|
+
+Field of View considerations
+----------------------------
+
+An approximation of the FoV for a few ROI configurations:
+
+.. csv-table:: 
+  :header: "ROI zone size (SPADs)", "Diagonal Field of View"
+  :width: 40%
+  :widths: 20, 20
+  :align: left
+
+  "16 x 16", "27° (full FoV)"
+  "8 x 8", "20°"
+  "4 x 4", "15° (smallest)"
 
 
+When using a smaller number of SPADs, the sensitivity, and thus the max. distance range, of the sensor will be reduced. When reducing the number of SPADs to the minimum of 4 x 4, the max. usable distance is ca. 1.7 meter.
+
+The actual Field of View can be seen as a cone, similar to this image:
+
+.. image:: P113_FieldOfView_27deg.png
+
+The light-colored cone in the center of the pink cone is a projection of the theoretical FoV when 4 x 4 SPADs are configured for the ROI. The max. distance available is reduced, as described above.
+
+|
+
 Change log
 ----------
 
 .. versionchanged:: 2.0
   ...
 
+  |added| 2024-07-30 Add configuration and description for ROI and FoV.
+
   |added| 2024-04-27 Add value ``Direction``.
 
   |added| 2021-04-05 Added to main repository as Plugin 113 Distance - VL53L1X (400cm), based on a copy of Plugin 110 Distance - VL53L0X (200cm)

docs/source/Plugin/P163.rst

@@ -0,0 +1,108 @@
+.. include:: ../Plugin/_plugin_substitutions_p16x.repl
+.. _P163_page:
+
+|P163_typename|
+==================================================
+
+|P163_shortinfo|
+
+Plugin details
+--------------
+
+Type: |P163_type|
+
+Name: |P163_name|
+
+Status: |P163_status|
+
+GitHub: |P163_github|_
+
+Maintainer: |P163_maintainer|
+
+Used libraries: |P163_usedlibraries|
+
+Description
+-----------
+
+The RadSens and RadSens mini boards are radiation counters, that provide the counted values via the I2C interface.
+
+.. image:: P163_RadSense-mini.jpg
+  :width: 50%
+  :alt: RadSens mini board
+
+.. warning:: These boards use fairly high voltages (400V or higher) to drive the geiger tube. When operated they should be installed electrically safe to protect the public and operator from harm.
+
+Configuration
+-------------
+
+.. image:: P163_DeviceConfiguration.png
+  :alt: Device configuration
+
+
+* **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.
+
+Dats Source
+^^^^^^^^^^^
+
+* **Remote Unit**: Shows the remote unit, by number and name, where the data originates if the ESPEasy P2P Network is used to transmit sensor data to this units. Remote Unit 0 is shown when no remote unit is configured, and the data is collected from a locally connected sensor (the standard/usual configuration).
+
+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`
+
+Currently, only the default I2C address of ``0x66`` is supported. Multiple sensors can be connected using an I2C multiplexer.
+
+Device Settings
+^^^^^^^^^^^^^^^
+
+* **Read incremental count**: If you want to see the incrementing count over a certain timespan, you can use the Incremental Count value, and after some time, reset the count using the ``radsens,resetcount`` command. When unchecked the number of impulses since the last read is used.
+
+* **Reset after read**: When checked, the incremental counter is reset after reading the value. This counter can also be cleared via the ``radsens,resetcount`` command.
+
+* **Low-power mode**: To use the low power mode of the board, this option can be checked.
+
+* **Enable onboard Led**: By default, the onboard Led of the sensor board shows an indication of the impulses counted. This setting can be used to turn the Led off. (On by default).
+
+* **Events on Count-threshold**: Select the threshold for the Count value to trigger an event. This can avoid the generation of many events if the count changes only slightly. Event generation can be disabled by setting this value to -1.
+
+* **Use Count-average of values**: To make the event triggers more stable, instead of using only the previous value, an averange of the last 'n' measurements can be used to even out the response. The max. number of values depends on the ESP used, for ESP8266: 16, for ESP32: 250.
+
+.. note:: To be able to use the Count-average value, the **Stats** checkbox for the Count value must be enabled. Only the available values will be used for the average, as data from any previous run is not persisted after plugin restart.
+
+Data Acquisition
+^^^^^^^^^^^^^^^^
+
+This group of settings, **Single event with all values**, **Send to Controller** and **Interval** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
+
+* **Interval** By default, Interval will be set to 60 sec. The data will be collected and optionally sent to any configured controllers using this interval.
+
+Values
+^^^^^^
+
+The plugin provides measurements ``Count`` in impulses/microRad, ``iDynamic`` the dynamic radiation intensity \< 123 sec., ``iStatic`` the static radiation intensity, and ``IncrCount``, the incremented counter value since the last reset or restart of the plugin.
+
+Per Value is a **Stats** checkbox available, that when checked, gathers the data and presents recent data in a graph, as described here: :ref:`Task Value Statistics:  <Task Value Statistics>`
+
+To use the Count-average as threshold, the Stats option for ``Count`` has to be enabled.
+
+Commands available
+^^^^^^^^^^^^^^^^^^
+
+.. include:: P163_commands.repl
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  2024-08-13 Initial release version.
+
+
+
+
+

docs/source/Plugin/P163_commands.repl

@@ -0,0 +1,21 @@
+.. csv-table::
+    :header: "Command Syntax", "Extra information"
+    :widths: 20, 30
+
+    "
+    ``radsens,calibration,<value>``
+    ","
+    Change the calibration value for the board in impulses per microrad. Can be used when a different type of geiger tube is installed on the board. The default tube uses 105 imp/uRad.
+    "
+    "
+    ``radsens,highvoltage,<0|1>``
+    ","
+    Enable (``1``) or disable (``0``) the High Voltage generator on the board that powers the geiger tube. When this is turned off, the used power is greatly reduced, but no usable measurements can be retrieved.
+
+    This command can be used when bringing the ESP in sleep mode, and when returning from sleep mode.
+    "
+    "
+    ``radsens,resetcount``
+    ","
+    Clear the incremental count in the sensor driver.
+    "