Update documentation around calibration algorithms

Author: MallocArray

README.md

@@ -8,6 +8,8 @@ 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.
@@ -68,4 +70,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.