Air Quality telemetry in Node-RED flows

docs/configuration/node-red-config.md

@@ -74,15 +74,16 @@ The config file is loaded whenever the TM flows restart.  It is located in the u
 It is _not necessary_ to copy this full configuration file. Default values are specified below.
 {% endhint %}
 
-<pre class="language-yaml"><code class="lang-yaml"><strong>########
-</strong><strong># This file contains configuration settings executed by node-red
-</strong><strong># Note: Comments will be removed by updates from node-red
-</strong><strong>########
-</strong><strong>
-</strong><strong># Optional: IoT hub backend integration
-</strong><strong>thingsboard:
-</strong><strong>    # Optional: enable connection to backend thingsboard server (default: shown below)
-</strong>    enabled: False
+```yml
+########
+# This file contains configuration settings executed by node-red
+# Note: Comments will be removed by updates from node-red
+########
+
+# Optional: IoT hub backend integration
+thingsboard:
+    # Optional: enable connection to backend thingsboard server (default: shown below)
+    enabled: false
     # Required: host name, without protocol or port number
     host: tb.server.com
     # Required: thingsboard telemetry protocol (default: shown below), 
@@ -114,15 +115,15 @@ deployment:
     bearing:
 
 sensors:
-<strong>    # Optional: if used, must match the Frigate camera name(s)
-</strong>    # if not set, no cameras will be used
+    # Optional: if used, must match the Frigate camera name(s)
+    # if not set, no cameras will be used
     cameras:
         # camera name must match Frigate configuration camera names
         picam_h264:
             # Optional Enable/disable the camera (default: shown below).
             # if disabled, any Frigate events for specified camera will be ignored
             # Note: this will not impact Frigate's system
-            enabled: False
+            enabled: false
             # Optional: define the radar co-located with camera to associate speeds
             # camera and radar direction and field of view (FOV) should match
             # Note: name needs to match one defined in `radars` section
@@ -135,15 +136,18 @@ sensors:
         # Names are used to associate readings with cameras and other sensors
         TM_RADAR_SERIAL_PORT_00:
             # Optional: Enable/disable the radar (default: shown below).
-            enabled: False
+            enabled: false
 
-    # Optional: used to specify air quality monitor sensors
+    # Optional: used to specify air quality monitor sensor name(s)
     # Note: air quality configuration file is separate from the node-red config, based on the aq device
-    aq_monitor:
-        # Optional: Enable/disable the AQ sensor payloads (default: shown below).
-        enabled: False
-        # mqtt topic to subscribe for incoming telemetry from sensors
-        mqtt_topic_incoming: aq/readings
+    airquality_monitors:
+        # Required: aq sensor name must match AQ configuration -defined MQTT topic middle element (second element)
+        sensorname01:
+            # Optional: Enable/disable the AQ sensor payloads (default: shown below).
+            enabled: false
+            # Required: mqtt topic to subscribe for incoming full-payload telemetry from AQ sensor
+            #  must be last element in mqtt topic defined in AQ configuration
+            mqtt_topic_incoming: readings
 
 time:
     # Optional: Set a timezone to use in the UI (default: use browser local time)
@@ -152,7 +156,6 @@ time:
     timezone: America/Los_Angeles
     # Optional: For internet-connected deployments, sync using `timedatectl set-npt` (default: shown below)
     # Note: for offline deployments, time will stop whenever power is disconnected
-    npt_set: True
-
-</code></pre>
+    npt_set: false
+```
 

docs/sensor-payloads/air-quality-aq-payload.md

@@ -2,7 +2,7 @@
 description: Enviro + Air Quality sensor from Pimoroni for environmental conditions
 ---
 
-# Air Quality (AQ) Payload
+# Air Quality (AQ) Sensor Specifications
 
 {% hint style="info" %}
 The AQ software is available at [greendormer/enviroplus-monitor](https://github.com/greendormer/enviroplus-monitor). It is based on the wonderful work from the [roscoe81/enviro-monitor](https://github.com/roscoe81/enviro-monitor) and [Pimoroni Enviroplus](https://github.com/pimoroni/enviroplus-python) projects.
@@ -28,21 +28,18 @@ See [Config Readme](https://github.com/greendormer/enviroplus-monitor/blob/main/
 
 ### Recommended config settings
 
-{% hint style="info" %}
-Note: At present, readings will be sent every 5-minutes and _this is hard-coded_. This will be parameterized in a future release.
-{% endhint %}
-
 The following are important keys for the recommended default Traffic Monitor -specific configuration:
 
 * `"enable_send_data_to_homemanager": true` in order to send MQTT payloads to specified broker
 * `"mqtt_broker_name": "localhost"` to send to Node-RED MQTT broker (assumes port 1883)
 * `"indoor_outdoor_function": "Outdoor"` to utilize `outdoor_mqtt_topic`
 * `"enable_display": false` since the AQ sensor will be in an enclosure
-* `"outdoor_mqtt_topic": "aq-readings"` for monitored message topic
+* `"outdoor_mqtt_topic": "aq/sensorname01/readings"` for sending messages, must start with "aq" and the middle element, "sensorname01" must be defined in your TM config
+* `"long_update_delay": 300` for time between sending MQTT messages (default 300-seconds)
 
 ### Deployment-specific config settings
 
-These need to be configured per-deployment for your location. They are utilized by the [`astral` package](https://astral.readthedocs.io/en/latest/package.html) for calculating the times of various aspects of the sun and phases of the moon.
+The following location-based settings need to be set per-deployment for your location. They are utilized by the [`astral` package](https://astral.readthedocs.io/en/latest/package.html) for calculating the times of various aspects of the sun and phases of the moon (lat/lon, time zone) and calibrating temperature, humidity, barometer, and gas (altitude) readings.
 
 ```json
 {
@@ -55,7 +52,7 @@ These need to be configured per-deployment for your location. They are utilized
 }
 ```
 
-## Sensor MQTT Incoming Payload
+# Air Quality MQTT Incoming Payload
 
 The TM AQ application sends messages via MQTT integration on the `aq/readings` topic.
 
@@ -65,53 +62,89 @@ The sensor needs to stabilize (default 5-minutes) after the script initializes b
 
 ```json
 {
-    "Gas Calibrated": true,
-    "Bar": [
-        1014.07,
+    "gas_calibrated": false,
+    "bar": [
+        1009.44,
         "0"
     ],
-    "Hum": [
-        70.3,
-        "1"
+    "hum": [
+        28.7,
+        "2"
     ],
-    "P2.5": 0,
-    "P10": 0,
-    "P1": 0,
-    "Dew": 10.8,
-    "Temp": 16.2,
-    "Min Temp": 13.7,
-    "Max Temp": 16.8,
-    "Red": 6.7,
-    "Oxi": 0.21,
-    "NH3": 1.51,
-    "Lux": 0
+    "p025": 0,
+    "p10": 0,
+    "p01": 0,
+    "dew": 2.1,
+    "temp": 21,
+    "temp_min": 20.9,
+    "temp_max": 21.1,
+    "gas_red": 4.2,
+    "gas_oxi": 0.15,
+    "gas_nh3": 0.69,
+    "lux": 1.2,
+    "proximity": 255,
+    "lux_raw": 1.16185,
+    "temp_raw": 28.68982029794099,
+    "bar_raw": 1003.7122773175154,
+    "hum_raw": 18.31337919009301,
+    "gas_red_raw": 140805,
+    "gas_oxi_raw": 103585,
+    "gas_nh3_raw": 227871,
+    "current_time": 1738698665.077546
 }
 ```
 
-### Database 
+| Key | Valid Values | Units | Notes |
+| -------------- | ------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| gas_calibrated | true/false | | Hard-coded value (10-min) `gas_sensors_warmup_time = 6000` or `startup_stabilisation_time` when `reset_gas_sensor_calibration = true`|
+| bar | [REAL, TEXT] | hPa, Comfort-level `{"0": "Stable", "1": "Fair", "3": "Poorer/Windy/", "4": "Rain/Gale/Storm"}` | Air pressure, compensated for altitude and temp as `Bar / comp_factor` where `comp_factor = math.pow(1 - (0.0065 * altitude/(temp + 0.0065 * alt + 273.15)), -5.257)` |
+| hum | [REAL, TEXT] | %, Comfort-level `{"good": "1", "dry": "2", "wet": "3"}`| Adjusted for compensation factor set in `config.json` |
+| Forecast | {OBJECT} | `Valid`: true/false, `3 Hour Change` is millibars difference in barometer readings, `Forecast` is description calculated from barometer change | Calculated forecast based on sensor barometer changes|
+| pm01 | REAL | ug/m3 (microgram per meter cubed, µg/m³) | Particulate Matter 1 micrometers / microns (PM1, PM<sub>1</sub>), Read directly using the `pms5003.pm_ug_per_m3()` method from the particulate matter sensor. |
+| pm025 | REAL | ug/m3 (microgram per meter cubed, µg/m³) | Particulate Matter 2.5 micrometers / microns (PM2.5, PM<sub>2.5</sub>), read directly using the `pms5003.pm_ug_per_m3()` method from the particulate matter sensor. |
+| pm10 | REAL | ug/m3 (microgram per meter cubed, µg/m³) | Particulate Matter 10 micrometers / microns (PM10, PM<sub>10</sub>), Read directly using the `pms5003.pm_ug_per_m3()` method from the particulate matter sensor. |
+| dew | REAL | C | Calculated from Temp and Hum as `(237.7 * (math.log(dew_hum/100)+17.271*dew_temp/(237.7+dew_temp))/(17.271 - math.log(dew_hum/100) - 17.271*dew_temp/(237.7 + dew_temp)))` | 
+| temp | REAL |  C | Adjusted for compensation factor set in `config.json` | 
+| temp_min | REAL | C | Minimum temperature measured while sensor was running (only resets on restart) | 
+| temp_max | REAL | C | Maximum temperature measured while sensor was running (only resets on restart) | 
+| gas_red | REAL | ppm | Red PPM calculated as `red_in_ppm = math.pow(10, -1.25 * math.log10(red_ratio) + 0.64)`. `red_ratio` is compensated gas value, see Software notes. | 
+| gas_oxi | REAL | ppm | Oxi PPM calculated as `oxi_in_ppm = math.pow(10, math.log10(oxi_ratio) - 0.8129)`. `oxi_ratio` is compensated gas value, see Software notes. | 
+| nh3 | REAL | ppm | NH3 PPM calculated as `nh3_in_ppm = math.pow(10, -1.8 * math.log10(nh3_ratio) - 0.163)`. `nh3_ratio` is compensated gas value, see Software notes. | 
+| lux | REAL | lux | Read directly using the `ltr559.get_lux()` method from the light sensor. | 
+| temp_raw | REAL | C | Read directly from sensor absent compensation. |
+| bar_raw | REAL | C | Read directly from sensor absent compensation. |
+| hum_raw | REAL | % | Read directly from sensor absent compensation. |
+| gas_red_raw | REAL | Ohms | Read directly from sensor using `gas_data.reducing` method absent compensation. |
+| gas_oxi_raw | REAL | Ohms | Read directly from sensor using `gas_data.oxidising` method absent compensation. |
+| gas_nh3_raw | REAL | Ohms | Read directly from sensor using `gas_data.nh3` method absent compensation. |
+| current_time | REAL | Unix time in Seconds | Created by script upon reading values. |
+
+# Air Quality TM Database&#x20;
 
 \[insert attributes table here]
 
-## Notes on readings
+# Notes on Air Quality readings
 
-### Gas sensor
+## Gas sensor
 
-MICS6814 analog gas sensor ([datasheet](https://www.sgxsensortech.com/content/uploads/2015/02/1143_Datasheet-MiCS-6814-rev-8.pdf)):  _The MiCS-6814 is a robust MEMS sensor for the detection of pollution from automobile exhausts and for agricultural/industrial odors._ &#x20;
+The [MICS6814](https://www.sgxsensortech.com/content/uploads/2015/02/1143_Datasheet-MiCS-6814-rev-8.pdf) analog gas sensor:  _The MiCS-6814 is a robust MEMS sensor for the detection of pollution from automobile exhausts and for agricultural/industrial odors._ &#x20;
 
-The sensor includes the ability to detect reductive (RED), oxidative (OXI), and ammonia (NH3) gases.
+The sensor includes the ability to detect reductive (RED), oxidative (OXI), and ammonia (NH3) gases. The raw gas readings are measured as Ohms of resistance for their respective gasses, but the software compensates for temperature, humidity, altitude, and drift to provide PPM (parts per million) equivalents.* 
+
+*See Software notes and additional discussions on [pimoroni/enviroplus-python #47](https://github.com/pimoroni/enviroplus-python/issues/47) and [pimoroni/enviroplus-python #67](https://github.com/pimoroni/enviroplus-python/issues/67). 
 
 **Software notes**
 
 * Gas calibrates using Temp, Humidity, and Barometric Pressure readings.
 * Gas Sensors (`Red`, `Oxi`, `NH3`) take 100-minutes to warm-up and readings to become available
-* To compensate for gas sensor drift over time, the software calibrates gas sensors daily at time set by `gas_daily_r0_calibration_hour`, using average of daily readings over a week if not already done in the current day and if warm-up calibration is completed.&#x20;
+* To compensate for gas sensor drift over time, the software calibrates gas sensors daily at time set by `gas_daily_r0_calibration_hour`, using average of daily readings over a week if not already done in the current day and if warm-up calibration is completed. This compensates for gas sensor drift over time&#x20;
 * Raw gas readings will also have compensation factors applied, determined by [regression analysis](https://github.com/roscoe81/enviro-monitor/blob/master/Regression_Analysis/Northcliff_Enviro_Monitor_Regression_Analyser.py).
 
-### Temperature, pressure, and humidity
+## Temperature, pressure, and humidity
 
-BME280 temperature, pressure, humidity sensor ([datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme280-ds002.pdf)) with I2S digital output.
+The [BME280](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme280-ds002.pdf) temperature, pressure, humidity sensor with I2S digital output.
 
-#### Software notes
+### Software notes
 
 * `Temp` (temperature) and `Hum` (humidity) have cubic polynomial compensation factors applied to raw readings
 * `Min Temp`and `Max Temp`are calculated over the entire time the script is running
@@ -123,13 +156,17 @@ BME280 temperature, pressure, humidity sensor ([datasheet](https://www.bosch-sen
     dewpoint = (237.7 * (math.log(dew_hum/100)+17.271*dew_temp/(237.7+dew_temp))/(17.271 - math.log(dew_hum/100) - 17.271*dew_temp/(237.7 + dew_temp)))
     ```
 
-### Noise&#x20;
+## Optical (light, proximity)
+
+The [LTR-559](https://optoelectronics.liteon.com/upload/download/DS86-2013-0003/LTR-559ALS-01_DS_V1.pdf) light and proximity sensor
+
+## Noise&#x20;
 
 MEMS microphone ([datasheet](https://media.digikey.com/pdf/Data%20Sheets/Knowles%20Acoustics%20PDFs/SPH0645LM4H-B.pdf)).
 
-### Particulate matter (PM) sensor&#x20;
+## Particulate matter (PM) &#x20;
 
-Plantower PMS5003 Particulate Matter (PM) Sensor ([datasheet](http://www.aqmd.gov/docs/default-source/aq-spec/resources-page/plantower-pms5003-manual_v2-3.pdf)).
+The Plantower [PMS5003](http://www.aqmd.gov/docs/default-source/aq-spec/resources-page/plantower-pms5003-manual_v2-3.pdf) Particulate Matter (PM) Sensor.
 
 \