Merge branch 'mega' into P021-state_based_extension

docs/source/Plugin/P045.rst

@@ -33,9 +33,9 @@ Configuration
 
 .. image:: P045_DeviceConfiguration.png
 
-**Name** A unique name should be entered here.
+**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.
+**Enabled**: The device can be disabled or enabled. When not enabled the device should not use any resources.
 
 I2C Options 
 ^^^^^^^^^^^^
@@ -47,7 +47,7 @@ The available settings here depend on the build used. At least the **Force Slow
 Device Settings
 ^^^^^^^^^^^^^^^^
 
-* **Function** Select the function this task should perform.
+* **Function**: Select the function this task should perform.
 
 Available options:
 
@@ -61,37 +61,53 @@ When selecting the **Movement detection** function, additional configuration is
 
 The Detection threshold can be configured per X, Y and Z axis (range 0..65535) and will be triggered when it exceeds the set threshold, where the axis is ignored if the threshold is set to 0. An actual threshold can be determined by selecting one of the Acceleration X/Y/Z functions, and making note of the value measured while an expected movement is applied to the sensor.
 
-* **Detection on all 3 axes** When this option is enabled, all 3 axes need to exceed the configured threshold for the counter to be increased. When disabled, only one of the axis need to exceed the threshold to cause an increment.
+* **Detection on all 3 axes**: When this option is enabled, all 3 axes need to exceed the configured threshold for the counter to be increased. When disabled, only one of the axis need to exceed the threshold to cause an increment.
 
-* **Min. detection count** The minimum count of movements during the **Detection window** before the count is reset.
+* **Min. detection count**: The minimum count of movements during the **Detection window** before the count is reset.
 
-* **Detection window** The number of interval passes before the counter is actually increased.
+* **Detection window**: The number of interval passes before the counter is actually increased.
 
 Every 30 seconds a counter for the detection window is increased plus all axis are checked and if they *all* (or any when **Detection on all 3 axes** is unchecked) that are enabled exceeded the threshold values, a counter is increased.
 
 Each period, defined by the **Detection window**, the counter is checked against the **Min. detection count** and if found equal or larger, movement is detected.
 
 If in the next window the **Min. detection count** value is not met, movement has stopped. The **Detection window** cannot be smaller than the **Min. detection count**.
 
+Other measurements
+~~~~~~~~~~~~~~~~~~
+
+When **Function** is set to one of the measurement options, **Range acceleration**, **Acceleration** or **G-force**, the settings related to Movement detection will be hidden:
+
+.. image:: P045_All3ValuesCheckbox.png
+
+* **Provide all 3 values (X/Y/X)**: When unchecked (default), the selected raw X/Y/Z value will be available as the single value in the **Values** section, below. When *checked*, all 3 X, Y and Z values for the selected function will be available in the **Values** section, always in ``X``, ``Y``, ``Z`` order. Most usable would be to name them accordingly.
+
+.. image:: P045_All3Values.png
+
 Data Acquisition
 ^^^^^^^^^^^^^^^^
 
-The Single event with all values, Send to Controller and Interval settings are standard available configuration items. Send to Controller is only shown when one or more Controllers are configured.
+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.
 
-**Interval** By default, Interval will be set to 60 sec. The minimum value allowed is 1 sec.
+**Interval**: By default, Interval will be set to 60 sec. The minimum value allowed is 1 sec.
 
 Values
 ^^^^^^
 
 The measured value or the counter are available here, by default no name is given for the value, as this is usually chosen based on the function. No formula or decimals are available.
 
+In selected builds, per Value a **Stats** and **Hide** checkbox and an **Axis** selection combobox are available, that when Statis is checked, gathers the data and presents recent data, based on the **Interval**, in a graph, as described here: :ref:`Task Value Statistics:  <Task Value Statistics>`
+
 
 Change log
 ----------
 
 .. versionchanged:: 2.0
   ...
 
+  |added|
+  2024-11-03 Checkbox for selecting all 3 X/Y/Z values for a measurement.
+
   |added|
   2022-05-05 Checkbox for selecting ALL or ANY axis movement detection.
 

docs/source/Plugin/P053.rst

@@ -23,145 +23,7 @@ Maintainer: |P053_maintainer|
 
 Used libraries: |P053_usedlibraries|
 
-Introduction
-------------
-
-The Plantower PMSx003 modules are laser based particle sensors.
-
-Particles are measured by blowing air through the enclosure with a laser inside. By measuring diffusion of the laser beam, the amount of particles is counted.
-
-Measurement information is transmitted over a serial interface.
-
-In opposition to the GP2Y10 this sensors have an own microprocessor that does reading and differing into the PM1.0, PM2.5 and PM10 sizes. The values can be read directly from the serial interface.
-
-Units of Measure
-----------------
-
-Dust Particles
-^^^^^^^^^^^^^^
-
-All supported Plantower PMSx003 modules can measure the concentration of dust particles, binned per size of the particle.
-
-The measured values are either in counts per 0.1 liter, or in µg/m3.
-
-To indicate the kind of particles that can be measured by the Plantower sensors:
-
-.. image:: P053_Particulates_chart.png
-
-`Image source <https://forums.adafruit.com/viewtopic.php?f=48&t=136528#p767725>`_
-
-
-The counts per 0.1 liter can be specified in a larger number of bins.
-However, the Plantower particle sensors appear to be estimating particles larger than roughly 2.5 - 3 micron.
-The bins ranging from 0.3 ... 2.5 micron are actually being measured, but the larger ones are estimates.
-This has as side effect that it may not show anything if there are no particles smaller than roughly 3 micron.
-
-Conversion count/100ml to mg/m3
-"""""""""""""""""""""""""""""""
-
-Conversion between counts per volume into weight per volume (e.g. mg/m3) is a bit more complicated than using a single multiplier factor.
-As can be seen in the particle size chart above, the average molecular weight of particles will be different per bin and also there is no such thing as an universal mixture ratio of particles all over the world.
-
-There seem to be standardized conversion factors for:
-
-* PM10  consists of coarse particles that have diameters that are less than or equal to 10 micrometres
-* PM2.5  consists of fine particles with diameters less than or equal to 2.5 micrometres
-* PM1  (particles <= 1 micron)
-
-However, a simple conversion rate is hard to find even though it seems to be standardized.
-What makes it even harder to perform such a conversion from counts per volume to weight per volume is the fact that the Plantower sensors count particles of a specific size and above.
-
-For example:
-
-* PM2.5 is about particles **less than or equal** to 2.5 micrometres
-* cnt2.5/100ml indicates the number of particles with diameter **beyond** 2.5 micrometres in 0.1 L of air. (datasheet Plantower PMS5003)
-
-.. note:: ``PMxx`` values relate to particles **less than or equal** to said size, while count/100ml relates to  particles of **at least** said size.
-   Except when "Split count bins" is checked, then the "count/0.1L" values represent only a single bin.
-
-
-Effects of Humidity
-"""""""""""""""""""
-
-There are some reports suggesting that some particles may stick together causing a shift in the bins.
-For example, if one would draw a histogram of the counted particles per bin, the chart would appear to be shifted a bit to the more larger particles.
-
-.. image:: P053_effect_humidity_measurement.png
-
-`Image source <https://forums.adafruit.com/viewtopic.php?f=48&t=136528#p767725>`_
-
-The apparent size shift vs. humidity is only for soluble particles. 
-Water won't adhere to insoluble particles, so high humidity won't affect particle counts of soot, ash, or most dusts, but it will have an effect with salts (like sea salt spray) or organic compounds.
-
-In some setups this may also make the counted values appear lower, since the sensor can only estimate the particles larger than 3 micron if there are also smaller particles detected.
-When the smaller particles all stick together thus no small particles will be observed by the sensor, the reading may be (much) lower than it actually should be.
-Try to have the sensor running in environments with relatively low humidity (less than 80%).
-
-A very good video describing hazards of dust particles: `Sabine Hossenfelder - How bad is Diesel? <https://www.youtube.com/watch?v=apbS205t53w>`_
-
-Air Quality Index
-"""""""""""""""""
-
-There is a lot of information to be found online about the effects and health issues of exposure to dust particles.
-For example the UK guidelines of average daily exposure on Wikipedia:
-
-.. image:: P053_AirQualityIndex_Wikipedia.png
-
-Source: `Wikipedia - Air Quality Index <https://en.wikipedia.org/wiki/Air_quality_index#United_Kingdom>`_
-
-Such an Air Quality Index can then be used to indicate the maximum exposure (in days per year) which can be considered safe.
-
-A website to check your local air quality: `IQAir <https://www.iqair.com/>`
-
-Temperature/Humidity
-^^^^^^^^^^^^^^^^^^^^
-
-Plantower sensors with ``T`` or ``ST`` in their model name, can also measure temperature and humidity.
-
-It is likely that the modules capable of measuring humidity can also compensate for this humidity when calculating the concentration in µg/m3.
-However, so far it is unclear whether these sensors actually do compensate for this as humidity might cause the smaller particles to stick together.
-But this depends on the type of particles as not all may adhere to water, which makes it almost impossible to have a simple universal compensation factor for humidity.
-
-It is up to the user to interpret (and correct) the data, as the user may have more information on the composition of the measured air.
-
-
-Formaldehyde
-^^^^^^^^^^^^
-
-Plantower sensors with ``S`` or ``ST`` in their model name, can also measure Formaldehyde.
-
-When comparing concentration levels, one may encounter concentrations in ppm or µg/m3.
-
-To compare these, use as conversion factor:  1 ppm = 1.25 mg/m3 (1 atm pressure, 20 degree C)
-
-The Plantower sensors report the concentration in mg/m3.
-
-
-The information below on Formaldehyde is an excerpt of the online found documents, written by `WHO Regional  Office  for Europe,  Copenhagen,  Denmark,  2001 <https://www.euro.who.int/__data/assets/pdf_file/0014/123062/AQG2ndEd_5_8Formaldehyde.pdf>`_
-
-Formaldehyde  is  the  most common aldehyde in the environment. The natural background concentration is < 1 µg/m3  with a mean of about 0.5 µg/m3.
-
-In urban environments, outdoor air concentrations are more variable and depend on local conditions; 
-annual averages are usually  between 1 and 20 µg/m3. 
-
-Short-term peaks,  e.g.  in heavy traffic or during severe inversions, can range up to 100 µg/m3. (0.1 mg/m3)
-The levels of formaldehyde in indoor air are often higher than those in outdoor air. 
-Major sources of formaldehyde in some dwellings are off-gassing of urea–formaldehyde foam insulation, particle board and formaldehyde-based resins. 
-In the early 1980s, mean levels of 490 µg/m3 were measured in mobile homes, with individual measurements as high as several mg/m3 in new mobile homes. 
-Now formaldehyde levels in mobile homes are typically around 100 µg/m3  or less.  
-Mean levels in conventional homes with no urea–formaldehyde foam insulation range from 25 to 60 µg/m3
-
-
-Exposure Guidelines
-"""""""""""""""""""
-
-Formaldehyde has been shown to be toxic in higher concentrations.
-Concentration was more important than dose (concentration × length of exposure)  in  determining  the  cytotoxic  effects of  formaldehyde.
-
-* A short-term (30-minute) guideline of 0.1 mg/m3 is recommended as preventing sensory irritation in the general population.
-* A long-term exposure guideline of 0.21 mg/m3 for the protection of health for long-term effects, including cancer.
-
-Source: `WHO Guidelines for Indoor Air Quality: Selected Pollutants <https://www.ncbi.nlm.nih.gov/books/NBK138711/>`_
+.. include:: P053_P175_common.repl
 
 Supported hardware
 ------------------