Release 4.0.0

Author: MallocArray

README.md

@@ -4,17 +4,23 @@ ESPHome yaml files for AirGradient devices to maintain the research and accuracy
 
 ## Breaking Changes
 
-Due to renaming of the Automatic Background Calibration switch to the proper name of Automatic Baseline Correction, this switch will default to being enabled, even if previously you had disabled it.  After installing, disable again if desired
+* Remove substitution line such as `config_version: 2.0.5` from the main file, as this has been moved into the board package file
+* Updated to 4.0.0 versions, skipping 3.x to avoid confusion with current AirGradient official firmware
 
 ## Changes
 
-* Added Display Contrast slider to dim the display
-* Added device_class to the PMSx005 sensors to have them properly reflect in the HomeKit integration if supported ([Forum Link](https://forum.airgradient.com/t/airgradient-one-customized-mallocarray-esphome-display/1328/7?u=mallocarray))
-* Added optional Factory Reset switch that is disabled by default. Can be enabled in HomeAssistant and used if desired
-* LED combo package. Left 5 LEDs reflect CO2 levels, middle 5 LEDs reflect PM2.5 levels, far right indicates VOC. (Same as display)
-* LED bar configs feature a "LED Fade" parameter that controls the percentage that the LED bar dims out from the center
-  ![1715467068556](image/README/1715467068556.png)
-* CO2 package supports optional substitution `co2_offset` to offset reported readings by a set amount.  Useful if sensor is known to be off by a certain amount, or if wanting to override default calibration of 400 ppm
+* Support for ESPHome 2024.6 and later
+* Added extended timeout for API upload on ONE and OpenAir models to reduce reboots
+* Applied correction algorithms for PM2.5 provided by AirGradient
+  * https://www.airgradient.com/documentation/correction-algorithms/
+* Updated API upload to follow current structure including both raw and corrected values
+* Moved config_version substitution into the board package so it can be updated without manual change to main config file.  Please remove the line starting with `config_version:` from your personal files
+* Split captive portal config to a separate package.  Can be removed if not using the portal or if defining wifi networks in your config file, which results in a small memory savings
+* Removed safe_mode package by default.  Very few use cases for it
+* Added commented out packages for extended_life configs to make it easier to enable if desired
+* Added commented out package for SHT30 temp sensor in AG Pro file to make it easier to switch to if desired
+* Added new sensor options for raw values for PM2.5, temp, and humidity in some device configurations, and added AirGradient provided correction algorithms to the standard sensors
+* AG DIY Basic display config changed to same font as other models, downloading from gfonts instead of using local file
 
 ## Features
 
@@ -48,7 +54,7 @@ Many added features can be found in HomeAssistant by going to Settings>Devices a
 
   - Short press (Less than 1 second) - Toggle between F and C on display
   - Long press (More than 1 second, less than 5) - Trigger manual CO2 calibration
-- Leverage automations in HomeAssistant to turn on the "Blank" page and turn off all other pages to effectively disable the display output.  Could also turn off the LED strip or set Brightness to 0 to eliminate output while still collecting sensor data
+- Leverage automation in HomeAssistant to turn on the "Blank" page and turn off all other pages to effectively disable the display output.  Could also turn off the LED strip or set Brightness to 0 to eliminate output while still collecting sensor data
 
 ## Installation
 
@@ -162,14 +168,5 @@ MQTT support has been mentioned in the AirGradient forums several times.  ESPHom
 
 Several more features are planned to be added to this repo
 
-- [X] Support for Open Air without CO2 sensor (Model: O-1PPT)
-- [ ] Explore options for disabling display/LED during certain times (May be differed to HomeAssistant Automations)
-- [ ] Standardize font on AirGradient Basic display to match Pro
-- [X] Reduce number of fonts used in the multi_page package
-  - [X] Open Sans displays a consistent height, but some characters, such as F and 0 are mismatched, the left side is double line thick while right is single line
-  - [X] Poppins Light is consistent thickness, but numbers are taller than letters, giving a mismatched height
-- [ ] Add GitHub actions to automatically build updated .bin files as needed
-- [X] Add support for esp32_improv and improv_serial (improv_serial not supported with this board and used pins.  esp32_improv uses 30% of available flash memory and is nearly full)
-  - [X] [https://esphome.io/guides/creators.html](https://esphome.io/guides/creators.html "https://esphome.io/guides/creators.html")
-- [X] Add support for dashboard_import and project information
-  - [X] [https://esphome.io/guides/creators.html](https://esphome.io/guides/creators.html "https://esphome.io/guides/creators.html")
+- [ ] Explore options for disabling display/LED during certain times (May be differed to HomeAssistant Automation)
+- [X] Standardize font on AirGradient Basic display to match Pro

airgradient-basic.yaml

@@ -5,7 +5,6 @@
 substitutions:
   name: "ag-basic"
   friendly_name: "AG Basic"
-  config_version: 2.0.5
   name_add_mac_suffix: "false"  # Must have quotes around value
 
 # Enable Home Assistant API
@@ -16,20 +15,19 @@ ota:  # Add password as desired
   # password:
 
 wifi:
-  # Enable fallback hotspot (captive portal) in case wifi connection fails
-  ap:
 
 dashboard_import:
   package_import_url: github://MallocArray/airgradient_esphome/airgradient-basic.yaml
   import_full_config: false
 
 packages:
   board: github://MallocArray/airgradient_esphome/packages/airgradient_d1_mini_board.yaml
+  captive_portal: !include github://MallocArray/airgradient_esphome/packages/captive_portal.yaml
   pm_2.5: github://MallocArray/airgradient_esphome/packages/sensor_pms5003.yaml
   co2: github://MallocArray/airgradient_esphome/packages/sensor_s8.yaml
+  # temp_humidity: github://MallocArray/airgradient_esphome/packages/sensor_sht40.yaml
   temp_humidity: github://MallocArray/airgradient_esphome/packages/sensor_sht30.yaml
   display: github://MallocArray/airgradient_esphome/packages/display_ssd1306.yaml
   airgradient_api: github://MallocArray/airgradient_esphome/packages/airgradient_api_d1_mini_no_sgp41.yaml
   wifi: github://MallocArray/airgradient_esphome/packages/sensor_wifi.yaml
   uptime: github://MallocArray/airgradient_esphome/packages/sensor_uptime.yaml
-  safe_mode: github://MallocArray/airgradient_esphome/packages/switch_safe_mode.yaml

airgradient-one.yaml

@@ -4,7 +4,6 @@
 substitutions:
   name: "ag-one"
   friendly_name: "AG One"
-  config_version: 2.0.5
   name_add_mac_suffix: "false"  # Must have quotes around value
 
 # Enable Home Assistant API
@@ -15,15 +14,14 @@ ota:  # Add password as desired
   # password:
 
 wifi:
-  # Enable fallback hotspot (captive portal) in case wifi connection fails
-  ap:
 
 dashboard_import:
   package_import_url: github://MallocArray/airgradient_esphome/airgradient-one.yaml
   import_full_config: false
 
 packages:
   board: github://MallocArray/airgradient_esphome/packages/airgradient_esp32-c3_board.yaml
+  captive_portal: !include github://MallocArray/airgradient_esphome/packages/captive_portal.yaml
   pm_2.5: github://MallocArray/airgradient_esphome/packages/sensor_pms5003.yaml
   co2: github://MallocArray/airgradient_esphome/packages/sensor_s8.yaml
   temp_humidity: github://MallocArray/airgradient_esphome/packages/sensor_sht40.yaml
@@ -36,7 +34,6 @@ packages:
   config_button: github://MallocArray/airgradient_esphome/packages/config_button.yaml
   wifi: github://MallocArray/airgradient_esphome/packages/sensor_wifi.yaml
   uptime: github://MallocArray/airgradient_esphome/packages/sensor_uptime.yaml
-  safe_mode: github://MallocArray/airgradient_esphome/packages/switch_safe_mode.yaml
 
 binary_sensor:
   - id: !extend config_button

airgradient-open-air-o-1ppt.yaml

@@ -5,7 +5,6 @@
 substitutions:
   name: "ag-open-air-o-1ppt"
   friendly_name: "AG Open Air O-1PPT"
-  config_version: 2.0.5
   name_add_mac_suffix: "false"  # Must have quotes around value
 
 # Enable Home Assistant API
@@ -16,20 +15,20 @@ ota:  # Add password as desired
   # password:
 
 wifi:
-  # Enable fallback hotspot (captive portal) in case wifi connection fails
-  ap:
 
 dashboard_import:
   package_import_url: github://MallocArray/airgradient_esphome/airgradient-open-air-o-1ppt.yaml
   import_full_config: false
 
 packages:
   board: github://MallocArray/airgradient_esphome/packages/airgradient_esp32-c3_board.yaml
+  captive_portal: !include github://MallocArray/airgradient_esphome/packages/captive_portal.yaml
   pm_2.5: github://MallocArray/airgradient_esphome/packages/sensor_pms5003t.yaml
+  # pm_2.5: github://MallocArray/airgradient_esphome/packages/sensor_pms5003t_extended_life.yaml
   pm_2.5_2: github://MallocArray/airgradient_esphome/packages/sensor_pms5003t_2.yaml
+  # pm_2.5_2: github://MallocArray/airgradient_esphome/packages/sensor_pms5003t_2extended_life.yaml
   tvoc: github://MallocArray/airgradient_esphome/packages/sensor_sgp41.yaml
   airgradient_api: github://MallocArray/airgradient_esphome/packages/airgradient_api_esp32-c3_dual_pms5003t.yaml
   hardware_watchdog: github://MallocArray/airgradient_esphome/packages/watchdog.yaml
   wifi: github://MallocArray/airgradient_esphome/packages/sensor_wifi.yaml
   uptime: github://MallocArray/airgradient_esphome/packages/sensor_uptime.yaml
-  safe_mode: github://MallocArray/airgradient_esphome/packages/switch_safe_mode.yaml

airgradient-open-air-o-1pst.yaml

@@ -5,7 +5,6 @@
 substitutions:
   name: "ag-open-air-o-1pst"
   friendly_name: "AG Open Air O-1PST"
-  config_version: 2.0.5
   name_add_mac_suffix: "false"  # Must have quotes around value
 
 # Enable Home Assistant API
@@ -16,20 +15,19 @@ ota:  # Add password as desired
   # password:
 
 wifi:
-  # Enable fallback hotspot (captive portal) in case wifi connection fails
-  ap:
 
 dashboard_import:
   package_import_url: github://MallocArray/airgradient_esphome/airgradient-open-air-o-1pst.yaml
   import_full_config: false
 
 packages:
   board: github://MallocArray/airgradient_esphome/packages/airgradient_esp32-c3_board.yaml
+  captive_portal: !include github://MallocArray/airgradient_esphome/packages/captive_portal.yaml
   pm_2.5: github://MallocArray/airgradient_esphome/packages/sensor_pms5003t.yaml
+  # pm_2.5: github://MallocArray/airgradient_esphome/packages/sensor_pms5003t_extended_life.yaml
   co2: github://MallocArray/airgradient_esphome/packages/sensor_s8.yaml
   tvoc: github://MallocArray/airgradient_esphome/packages/sensor_sgp41.yaml
   airgradient_api: github://MallocArray/airgradient_esphome/packages/airgradient_api_esp32-c3.yaml
   hardware_watchdog: github://MallocArray/airgradient_esphome/packages/watchdog.yaml
   wifi: github://MallocArray/airgradient_esphome/packages/sensor_wifi.yaml
   uptime: github://MallocArray/airgradient_esphome/packages/sensor_uptime.yaml
-  safe_mode: github://MallocArray/airgradient_esphome/packages/switch_safe_mode.yaml

airgradient-pro.yaml

@@ -4,7 +4,6 @@
 substitutions:
   name: "ag-pro"
   friendly_name: "AG Pro"
-  config_version: 2.0.5
   name_add_mac_suffix: "false"  # Must have quotes around value
 
 # Enable Home Assistant API
@@ -15,25 +14,24 @@ ota:  # Add password as desired
   # password:
 
 wifi:
-  # Enable fallback hotspot (captive portal) in case wifi connection fails
-  ap:
 
 dashboard_import:
   package_import_url: github://MallocArray/airgradient_esphome/airgradient-pro.yaml
   import_full_config: false
 
 packages:
   board: github://MallocArray/airgradient_esphome/packages/airgradient_d1_mini_board.yaml
+  captive_portal: !include github://MallocArray/airgradient_esphome/packages/captive_portal.yaml
   pm_2.5: github://MallocArray/airgradient_esphome/packages/sensor_pms5003.yaml
   co2: github://MallocArray/airgradient_esphome/packages/sensor_s8.yaml
   temp_humidity: github://MallocArray/airgradient_esphome/packages/sensor_sht40.yaml
+  # temp_humidity: github://MallocArray/airgradient_esphome/packages/sensor_sht30.yaml
   tvoc: github://MallocArray/airgradient_esphome/packages/sensor_sgp41.yaml
   display: github://MallocArray/airgradient_esphome/packages/display_sh1106_single_page.yaml
   airgradient_api: github://MallocArray/airgradient_esphome/packages/airgradient_api_d1_mini.yaml
   config_button: github://MallocArray/airgradient_esphome/packages/config_button.yaml
   wifi: github://MallocArray/airgradient_esphome/packages/sensor_wifi.yaml
   uptime: github://MallocArray/airgradient_esphome/packages/sensor_uptime.yaml
-  safe_mode: github://MallocArray/airgradient_esphome/packages/switch_safe_mode.yaml
 
 binary_sensor:
   - id: !extend config_button

full_config/ag-open-air-o-1ppt.yaml

@@ -190,6 +190,8 @@ sensor:
     id: temp
     filters:
     - lambda: !lambda |-
+        // Remove line with (x > 6000) once the negative number issue fix is merged in https://github.com/esphome/issues/issues/3814
+        if (x > 6000) return ((x - 6553.6) * 1.327) - 6.738;
         if (x < 10.0) return (x * 1.327) - 6.738;
         return (x * 1.181) - 5.113;
     - sliding_window_moving_average:
@@ -324,6 +326,8 @@ sensor:
     id: temp_2
     filters:
     - lambda: !lambda |-
+        // Remove line with (x > 6000) once the negative number issue fix is merged in https://github.com/esphome/issues/issues/3814
+        if (x > 6000) return ((x - 6553.6) * 1.327) - 6.738;
         if (x < 10.0) return (x * 1.327) - 6.738;
         return (x * 1.181) - 5.113;
     - sliding_window_moving_average:

full_config/ag-open-air-o-1pst.yaml

@@ -209,6 +209,8 @@ sensor:
     id: temp
     filters:
     - lambda: !lambda |-
+        // Remove line with (x > 6000) once the negative number issue fix is merged in https://github.com/esphome/issues/issues/3814
+        if (x > 6000) return ((x - 6553.6) * 1.327) - 6.738;
         if (x < 10.0) return (x * 1.327) - 6.738;
         return (x * 1.181) - 5.113;
     - sliding_window_moving_average:

packages.md

@@ -26,6 +26,16 @@ Board configuration for devices based on the D1 Mini chip (AG Basic and AG Pro)
 
 Board configuration for devices based on the ESP32-C3 chip (AG ONE and OpenAir)
 
+## button_factory_reset.yaml
+
+Enables a button to reset device to factory resets, which erases all nvram and erases all stored preferences.
+
+Useful if warning messages about being unable to save preferences appear
+
+## captive_portal.yaml
+
+Configures the device to provide a captive portal to create a hotspot if wifi is not connected, so it can be connected to a new wifi network without reconfiguring the config file
+
 ## config_button.yaml
 
 Enables the configuration button on the AirGradient device.  Default configuration is for devices based on ESP32-C3 chip, but additional configuration can be added to change the pin to support D1 Mini if the device has a physical button installed (Already part of the config file for AG Pro v4.2)
@@ -197,10 +207,20 @@ 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
 
+## sensor_pms5003_uncorrected.yaml
+
+Configures a Plantower PMS5003 sensor using raw values from the sensor
+
+Reports PM 2.5, PM 10, PM 1.0, PM 0.3, and Air Quality Index based on the current readings.
+
 ## sensor_pms5003.yaml
 
 Configures a Plantower PMS5003 sensor.
 
+Applies correction algorithms provided by AirGradient
+
+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.
 
 ## sensor_s8.yaml
@@ -224,6 +244,15 @@ Configures a Sensirion SGP41 sensor.
 
 Reports VOC and NOx Index values.
 
+Now supports modifying VOC and NOx learning time offset hours by adding the substitutions
+
+```yaml
+substitutions:
+  # 12, 60, 120, 360, 720 are suggested values from AirGradient (range 1..1000)
+  voc_learning_time_offset_hours: '12'
+  nox_learning_time_offset_hours: '12'
+```
+
 ## sensor_sht30.yaml
 
 Configures a Sensirion SHT30 sensor

packages/airgradient_api_d1_mini.yaml

@@ -20,8 +20,10 @@ interval:
                 pm02: !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).state);
-                rhum: !lambda return to_string(id(humidity).state);
+                atmp: !lambda return to_string(id(temp_raw).state);
+                atmpCompensated: !lambda return to_string(id(temp).state);
+                rhum: !lambda return to_string(id(humidity_raw).state);
+                rhumCompensated: !lambda return to_string(id(humidity).state);
                 tvocIndex: !lambda return to_string(id(voc).state);
                 noxIndex: !lambda return to_string(id(nox).state);
                 # Uptime in minutes as the boot value