Merge branch 'mega' into bugfix/GPS_resolution

README.md

@@ -68,7 +68,7 @@ alt_wifi        | Alternative WiFi configuration     |
 beta            | Arduino Beta release               |
 sdk3            | Arduino SDK v.3                    |
 core_274        | Arduino Core 2.7.4 release         |
-core_302        | Arduino Core 3.0.2 release         |
+core_312        | Arduino Core 3.1.2 release         |
 core_274_sdk3   | Arduino Core 2.7.4 SDK v.3 release |
 
 
@@ -110,7 +110,7 @@ Flash size | Description                 |
 16M1M      | 16 MB with 1 MB filesystem  |
 16M8M      | 16 MB with 8 MB filesystem  |
 
-N.B. Starting with release 2023/12/25, All ESP32 LittleFS builds use IDF 5.1, to support newer ESP32 chips like ESP32-C2 and ESP32-C6 and SPI Ethernet. Other SPIFFS based ESP32 builds will be migrated to LittleFS as SPIFFS is no longer available in IDF 5 and later. A migration plan will be made available in 2024.
+N.B. Starting with release 2023/12/25, All ESP32 LittleFS builds use IDF 5.3, to support newer ESP32 chips like ESP32-C2 and ESP32-C6, and SPI Ethernet. Other SPIFFS based ESP32 builds will be migrated to LittleFS as SPIFFS is no longer officially available in IDF 5 and later. As a temporary solution, a specially crafted IDF 5.1 build that still includes SPIFFS, is used for the SPIFFS builds. A migration plan will be made available in 2025.
 
 *[opt-build-features]* can be any of:
 Build features  | Description                                                                                               |
@@ -140,7 +140,7 @@ ESPEasy_mega-20230822_max_ESP32s3_8M1M_LittleFS_OPI_PSRAM_CDC_ETH.bin | ESP32-S3
 ESPEasy_mega-20230822_max_ESP32_16M1M.bin                             | ESP32 with 16MB flash                           | All available plugins            |
 ESPEasy_mega-20230822_max_ESP32_16M8M_LittleFS_ETH.bin                | ESP32 with 16MB flash, Ethernet                 | All available plugins            |
 
-The binary files for the different ESP32 variants (S2, C3, S3, C2, C6, 'Classic') are available in separate archives.
+The binary files for the different ESP32 variants (S2, C3, S3, C2, C6, Solo1, 'Classic') are available in separate archives.
 
 To see what plugins are included in which collection set, you can find that on the [ESPEasy Plugin overview page](https://espeasy.readthedocs.io/en/latest/Plugin/_Plugin.html)
 

docs/source/Controller/C004.rst

@@ -20,12 +20,125 @@ GitHub: |C004_github|_
 
 Maintainer: |C004_maintainer|
 
+Description
+-----------
+
+The ThingSpeak controller allows to send data to the ThingSpeak web service so it can be presented using the tools available there.
+
+Both free and paid accounts are supported, where a free account has some restrictions like the number of 'Channels' that can be created, and the maximum update-frequency.
+
+Configuration
+-------------
+
+.. image:: C004_ControllerConfiguration.png
+
+* **Protocol**: The selected Controller Protocol.
+
+* **Locate Controller**: This should be set to ``Use Hostname``, this will be forced when data is sent via the controller, but not saved.
+
+* **Controller Hostname**: This should be set to ``api.thingspeak.com``, the only available API entrypoint. No url suffix should be added (at the time of writing this documentation).
+
+* **Controller Port**: The default port number ``80`` should be used.
+
+Controller Queue
+^^^^^^^^^^^^^^^^
+
+* **Minimum Send Interval**: The minimum time to wait before the next set of data can be sent to the controller. This can be set quite high, as the update frequency is not very high, and when sending data in too quick succession, the new data will be ignored. Especially on a free account, only a limited number of updates per day can be sent, so setting this to 600000 msec. (10 minutes) is quite realistic.
+
+* **Max Queue Depth**: Determines the number of elements that can be stored in the queue before new samples are dismissed. When the receiving server is available, the data elements will be sent, emptying the queue, and making room for new samples again. To avoid sending too many messages at once, causing them to be discarded by ThingSpeak, the queue depth should best be set to 1. At the same time, to avoid samples to be discarded by the controller, the Interval for devices using this controller should also be set rather high, in the 20 to 30 minutes range.
+
+* **Max Retries**: Setting is not used for this controller.
+
+* **Full Queue Action**: The controller always uses the ``Ignore New`` strategy when the queue is filled.
+
+* **Allow Expire**: Not applicable for this controller.
+
+* **De-duplicate**: When enabled, avoids sending duplicate data, comparing to what's currently in the send-queue.
+
+* **Check Reply**: The controller always uses the ``Ignore Acknowledgement`` setting.
+
+* **Client Timeout**: The timeout to allow before the connection is failing. As ThingSpeak is an external internet service, a somewhat longer than the default timeout should be used. 1000 msec. should work in most cases, but on very high latency connections, this value can be increased.
+
+Credentials
+^^^^^^^^^^^
+
+* **ThingHTTP Name**: This setting is currently not used for this controller.
+
+* **API Key**: Enter the Write API Key for the channel the data should be sent to. To use multiple channels, an extra ThingSpeak controller should be configured, so a different API Key can be configured.
+
+* **Enabled**: To enable the controller this box has to be checked.
+
+Practical use-cases
+-------------------
+
+As ThingSpeak is a low-frequency external service, only a limited number of updates per day can be sent. For a Free account that's limited to 3 million messages per year, with a minimum interval of 15 seconds, effectively ca. 8000 updates per day. For a paid account it depends on the type of the account used, details and current price information can be found via the `ThingSpeak licensing FAQ <https://thingspeak.com/pages/license_faq>`_
+
+Multiple sensors to a single channel
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To send out data from multiple ESPEasy tasks (max. 4 values) to a single ThingSpeak Channel (max. 8 fields), the data has to be sent at least 15 seconds apart. To avoid losing data that is sent too soon, it's best to control the task 'activation' from rules. A simple round-robin system will do:
+
+.. code-block:: none
+
+  On Clock#Time=All,**:** Do // Once every minute
+    If %v1% = 0
+      TaskRun,BME_280_1  // First BME, Idx 1 (field 1..3)
+    Elseif %v1% = 1
+      TaskRun,BME_280_2 // Second BME, Idx 4 (field 4..6)
+    Elseif %v1% = 2
+      TaskRun,DallasAB // 2 Dallas temperature sensors, Idx 7 (field 7..8)
+    Endif
+    Let 1,%v1%+1 // Next task
+    If %v1% > 2 // All done?
+      Let,1,0 // Reset
+    Endif
+  Endon
+
+All above tasks, ``BME_280_1``, ``BME_280_2`` and ``DallasAB`` should be set to high Interval values, like 600 (every 10 minutes) to avoid them being run unexpectedly.
+
+For adding more than 8 values, a new ThingSpeak Channel should be created, and because each Channel is using a different Write API Key, an extra ThingSpeak Controller should be configured, and extra tasks set up similarly but for the extra controller. ESPEasy allows up to 3 controllers to be configured, that *can* all 3 be ThingSpeak controllers, if needed.
+
+Selected values from multiple sensors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When sending data to a controller via the default task configuration options, all values will be sent to the controller.
+
+If you want to send only a selection of the values to ThingSpeak, an intermediate Dummy Device should be used to store the values to be sent out, and configured to send the data to the ThingSpeak controller. Multiple sensor values can be collected in the Dummy Device, before it is triggered to send out the data.
+
+.. code-block:: none
+
+  On BME_280_1#All Do // Single event with all values can best be enabled for the sensor
+    TaskValueSet,Dummy,1,%eventvalue1%
+    TaskValueSet,Dummy,2,%eventvalue2%
+  Endon
+
+  On BME_280_2#All Do
+    TaskValueSet,Dummy,3,%eventvalue1%
+    TaskValueSet,Dummy,4,%eventvalue2%
+  Endon
+
+  On Clock#Time=All,**:** Do // Once every minute
+    If %v1% = 0
+      TaskRun,Dummy  // Dummy with BME values, Idx 1 (field 1..4)
+    Elseif %v1% = 1
+      TaskRun,DallasABCD // 4 Dallas temperature sensors, Idx 5 (field 5..8)
+    Endif
+    Let 1,%v1%+1 // Next task
+    If %v1% > 1 // All done?
+      Let,1,0 // Reset
+    Endif
+  Endon
+
+The Interval for the BMEs can be set to 10..30 seconds, and the Interval for the Dummy task to 0, as it will be triggered from the minute timer.
+
 Change log
 ----------
 
 .. versionchanged:: 2.0
   ...
 
+  |added| 2024-05-29 Update documentation and add implementation examples.
+
   |added|
   Major overhaul for 2.0 release.
 

docs/source/ESPEasy/ESPchips.rst

@@ -297,7 +297,7 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
       - 20, 21, 22, 24, 25, 26
       - 20, 21, 22, 24, 25, 26
       - 
-      - 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37
+      - N/A
    *  - UART
       - 1.5 (Serial1 out only)
       - 3

docs/source/Plugin/P038.rst

@@ -83,6 +83,9 @@ Change log
 .. versionchanged:: 2.0
   ...
 
+  |improved|
+  2024-12-22: Fix HSV values for ``NeoPixelHSV*`` commands.
+
   |improved|
   2022-01: Make plugin multi-instance compatible, improve/fix pin selection, allow RGBW color selection for ``NeoPixelLine*`` commands.
 

docs/source/Plugin/P038_commands.repl

@@ -30,9 +30,9 @@
     | Set the LED to the provided H/S/V color value.
 
     | led nr: 1..<Led Count>
-    | hue: 0..255
-    | saturation: 0..255
-    | value: 0..255
+    | hue: 0..360
+    | saturation: 0..100
+    | value: 0..100
     "
     "
     | ``NeoPixelAllHSV,<hue>,<saturation>,<value>``

docs/source/Plugin/P097.rst

@@ -24,21 +24,57 @@ Used libraries: |P097_usedlibraries|
 Description
 -----------
 
-Touch pin support for ESP32.
+Touch pin support for ESP32 based devices. (EPS32Classic, ESP32S2, ESP32S3)
+
+The ESP32Classic does have support for 10 touch pads and ESP32S2 and ESP32S3 have support for 14 touch pads.
+
+.. note:: For ESP32S2 and ESP32S3, the touchpad support from ``T10`` to ``T14`` has been disabled due to stability issues.
 
-The ESP32 does have support for 10 touch pads.
 Such a touch pad can be as simple as a wire or a PCB pad connected to 
 one of the GPIO pins labelled with ``T0`` ... ``T9``.
 
-A touch pad pin can be considered as an analog input pin.
-When not touched, the reported value is "High", for example 100.
 
+A touch pad pin can be considered as an analog input pin.
+If the pin is not touched, it will report a relatively high value on an ESP32Classic (e.g. 100) and a relatively low value on an ESP32S2 or ESP32S3 (e.g. 15000) compared to the value when the pin is touched.
+This value is displayed in the settings of the touch plugin ("current pressure") and is reported as the first taskvalue (default name is "touch") whenever the pin is touched or released.
+
+
+Task settings
+~~~~~~~~~~~~~
+
+* **Device**: Name of plugin
+* **Name**: Name of the task
+* **Enable**: Should the task be enabled or not
+
+Device Settings
+^^^^^^^^^^^^^^^
+* **Analog Pin**: Choose the pin to be used
+* **Toggle State**: When the pin is touched, the value of the second taskvalue (default: "state") toggles between 0 and 1.
+* **Send Long Press Event**: A long press event is sent when the pin is pressed for longer than the time specified in the Long Press Time setting. The second taskvalue becomes 10
+* **Long Press Time:**: The time that you need to press the button before the long press event is triggered.
+* **Wake Up from Sleep**: The device will wake up from sleep when the pin is touched.
+
+Touch Settings
+^^^^^^^^^^^^^^
+* **Send Touch Event:**: An event is sent when the pin is touched 
+* **Send Release Event**: An event is sent when the pin is released
+* **Send Duration Event**: After release, the duration of the touch is sent as an event
+* **Touch Threshold**: see Threshold section...
+* **Current Pressure**: The current pressure is the same as the first taskvalue.
+
+Threshold:
+~~~~~~~~~~
+**ESP32Classic**:
 When touched, the capacity of the pin increases, which in return lowers the number of charge/discharge cycles.
-A typical value for a touched pin is lower than 20.
+A typical value for a touched pin is lower than 20, compared to its initial (untouched) value.
+A touch event occurs when the touch value is less than the "base value" minus the threshold value.
 
-The user has to set a threshold value for when to consider a pin being touched.
-The best value has to be determined by trial and error and may differ per use case.
+**ESP32S2** and **ESP32S3**:
+When touched, the pin value increases.
+A typical value for a touched pin is higher than 1500, compared to its initial (untouched) value.
+A touch event occures when the touch value is greater then the "base value" plus the threshold value.
 
+The best value has to be determined by trial and error and may differ per use case.
 
 Events
 ~~~~~~
@@ -53,4 +89,8 @@ Change log
 .. versionchanged:: 2.0
   ...
 
+  |improved| 2024-12-11 Added all settings, a distinction between ESP32 models and the event for <taskvar2>.
+
   |added| 2020-04-25
+
+

docs/source/Plugin/P097_events.repl

@@ -3,15 +3,15 @@
    :widths: 30, 20
 
    "
-   ``<taskname>#<taskvar>``
+   ``<taskname>#<taskvar1>``
 
    The regular events like in every other task. Only difference here is that you may have an event either when the touch pad is touched, released or both.
    ","
 
    .. code-block:: none
 
       on touch#Touch do
-       GPIO,2,1 //LED on
+       LogEntry,'Touch value %eventvalue%'
       endon
 
    "
@@ -39,3 +39,22 @@
       6553655 : Info  : Touch Duration 460 ms
 
    "
+   "
+   ``<taskname>#<taskvar2>``
+
+   An event is sent every time the state of <taskvar2> changes. 
+
+   The state can be either **0** for released, **1** for touched and **10** for long press.
+   ","
+
+   .. code-block:: none
+
+      on touch#State do
+       if %eventvalue% != 10
+         GPIO,2,%eventvalue% //LED on or off 
+       else
+         GPIO,3,1 // on longpress turn on another LED
+       endif
+      endon
+
+   "

docs/source/Plugin/P105.rst

@@ -79,6 +79,9 @@ When selecting the **AHT1x** Sensor model, an extra option is made available:
 
 * **AHT10 Alternative initialization**: Some AHT10 clone sensors do not seem to like the regular AHT10/AHT15 initialization sequence. They do however accept a soft reset command. By enabling this checkbox, only the soft reset is sent to the device. Only available for AHT1x devices.
 
+* **Temperature offset** Depending on the sensor and the location of the sensor, it may be required to apply some temperature compensation. This can be set in steps of 0.1 degree. This also applies a compensation to the **Humidity** reading.
+
+
 Data Acquisition
 ^^^^^^^^^^^^^^^^
 
@@ -97,6 +100,7 @@ Change log
 
 .. versionchanged:: 2.0
   ...
+  |changed| 2024/12/21 Add temperature offset
 
   |changed| 2024-12-03 Add alternative initialization option
 

docs/source/Plugin/P164.rst

@@ -99,7 +99,7 @@ This group of settings, **Single event with all values** and **Send to Controlle
 Values
 ^^^^^^
 
-The plugin provides the ``TVOC`` and ``eCO2`` values. A formula can be set to recalculate. The number of decimals can be set as desired, and defaults to 2.
+The plugin provides the ``TVOC``, ``eCO2`` and ``AQI`` values. A formula can be set to recalculate. The number of decimals can be set as desired, and defaults to 0.
 
 In selected builds, 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>`
 
@@ -112,6 +112,8 @@ Change log
 .. versionchanged:: 2.0
   ...
 
+  |changed| 2024-12-21 Added AQI value
+
   |added|
   2023-12-27 Initial release version.