Merge pull request #5142 from tonhuisman/feature/P175-add-pmsa003i-se…

…nsor

[P175] Add Dust - PMSx003i (I2C) Sensor

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
 ------------------

docs/source/Plugin/P053_P175_common.repl

@@ -0,0 +1,139 @@
+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/>`_