Merge branch 'mega' of https://github.com/letscontrolit/ESPEasy into feature/Documentation-updates-Q3-2025

docs/source/Plugin/DataAcquisition.repl

@@ -22,7 +22,7 @@ Depending on the controller capabilities, some configuration settings may be sho
 
 .. image:: Task_config_page_Controllers_section.png
 
-All configured Controllers are shown here, including their enabled or disabled state (only a single MQTT Controller can be enabled at one time).
+All configured Controllers are shown here, including the enabled or disabled state (multiple Controllers can be enabled, only a single MQTT Controller can be enabled at one time!).
 
 For each controller the user can select wether the data should be sent on each Interval (or explicit TaskRun).
 
@@ -30,12 +30,14 @@ For the Domoticz controllers the value index (IDX) has to be configured.
 
 For some controllers, like Home Assistant/openHAB, there are extra options available.
 
-* **Group**: This represents the group id to combine all values from multiple tasks into a single grouped-device during MQTT AutoDiscovery. Groups, by design, can span multiple ESPEasy devices, if desired, as long as the Task/Valuename combinations are unique. If a group should only combine Tasks from a single ESPEasy unit, the group id should be unique across multiple ESPEasy units. The group description, default *Group <n>*, can be adjusted in Home Assistant.
+* **Group**: This represents the group id to combine all values from multiple tasks into a single grouped-device during MQTT AutoDiscovery. Groups, by design, can span multiple ESPEasy devices, if desired, as long as the Task/Valuename combinations are unique. If a group should only combine Tasks from a single ESPEasy unit, the group id should be unique across multiple ESPEasy units. The group description, default *Group <n>*, can be adjusted in Home Assistant. If the Group value matches the current Unit nr, the Unit name, ``%sysname%``, is used instead of Group <nr>.
+
+* **Retained**: For MQTT Controllers, this setting can be enabled to send the values for the current task with the Retain flag set. The **Publish Retain flag** in the Controller settings will override this by sending *all* task values with Retain flag enabled.
 
 * **Send derived**: This checkbox determines if any configured Derived values should also be sent to the controller (and included in the AutoDiscovery if that's available and enabled).
 
-* **Resend MQTT Discovery**: When checked, will start a resend of the MQTT Discovery process for this task after a random delay, when Submit is clicked, so any chenged settings can be updated in the MQTT server. This setting is only available if the controller is enabled, the Auto Discovery feature is available and enabled for the controller. This setting is not stored.
+* **Resend MQTT Discovery**: When checked, will start a resend of the MQTT Discovery process for this task after a random delay, when Submit is clicked, so any changed settings will be updated in the MQTT broker. This setting is only available if the controller is enabled, the Auto Discovery feature is available and enabled for the controller. This setting is not stored.
 
-Other controllers, like FHEM HTTP, do not support additional settings besides the checkbox to enable sending the data.
+Other controllers, like f.e. FHEM HTTP, do not support additional settings besides the checkbox to enable sending the data.
 
 |

docs/source/Plugin/P037.rst

@@ -179,7 +179,7 @@ The number of mappings is currently limited to 25, but only the number of used m
 Option: Generate events for accepted topics
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* **Generate events for accepted topics**: Enabling this option will generate an event for every incoming, and accepted if Filtering is used, non-JSON payload even when that has a non-numeric value. The event generated is: ``<devicename>#<valuename>=<value>``, for example ``MQTT_Import#Value1=on``.
+* **Generate events for accepted topics**: Enabling this option will generate an event for every incoming, and accepted if Filtering is used, non-JSON payload even when that has a non-numeric value. The event generated is: ``<devicename>#<valuename>=<value>``, for example ``MQTT_Import#Value1=on``. When the ``<value>`` is numeric, the configured number of decimals is applied to the value.
 
 When this option is disabled it has the backward-compatible behavior of discarding that message as invalid.
 

docs/source/Plugin/P056.rst

@@ -23,28 +23,52 @@ Maintainer: |P056_maintainer|
 
 Used libraries: |P056_usedlibraries|
 
-Supported hardware
-------------------
+Introduction
+------------
 
-|P056_usedby|
+A dust sensor will measure the dust concentration of the surrounding air. Depending on the device, different particle sizes can be measured, and the SDS series provides values for up to 2.5 and up to 10 micrometer particle size.
+
+Multiple sensors can be used independently on a single ESP unit, as long as the serial port setup is uniquely configured.
+
+
+Device
+------
+
+.. image:: P056_DeviceConfiguration.png
+
+
+Task settings
+~~~~~~~~~~~~~
+
+* **Name** The name of the task. This should be unique for all devices that are configured. (Initially empty)
+
+* **Enabled** For the device to work it has to be enabled. When checked, the device will be started as soon as the ESP starts. If desired, the device can also be enabled from f.e. a rule by using the ``TaskEnable,<tasknr>`` or ``TaskEnable,<taskname>`` command, or disabled using the corresponding ``TaskDisable,<tasknr>|<taskname>`` commands.
 
 Sensor
-^^^^^^
+~~~~~~
 
 See: :ref:`SerialHelper_page`
 
+Device Settings
+~~~~~~~~~~~~~~~
 
-**TODO**: Complete this documentation...
+* **Sleep time**: Numeric value to set the sleep time between measurements. The laser used in the sensor has an aproximated life time of 8000 hours of on-time. When enabled continuously, this number will be reached in about 333 days, so less than a year! To prolong the lifetime, a sleep interval can be configured, during which the laser will be turned on, and then turned off for ``<sleeptime>*60-30`` seconds. Range = 0 (continuous) or 1 .. 30 seconds.
 
-.. Commands available
-.. ^^^^^^^^^^^^^^^^^^
+This setting is only available if the optional **ESP TX GPIO** pin is configured correctly, as it involves sending a command to the sensor.
 
-.. .. include:: P056_commands.repl
 
-.. Events
-.. ~~~~~~
+.. include:: DataAcquisition.repl
 
-.. .. include:: P056_events.repl
+* **Interval**: By default, Interval will be set to 60 sec for this plugin. It is the frequency used to read sensor values and send these to any Controllers configured for this device. Values will *only* be sent if data is successfully received from the sensor.
+
+Values
+~~~~~~
+
+The measured values are available in ``PM2.5`` and ``PM10``.
+
+For a complete description of all available columns see the `Plugin - Values <_Plugin.html#values>`_ section.
+
+|
 
 Change log
 ----------
@@ -52,6 +76,9 @@ Change log
 .. versionchanged:: 2.0
   ...
 
+  |changed|
+  2025-08-05: Enable multiple instances of the plugin, and update the documentation.
+
   |added|
   Major overhaul for 2.0 release.
 
@@ -61,7 +88,3 @@ Change log
   |added|
   Initial release version.
 
-
-
-
-

docs/source/Plugin/P089.rst

@@ -40,6 +40,16 @@ Device Settings
 
 * **Hostname**: The hostname or IP-address for the device or host to monitor.
 
+**ESP32 only:**
+
+* **Ping count**: The number of pings that should be tried before reporting a failure. (Only available on ESP32 builds)
+
+* **Available Values**: The default is to only have a **Fails** value available, but for ESP32 there is also the Average ping-time in msec. available.
+
+.. image:: P089_AvailableValuesOptions.png
+
+When changing this setting, the page will save and reload to adjust for the change in **Values**, below.
+
 .. include:: DataAcquisition.repl
 
 * **Interval** By default, Interval will be set to 60 sec. Every Interval setting, the host will be pinged and the state will be updated in Fails. If the ping responds as intended, then Fails is reset to 0.
@@ -47,7 +57,9 @@ Device Settings
 Values
 ^^^^^^
 
-The failure count value is available in ``Fails``. No other options are available for Values.
+The failure count value is available in ``Fails``. On ESP32 there is an option to also show the average ping-time in msec. via ``Avg_ms``.
+
+On ESP32, 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>`
 
 
 
@@ -64,6 +76,8 @@ Change log
 .. versionchanged:: 2.0
   ...
 
+  |added| 2025-08-26 Enable support for ESP32
+
   |changed| 2023-03-14 Extended command handling to not require the taskname argument.
 
   |added| 2020-02-22 

docs/source/Plugin/P168.rst

@@ -53,15 +53,9 @@ Device Settings
 .. image:: P168_LuxReadMethodOptions.png
   :alt: Lux read-method options
 
-* *Normal*: Normal read mode, will report the uncorrected ``Lux`` value.
+* *Normal (no wait)*: Normal read mode, will report the uncorrected ``Lux`` value, doesn't wait for the sensor to complete a measurement, but retrieves it later after starting the read.
 
-* *Corrected*: Corrected read mode, Raw calculated to ``Lux`` and corrected for non-linearity.
-
-* *Auto*: Show the corrected value, auto-scaled with Gain factor and Integration time to avoid measuring errors because of over-exposing the sensor. This is the default setting.
-
-* *Normal (no wait)*: Normal read mode, will report the uncorrected ``Lux`` value, doesn't wait for the sensor to complete a measurement.
-
-* *Corrected (no wait)*: Corrected read mode, Raw calculated to ``Lux`` and corrected for non-linearity, doesn't wait for the sensor to complete a measurement.
+* *Corrected (no wait)*: Corrected read mode, Raw calculated to ``Lux`` and corrected for non-linearity, doesn't wait for the sensor to complete a measurement, but retrieves it later after starting the read.
 
 | 
 
@@ -75,8 +69,6 @@ Device Settings
 
 .. image:: P168_IntegrationTimeOptions.png
 
-.. warning:: When the **Lux Read-method** is set to *Auto* the Gain factor and Integration time settings are ignored.
-
 * **Power Save Mode**: The sensor can go into Power Save Mode on several levels, to conserve power when used in a battery operated device. When in power save mode, the integration time increases.
 
 .. image:: P168_PowerSaveModeOptions.png

docs/source/Plugin/_Plugin.rst

@@ -247,13 +247,13 @@ On selected builds (ESP32 only, can be enabled in ESP8266 Custom builds) per val
 
 If set the UoM will be space-appended to the value when displayed on the Devices page, used in the labels for the Stats display, and later used in the MQTT AutoDiscovery messages so the receiving server can use that for presentation. When set it is also included in the JSON output as ``UoM`` per taskvalue, available at the ``/json`` endpoint of the ESP, to be used by external systems like EasyFetch.
 
-A list of 150+ Unit of Measure values is available (derived of what's supported by Home Assistant):
+A list of 165+ Unit of Measure values is available (derived of what's supported/expected by Home Assistant):
 
 ``°C, °F, K, %, Pa, hPa, bar, mbar, inHg, psi, W, kW, V, Wh, kWh, A, VA, mm, cm, m, km,`` ``L, mL, m³, ft³, m³/h, ft³/h, lx, UV index, µg/m³, mg/m³, p/m³, ppm, ppb,``
 ``°, €, $, ¢, µs, ms, s, min, h, d, w, m, y, in, ft, yd, mi, Hz, GHz, gal, fl. oz, m²,`` ``g, kg, mg, µg, oz, lb, µS/cm, W/m², mm/h, mm/s, in/s, m/s, in/h, km/h, mph, db, dBm,``
 ``bit, kbit, Mbit, Gbit, B, kB, MB, GB, TB, PB, EB, ZB, YB, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB,`` ``bit/s, kbit/s, Mbit/s, Gbit/s, B/s, kB/s, MB/s, GB/s, KiB/s, MiB/s, GiB/s,``
 ``ft/s, kn, mW, MW, GW, TW, BTU/(h·ft²), pH, cbar, mmHg, kPa, mA, µA, mV, µV, kV, cm², km², mm²,`` ``in², ft², yd², mi², ac, ha, kHz, MHz, mWh, MWh, GWh, TWh, cal, kcal, Mcal,``
-``Gcal, J, kJ, MJ, GJ, var, kvar, varh, kvarh, st, mg/dL, mmol/L, µSv, µSv/h, m³/s, ft³/min,`` ``L/h, L/min, L/s, gal/min, mL/s``
+``Gcal, J, kJ, MJ, GJ, var, kvar, varh, kvarh, st, mg/dL, mmol/L, µSv, µSv/h, m³/s, ft³/min,`` ``L/h, L/min, L/s, gal/min, mL/s, g/m³, kWh/100km, Wh/km, mi/kWh, km/kWh, in/d, mm/d``
 
 Displaying the Unit of Measure in the Devices overview page can be disabled by unchecking the **Show Unit of Measure** checkbox on the Tools/Advanced page.
 
@@ -275,19 +275,19 @@ Available options, grouped per category:
 
 **Basic**: ``Single``
 
-**Environment**: ``Temp¹, Hum¹, Baro¹, Wind speed¹``
+**Environment**: ``Temp¹, Hum¹, Baro¹, Wind speed¹, Absolute humidity¹, Atmospheric pressure¹, Precipitation¹,`` ``Precipitation intensity¹``
 
-**Dust/Gases**: ``Dust PM2.5¹, Dust PM1.0¹, Dust PM10¹, (e)CO2¹, TVOC¹, AQI¹, NOx¹``
+**Dust/Gases**: ``Dust PM2.5¹, Dust PM1.0¹, Dust PM10¹, (e)CO2¹, CO¹, TVOC¹, VOC parts¹, AQI¹, NOx¹,`` ``Gas¹, N2O¹, Ozone¹, SO2¹``
 
-**Energy**: ``Voltage¹, Current¹, Power Usage¹, Power Factor¹, Apparent Power Usage¹, Reactive Power¹``
+**Energy**: ``Voltage¹, Current¹, Power Usage¹, Power Factor¹, Apparent Power Usage¹,`` ``Reactive Power¹, Reactive Energy¹, Energy¹, Energy storage¹, Energy distance¹``
 
 **Time**: ``Duration¹, Date¹, Timestamp¹``
 
-**Size**: ``Analog, Distance¹, Direction¹, Moisture¹, GPS, Weight¹, Data rate¹, Data size¹, Sound pressure¹, Signal strength¹``
+**Size**: ``Analog, Distance¹, Direction¹, Moisture¹, GPS, Weight¹, Data rate¹, Data size¹, Sound pressure¹, Signal strength¹,`` ``Volume¹, Volume flow rate¹, Volume storage¹, Water¹``
 
 **Light**: ``Lux¹, UV¹, UV Index¹, IR¹, Red¹, Green¹, Blue¹, Color temperature¹``
 
-**Other**: ``Switch¹, Switch (inv.)¹, Dimmer, String, UInt32 (1x), Int32 (1x), UInt64 (1x), Int64 (1x), Double (1x)``
+**Other**: ``Switch¹, Switch (inv.)¹, Dimmer, String, UInt32 (1x), Int32 (1x), UInt64 (1x), Int64 (1x), Double (1x), Frequency¹``
 
 Value Types marked with ``¹`` are supported for use in MQTT AutoDiscovery.
 
@@ -299,6 +299,16 @@ Here's a partial preview (the 'None' value is selected):
 
 .. image:: Task_config_page_ValueType_selector_part.png
 
+MQTT State Class
+^^^^^^^^^^^^^^^^
+
+For some Value Types a State Class can be provided in the MQTT Discovery configuration. By default this setting is empty, but for (mostly Energy related) this can be configured for:
+
+* *Measurement*
+* *Measurement-angle*
+* *Total*
+* *Total-increasing*
+
 |
 
 .. _Plugin List:

docs/source/Plugin/_plugin_substitutions_p07x.repl

@@ -110,7 +110,7 @@
 .. |P078_status| replace:: :yellow:`ENERGY`
 .. |P078_github| replace:: P078_Eastron.ino
 .. _P078_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P078_Eastron.ino
-.. |P078_usedby| replace:: `Modbus variants of Eastron SDM120M, SDM120CT, SDM220M, SDM230M, SDM72M, SDM72CTM, SDM630, SDM630MCT, SDM630-EV, SDM54-M, SDM320Y, DDM18SD, SMART X-96, MCS-U22, TAiYEDQ TAC2100 `
+.. |P078_usedby| replace:: `Modbus variants of Eastron SDM120M, SDM120CT, SDM220M, SDM230M, SDM72M, SDM72CTM, SDM630, SDM630MCT, SDM630-EV, SDM54-M, SDM320Y, DDM18SD, SMART X-96, MCS-U22, TAiYEDQ TAC2100`
 .. |P078_shortinfo| replace:: `.`
 .. |P078_maintainer| replace:: TD-er
 .. |P078_compileinfo| replace:: `.`

docs/source/Plugin/_plugin_substitutions_p08x.repl

@@ -119,11 +119,11 @@
 .. |P089_type| replace:: :cyan:`Communication`
 .. |P089_typename| replace:: :cyan:`Communication - Ping`
 .. |P089_porttype| replace:: `.`
-.. |P089_status| replace:: :yellow:`COLLECTION`
+.. |P089_status| replace:: :yellow:`COLLECTION` :yellow:`CLIMATE` :yellow:`ENERGY` :yellow:`NEOPIXEL`
 .. |P089_github| replace:: P089_Ping.ino
 .. _P089_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P089_Ping.ino
 .. |P089_usedby| replace:: `.`
 .. |P089_shortinfo| replace:: `.`
-.. |P089_maintainer| replace:: `TD-er`
+.. |P089_maintainer| replace:: `TD-er tonhuisman`
 .. |P089_compileinfo| replace:: `.`
-.. |P089_usedlibraries| replace:: `.`
+.. |P089_usedlibraries| replace:: `ESPping (ESP32)`