Merge pull request #148 from MallocArray/pm25_correction_formula

Add substitutions for pm25 correction formulas

Author: MallocArray

README.md

@@ -8,21 +8,20 @@ ESPHome yaml files for AirGradient devices to maintain the research and accuracy
 
 ## [Configuration](/configuration.md)
 
+## [Calibration](/calibration.md)
+
 ## Breaking Changes
 
 * 5.0.0 is a major version upgrade as switching to esp-idf is not fully supported via OTA. Highly recommend doing one USB flash of 5.0.0 and later to the AirGradient ONE and OpenAir devices to reformat the storage to support esp-idf.  Future updates can be done Over-The-Air without issue.
   * If not done, the device is likely to reboot at some point and switch to the standby partition, returning to a version prior to 5.0.0
   * [Seeing an Old Firmware Version After Update? Here's Why & How to Fix It · Issue #1821 · Blackymas/NSPanel_HA_Blueprint](https://github.com/Blackymas/NSPanel_HA_Blueprint/issues/1821)
   * [Read/Write bootloader, partition table and any partition via OTA by angelnu · Pull Request #5535 · esphome/esphome](https://github.com/esphome/esphome/pull/5535)
-* Aware of errors in the logs stating `esp_task_wdt_reconfigure(615): Invalid arguments`
-  * Tracking [Watchdog config hardcoded core mask · Issue #6767 · esphome/issues](https://github.com/esphome/issues/issues/6767)
-* 5.0.0 switches ONE and OpenAir models (based on ESP32) to the esp-idf framework, freeing up some memory and allowing other advanced features such as bluetooth_proxy and esp32_improv.  If the previous Arduino framework is desired, change the board to `airgradient_esp32-c3_board-arduino.yaml`
-* If attempting to add BT and BLE support, may need to remove the captive_portal package to free up enough space [Issue #115](https://github.com/MallocArray/airgradient_esphome/issues/115)
 
 ## Changes
 
-* Added optional package for using LED bar on AirGradient ONE to reflect TVOC values
-* Added examples of Home Assistant automation to disable the display and LED at a scheduled time in configuration.md
+* Added optional substitutions to implement batch-specific PM2.5 corrections using values provided by AirGradient
+  [See details in the packages.md file under the PMS5003 section.](packages.md#sensor_pms5003yaml)
+* Restored logging to default values as it no longer repeats messages about components taking too long to complete
 
 ## Features
 
@@ -68,4 +67,5 @@ Many added features can be found in HomeAssistant by going to Settings>Devices a
 
 More features are planned to be added to this repo
 
-- [ ] PMS5003 model specific correction algorithms
+- [X] PMS5003 model specific correction algorithms
+- [ ] Deprecate Extended Life packages and use a substitution to allow for adjusting update_interval

calibration.md

@@ -0,0 +1,39 @@
+# Calibration
+
+Many of the official calibration algorithms from AirGradient are also implemented in this repository.
+https://www.airgradient.com/documentation/calibration-algorithms/
+
+## EPA PM2.5 Calibration
+
+This algorithm is applied by default to all PMS5003(t) sensors in this repository.  If it is desired to not apply this and instead use raw values from the sensors, replace the package file with the one ending with `_uncorrected.yaml`
+
+## Batch Specific PM2.5 Calibration
+
+AirGradient detected that PMS5003 sensors after 2023-10-30 used a different manufacturer calibration that results in lower PM2.5 values under low concentrations.  AirGradient has developed an algorithm and tested values to correct these values when they are less than 31 ug/m3
+
+In this repo, 2 substitution values can be adjusted to apply the calibration. In the main YAML file for the device, add a substitutions item and the follow parameters if not already present.
+
+```yaml
+substitutions:
+  pm_2_5_scaling_factor: '1'
+  pm_2_5_intercept: '0'
+```
+
+Adjust the scaling factor and intercept specific to your requirements.  The values from AirGradient can be found in the AirGradient Dashboard site under Hardware>Advanced Settings>PM 2.5
+
+Under "Special formulas by specific batch" select a batch that matches the label on the sensor inside of your AirGradient, and take note of the `Scaling Factor` and `Offset` values to copy to the ESPHome YAML file.
+
+Refer to the AirGradient page for the most current values, and they are planning on adding device specific formulas in the future
+https://app.airgradient.com/settings/hardware
+
+| Batch ID            | Scaling Factor   | Offset |
+|---------------------|------------------|--------|
+| PMS5003_20231030    | 0.02838          | 0      |
+| PMS5003_20231218    | 0.03525          | 0      |
+| PMS5003_20240104    | 0.02896          | 0      |
+
+https://www.airgradient.com/blog/update-on-pms5003-calibration/
+
+## Temperature and Humidity Calibration for Open Air Outdoor monitors
+
+The algorithm from AirGradient for the PMS5003T sensors used in the Open Air for both Temperature and Humidity are applied by default. If it is desired to not apply this and instead use raw values from the sensors, replace the package file with the one ending with `_uncorrected.yaml`

packages.md

@@ -61,7 +61,7 @@ binary_sensor:
 For devices that use the ESP32-C3 the CPU clock can be lowered from default 160
 MHz to 80 MHz to save power. The higher default clock is not needed for the
 calculations that even the AirGradient One by default has to do to interact
-with all the sernsors, display, LEDs and so on. If you suspect this causes
+with all the sensors, display, LEDs and so on. If you suspect this causes
 problems, look at the ESPHome log or enable the `diagnostic_esp32.yaml` package
 and look at "Loop Time".
 
@@ -199,6 +199,14 @@ By default collects readings every second. Since this device has a limited lifes
 Collects readings every 2 minutes by default, but can be modified by adding an entry under substitutions, ensuring the value is surrounded by double quotes
 `pm_update_interval: "2min"`
 
+Can also apply batch or device specific correction formulas. See [calibration.md](calibration.md) for more details.
+
+```yaml
+substitutions:
+  pm_2_5_scaling_factor: '1'
+  pm_2_5_intercept: '0'
+```
+
 ## sensor_pms5003t_2_extended_life.yaml
 
 Configures a second Plantower PMS5003T sensor when 2 are installed, such as the Open Air Model O-1PPT.  Reports PM2.5, Temperature, and Humidity.
@@ -212,6 +220,14 @@ By default collects readings every second. Since this device has a limited lifes
 Collects readings every 2 minutes by default, but can be modified by adding an entry under substitutions, ensuring the value is surrounded by double quotes
 `pm_update_interval: "2min"`
 
+Can also apply batch or device specific correction formulas. See [calibration.md](calibration.md) for more details.
+
+```yaml
+substitutions:
+  pm_2_5_scaling_factor: '1'
+  pm_2_5_intercept: '0'
+```
+
 ## sensor_pms5003t_2.yaml
 
 Configures a second Plantower PMS5003T sensor when 2 are installed, such as the Open Air Model O-1PPT.  Reports PM 2.5, Temperature, and Humidity.
@@ -231,6 +247,14 @@ By default collects readings every second. Since this device has a limited lifes
 Collects readings every 2 minutes by default, but can be modified by adding an entry under substitutions, ensuring the value is surrounded by double quotes
 `pm_update_interval: "2min"`
 
+Can also apply batch or device specific correction formulas. See [calibration.md](calibration.md) for more details.
+
+```yaml
+substitutions:
+  pm_2_5_scaling_factor: '1'
+  pm_2_5_intercept: '0'
+```
+
 ## sensor_pms5003t_uncorrected.yaml
 
 Configures a Plantower PMS5003T sensor.  Reports PM 2.5, Temperature, and Humidity.
@@ -243,6 +267,14 @@ Configures a Plantower PMS5003T sensor.  Reports PM 2.5, Temperature, and Humidi
 
 Also applies a compensation algorithm from AirGradient to correct temperature and humidity readings when used inside of the Open Air enclosure
 
+Can also apply batch or device specific correction formulas. See [calibration.md](calibration.md) for more details.
+
+```yaml
+substitutions:
+  pm_2_5_scaling_factor: '1'
+  pm_2_5_intercept: '0'
+```
+
 ## sensor_pms5003_uncorrected.yaml
 
 Configures a Plantower PMS5003 sensor using raw values from the sensor
@@ -259,6 +291,14 @@ https://www.airgradient.com/documentation/correction-algorithms/
 
 Reports PM 2.5, PM 10, PM 1.0, PM 0.3, and Air Quality Index based on the current readings.
 
+Can also apply batch or device specific correction formulas. See [calibration.md](calibration.md) for more details.
+
+```yaml
+substitutions:
+  pm_2_5_scaling_factor: '1'
+  pm_2_5_intercept: '0'
+```
+
 ## sensor_s8.yaml
 
 Configures a Senseair S8 sensor.

packages/airgradient_api_d1_mini.yaml

@@ -17,7 +17,8 @@ interval:
                 wifi: !lambda return to_string(id(wifi_dbm).state);
                 rco2: !lambda return to_string(id(co2).state);
                 pm01: !lambda return to_string(id(pm_1_0).state);
-                pm02: !lambda return to_string(id(pm_2_5).state);
+                pm02: !lambda return to_string(id(pm_2_5_raw).state);
+                pm02Compensated: !lambda return to_string(id(pm_2_5).state);
                 pm10: !lambda return to_string(id(pm_10_0).state);
                 pm003Count: !lambda return to_string(id(pm_0_3um).state);
                 atmp: !lambda return to_string(id(temp_raw).state);

packages/airgradient_api_d1_mini_insecure.yaml

@@ -17,7 +17,8 @@ interval:
                 wifi: !lambda return to_string(id(wifi_dbm).state);
                 rco2: !lambda return to_string(id(co2).state);
                 pm01: !lambda return to_string(id(pm_1_0).state);
-                pm02: !lambda return to_string(id(pm_2_5).state);
+                pm02: !lambda return to_string(id(pm_2_5_raw).state);
+                pm02Compensated: !lambda return to_string(id(pm_2_5).state);
                 pm10: !lambda return to_string(id(pm_10_0).state);
                 pm003Count: !lambda return to_string(id(pm_0_3um).state);
                 atmp: !lambda return to_string(id(temp_raw).state);

packages/airgradient_api_d1_mini_no_sgp41.yaml

@@ -17,7 +17,8 @@ interval:
                 wifi: !lambda return to_string(id(wifi_dbm).state);
                 rco2: !lambda return to_string(id(co2).state);
                 pm01: !lambda return to_string(id(pm_1_0).state);
-                pm02: !lambda return to_string(id(pm_2_5).state);
+                pm02: !lambda return to_string(id(pm_2_5_raw).state);
+                pm02Compensated: !lambda return to_string(id(pm_2_5).state);
                 pm10: !lambda return to_string(id(pm_10_0).state);
                 pm003Count: !lambda return to_string(id(pm_0_3um).state);
                 atmp: !lambda return to_string(id(temp_raw).state);

packages/airgradient_api_esp32-c3.yaml

@@ -17,7 +17,8 @@ interval:
                 wifi: !lambda return to_string(id(wifi_dbm).state);
                 rco2: !lambda return to_string(id(co2).state);
                 pm01: !lambda return to_string(id(pm_1_0).state);
-                pm02: !lambda return to_string(id(pm_2_5).state);
+                pm02: !lambda return to_string(id(pm_2_5_raw).state);
+                pm02Compensated: !lambda return to_string(id(pm_2_5).state);
                 pm10: !lambda return to_string(id(pm_10_0).state);
                 pm003Count: !lambda return to_string(id(pm_0_3um).state);
                 atmp: !lambda return to_string(id(temp_raw).state);

packages/airgradient_d1_mini_board.yaml

@@ -1,5 +1,5 @@
 substitutions:
-  config_version: 5.2.1
+  config_version: 5.3.0
 
 esphome:
   name: "${name}"
@@ -18,8 +18,6 @@ esp8266:
 # Enable logging
 # https://esphome.io/components/logger.html
 logger:
-  logs:
-    component: ERROR  # Hiding warning messages about component taking a long time https://github.com/esphome/issues/issues/4717
 
 uart:
   # https://esphome.io/components/uart.html#uart

packages/airgradient_esp32-c3_board-arduino.yaml

@@ -1,5 +1,5 @@
 substitutions:
-  config_version: 5.2.1
+  config_version: 5.3.0
 
 esphome:
   name: "${name}"
@@ -17,8 +17,6 @@ esp32:
 # Enable logging
 # https://esphome.io/components/logger.html
 logger:
-  logs:
-    component: ERROR  # Hiding warning messages about component taking a long time https://github.com/esphome/issues/issues/4717
 
 uart:
   # https://esphome.io/components/uart.html#uart

packages/airgradient_esp32-c3_board.yaml

@@ -1,5 +1,5 @@
 substitutions:
-  config_version: 5.2.1
+  config_version: 5.3.0
 
 esphome:
   name: "${name}"
@@ -19,8 +19,6 @@ esp32:
 # Enable logging
 # https://esphome.io/components/logger.html
 logger:
-  logs:
-    component: ERROR  # Hiding warning messages about component taking a long time https://github.com/esphome/issues/issues/4717
 
 uart:
   # https://esphome.io/components/uart.html#uart