Merge pull request #932 from ApolloAutomation/air1-co2-auto-calibration

bharvey88 · web-flow · commit ce704bf39193 · 2026-06-10T15:23:06.000-05:00
Document CO2 automatic self-calibration across SCD40 products
diff --git a/docs/homey/products/air1/setup/general-tips.md b/docs/homey/products/air1/setup/general-tips.md
@@ -129,6 +129,12 @@ Per Sensirion,
 
 The optional CO<sub>2</sub> sensor addon is a great way to add the ability to track CO<sub>2</sub>. CO<sub>2</sub> levels in a closed, poorly ventilated bedroom can quickly rise to concentrations that may impair focus or even pose health risks. Notice the CO2 levels dropping in the image below when the HVAC was turned on overnight!
 
+The latest AIR-1 firmware keeps the SCD40 calibrated automatically. The sensor assumes it sees fresh air (about 420 ppm) at least once a week and corrects its baseline to match, so you no longer need to re-calibrate it manually every 1 to 2 years.
+
+!!! warning "Auto calibration needs regular fresh air"
+
+    If your AIR-1 sits in a space that rarely gets fresh air (a sealed office, a basement, a grow room), automatic self-calibration will slowly drag the CO<sub>2</sub> readings down. Turn off the **CO2 Auto Calibration** switch in your device's settings and follow the [manual calibration guide](../../../general/calibrating-and-updating/co2-calibration/) every 1 to 2 years instead.
+
 ![](/assets/co2-levels-drop-after-hvac-on.png)
 
 <a href="https://www.dhs.wisconsin.gov/chemical/carbondioxide.htm" target="_blank" rel="noreferrer nofollow noopener">Wisconsin Department of Health CO<sub>2</sub> Level Chart</a>
diff --git a/docs/homey/products/general/calibrating-and-updating/co2-calibration.md b/docs/homey/products/general/calibrating-and-updating/co2-calibration.md
@@ -1,8 +1,14 @@
 # CO<sub>2</sub> Calibration
 
-!!! tip "This should be done every 1-2 years."
+!!! info "Your sensor calibrates itself"
 
-    The <a href="https://sensirion.com/products/catalog/SCD40" title="Docmentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>) but it requires re-calibration after 1-2 years back to a 420 ppm baseline!
+    The latest Apollo firmware enables the SCD40's automatic self-calibration by default on every device with the CO<sub>2</sub> sensor (AIR-1, R-PRO-1, MSR-2, and MTR-1). As long as the sensor sees fresh air (about 420 ppm) at least once a week, it corrects its own baseline and you never need to calibrate manually. Airing out the room once a week is enough.
+
+    If your device sits in a space that rarely gets fresh air (a sealed office, a basement, a grow room), automatic self-calibration will slowly drag the readings down. Turn off the **CO2 Auto Calibration** switch in your device's settings and calibrate manually with the steps below instead.
+
+!!! tip "Calibrate manually every 1 to 2 years when auto calibration is off"
+
+    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>), but with automatic self-calibration turned off it needs re-calibration back to the 420 ppm baseline every 1 to 2 years.
 
 ![AIR-1 Shown Outdoors for CO2 Calibration Portrait Image](/assets/air-1-co2-calibration-portrait-image-1.jpg "AIR-1 Shown Outdoors for CO2 Calibration")
 
diff --git a/docs/homey/products/msr2/calibrating-co2.md b/docs/homey/products/msr2/calibrating-co2.md
@@ -4,9 +4,13 @@ description: Step by step guide for re-calibrating your SCD40 CO2 sensor
 ---
 # CO<sub>2</sub> Calibration - The Quick method - Desktop Only not mobile
 
-!!! tip "This should be done every 1-2 years."
+!!! info "Your MSR-2 calibrates itself"
 
-    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>) but it requires re-calibration after 1-2 years back to a 420 ppm baseline!
+    The latest MSR-2 firmware enables the SCD40's automatic self-calibration by default. As long as the sensor sees fresh air (about 420 ppm) at least once a week, it corrects its own baseline and you never need to calibrate manually. You only need this guide if the device sits in a space that rarely gets fresh air (a sealed office, a basement, a grow room), where auto calibration slowly drags the readings down. In that case, turn off the **CO2 Auto Calibration** switch in your device's settings and calibrate manually with the steps below.
+
+!!! tip "Calibrate manually every 1 to 2 years when auto calibration is off"
+
+    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>), but with automatic self-calibration turned off it needs re-calibration back to the 420 ppm baseline every 1 to 2 years.
 
 This article will guide you through a simple calibration of your CO<sub>2</sub> sensor for any Apollo Automation device!
 
diff --git a/docs/products/air1/faq.md b/docs/products/air1/faq.md
@@ -61,7 +61,7 @@ description: Frequently asked questions about the AIR-1 environmental sensor, in
 
 15\. **How do I calibrate the CO2 sensor?**
 
-* The CO2 sensor comes pre-calibrated, so you don’t need to perform any manual calibration. However, you can recalibrate the sensor through ESPHome if needed.
+* You usually don't need to. The latest AIR-1 firmware enables automatic self-calibration, which keeps the SCD40 accurate as long as the sensor sees fresh air (about 420 ppm) at least once a week. If your AIR-1 sits in a space that rarely gets fresh air (a sealed office, a basement, a grow room), turn off the **CO2 Auto Calibration** switch on the device page and follow the [manual calibration guide](../../general/calibrating-and-updating/co2-calibration/) every 1 to 2 years instead.
 
 16\. **Does the AIR-1 work outdoors?**
 
diff --git a/docs/products/air1/setup/general-tips.md b/docs/products/air1/setup/general-tips.md
@@ -134,6 +134,12 @@ Per Sensirion,
 
 The optional CO<sub>2</sub> sensor addon is a great way to add the ability to track CO<sub>2</sub>. CO<sub>2</sub> levels in a closed, poorly ventilated bedroom can quickly rise to concentrations that may impair focus or even pose health risks. Notice the CO2 levels dropping in the image below when the HVAC was turned on overnight!
 
+The latest AIR-1 firmware keeps the SCD40 calibrated automatically. The sensor assumes it sees fresh air (about 420 ppm) at least once a week and corrects its baseline to match, so you no longer need to re-calibrate it manually every 1 to 2 years.
+
+!!! warning "Auto calibration needs regular fresh air"
+
+    If your AIR-1 sits in a space that rarely gets fresh air (a sealed office, a basement, a grow room), automatic self-calibration will slowly drag the CO<sub>2</sub> readings down. Turn off the **CO2 Auto Calibration** switch on the device page and follow the [manual calibration guide](../../../general/calibrating-and-updating/co2-calibration/) every 1 to 2 years instead.
+
 ![](/assets/co2-levels-drop-after-hvac-on.png)
 
 <a href="https://www.dhs.wisconsin.gov/chemical/carbondioxide.htm" target="_blank" rel="noreferrer nofollow noopener">Wisconsin Department of Health CO<sub>2</sub> Level Chart</a>
diff --git a/docs/products/air1/setup/sensor-definitions.md b/docs/products/air1/setup/sensor-definitions.md
@@ -19,7 +19,7 @@ Once added to Home Assistant you can configure different settings for your AIR-1
     | Control | What it does |
     |---------|--------------|
     | **RGB Light** | Three RGB Neopixel LEDs. Click the light bulb or color wheel to change the color. Use the toggle to turn them on or off. |
-    | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the <a href="https://wiki.apolloautomation.com/products/general/calibrating-and-updating/co2-calibration/" target="_blank" rel="noopener">outdoor baseline</a> (about <a href="https://climate.nasa.gov/vital-signs/carbon-dioxide/?intent=121" target="_blank" rel="noopener">420 ppm</a>). Run it outdoors or next to an open window. |
+    | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the <a href="https://wiki.apolloautomation.com/products/general/calibrating-and-updating/co2-calibration/" target="_blank" rel="noopener">outdoor baseline</a> (about <a href="https://climate.nasa.gov/vital-signs/carbon-dioxide/?intent=121" target="_blank" rel="noopener">420 ppm</a>). Run it outdoors or next to an open window. Only needed when **CO2 Auto Calibration** is off. |
     | **Clean SEN55** | Runs the SEN55 fan auto-clean cycle to clear the particulate sensor and refresh its readings. |
 
 === "Sensors"
@@ -66,6 +66,7 @@ Once added to Home Assistant you can configure different settings for your AIR-1
     | **SEN55 Temperature Offset** | 6.0 °C | Calibrates the SEN55 temperature reading to a known value. See the <a href="https://wiki.apolloautomation.com/products/general/temp-hum-calibration/" target="_blank" rel="noopener">temperature &amp; humidity calibration guide</a>. |
     | **SEN55 Humidity Offset** | 0 % | Calibrates the SEN55 humidity reading to a known value. See the <a href="https://wiki.apolloautomation.com/products/general/temp-hum-calibration/" target="_blank" rel="noopener">temperature &amp; humidity calibration guide</a>. |
     | **DPS310 Pressure Offset** | 0.0 hPa | Applies a calibration offset to the DPS310 pressure reading. Range is -100 to +100 hPa in 0.1 hPa steps. Disabled by default. A small subset of devices do not include a DPS310 sensor; if this option reads *Unknown*, your device may be one of these units. |
+    | **CO2 Auto Calibration** | On | Keeps the SCD40 CO₂ sensor calibrated automatically. The sensor assumes it sees fresh air (about <a href="https://climate.nasa.gov/vital-signs/carbon-dioxide/?intent=121" target="_blank" rel="noopener">420 ppm</a>) at least once a week and corrects its baseline to match. Turn it off if the device sits in a space that rarely gets fresh air, then calibrate manually with **Calibrate SCD40 To 420ppm** every 1 to 2 years. |
     | **Sleep Duration** | 5 min | How long the AIR-1 stays in deep sleep between wake cycles (only used when **Prevent Sleep** is off). |
     | **Prevent Sleep** | On | Keeps the device awake instead of deep-sleeping, so it reports continuously. Turn it off to let the AIR-1 deep-sleep between readings for more accurate onboard SEN55 temperature and humidity. |
     | **Factory Reset ESP** | — | Erases settings and returns the device to factory firmware defaults. Disabled by default. |
diff --git a/docs/products/general/calibrating-and-updating/co2-calibration-quick.md b/docs/products/general/calibrating-and-updating/co2-calibration-quick.md
@@ -4,9 +4,13 @@ description: Step by step guide for re-calibrating your SCD40 CO2 sensor
 ---
 # CO<sub>2</sub> Calibration - The Quick method - Desktop Only not mobile
 
-!!! tip "This should be done every 1-2 years."
+!!! info "Your sensor calibrates itself"
 
-    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>) but it requires re-calibration after 1-2 years back to a 420 ppm baseline!
+    The latest Apollo firmware enables the SCD40's automatic self-calibration by default on every device with the CO<sub>2</sub> sensor (AIR-1, R-PRO-1, MSR-2, and MTR-1), so you only need this guide if you turned the **CO2 Auto Calibration** switch off. See the [full calibration guide](../co2-calibration/) for how auto calibration works and when to turn it off.
+
+!!! tip "Calibrate manually every 1 to 2 years when auto calibration is off"
+
+    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>), but with automatic self-calibration turned off it needs re-calibration back to the 420 ppm baseline every 1 to 2 years.
 
 This article will guide you through a simple calibration of your CO<sub>2</sub> sensor for any Apollo Automation device!
 
diff --git a/docs/products/general/calibrating-and-updating/co2-calibration.md b/docs/products/general/calibrating-and-updating/co2-calibration.md
@@ -4,9 +4,15 @@ description: Step by step guide for re-calibrating your SCD40 CO2 sensor
 ---
 # CO<sub>2</sub> Calibration
 
-!!! tip "This should be done every 1-2 years."
+!!! info "Your sensor calibrates itself"
 
-    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>) but it requires re-calibration after 1-2 years back to a 420 ppm baseline!
+    The latest Apollo firmware enables the SCD40's automatic self-calibration by default on every device with the CO<sub>2</sub> sensor (AIR-1, R-PRO-1, MSR-2, and MTR-1). As long as the sensor sees fresh air (about 420 ppm) at least once a week, it corrects its own baseline and you never need to calibrate manually. Airing out the room once a week is enough.
+
+    If your device sits in a space that rarely gets fresh air (a sealed office, a basement, a grow room), automatic self-calibration will slowly drag the readings down. Turn off the **CO2 Auto Calibration** switch on the device page in Home Assistant and calibrate manually with the steps below instead.
+
+!!! tip "Calibrate manually every 1 to 2 years when auto calibration is off"
+
+    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>), but with automatic self-calibration turned off it needs re-calibration back to the 420 ppm baseline every 1 to 2 years.
 
 ![AIR-1 Shown Outdoors for CO2 Calibration Portrait Image](/assets/air-1-co2-calibration-portrait-image-1.jpg "AIR-1 Shown Outdoors for CO2 Calibration")
 
diff --git a/docs/products/msr2/calibrating-co2.md b/docs/products/msr2/calibrating-co2.md
@@ -4,9 +4,13 @@ description: Step by step guide for re-calibrating your SCD40 CO2 sensor
 ---
 # CO<sub>2</sub> Calibration - The Quick method - Desktop Only not mobile
 
-!!! tip "This should be done every 1-2 years."
+!!! info "Your MSR-2 calibrates itself"
 
-    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>) but it requires re-calibration after 1-2 years back to a 420 ppm baseline!
+    The latest MSR-2 firmware enables the SCD40's automatic self-calibration by default. As long as the sensor sees fresh air (about 420 ppm) at least once a week, it corrects its own baseline and you never need to calibrate manually. You only need this guide if the device sits in a space that rarely gets fresh air (a sealed office, a basement, a grow room), where auto calibration slowly drags the readings down. In that case, turn off the **CO2 Auto Calibration** switch on the device page and calibrate manually with the steps below.
+
+!!! tip "Calibrate manually every 1 to 2 years when auto calibration is off"
+
+    The <a href="https://sensirion.com/products/catalog/SCD40" title="Documentation on SCD40 CO<sub>2</sub> Sensor!" target="_blank" rel="noreferrer nofollow noopener">SCD40 CO<sub>2</sub> sensor</a> has a long lifetime (<a href="https://sensirion.com/media/documents/48C4B7FB/66E05452/CD_DS_SCD4x_Datasheet_D1.pdf" title="scd10 datasheet showing lifetime over 10 years" target="_blank" rel="noreferrer nofollow noopener">over 10 years</a>), but with automatic self-calibration turned off it needs re-calibration back to the 420 ppm baseline every 1 to 2 years.
 
 This article will guide you through a simple calibration of your CO<sub>2</sub> sensor for any Apollo Automation device!
 
diff --git a/docs/products/msr2/setup/msr2-sensor-definitions.md b/docs/products/msr2/setup/msr2-sensor-definitions.md
@@ -19,7 +19,7 @@ Once added to Home Assistant you can configure different settings for your MSR-2
     | Control | What it does |
     |---------|--------------|
     | **RGB Light** | Three RGB Neopixel LEDs. Click the light bulb or color wheel to change the color. Use the toggle to turn them on or off. |
-    | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the <a href="https://wiki.apolloautomation.com/products/general/calibrating-and-updating/co2-calibration/" target="_blank" rel="noopener">outdoor baseline</a> (about <a href="https://climate.nasa.gov/vital-signs/carbon-dioxide/?intent=121" target="_blank" rel="noopener">420 ppm</a>). Run it outdoors or next to an open window. |
+    | **Calibrate SCD40 To 420ppm** | Forces a fresh-air calibration of the SCD40 CO₂ sensor to the <a href="https://wiki.apolloautomation.com/products/general/calibrating-and-updating/co2-calibration/" target="_blank" rel="noopener">outdoor baseline</a> (about <a href="https://climate.nasa.gov/vital-signs/carbon-dioxide/?intent=121" target="_blank" rel="noopener">420 ppm</a>). Run it outdoors or next to an open window. Only needed when **CO2 Auto Calibration** is off. |
 
 === "Sensors"
 
@@ -73,6 +73,7 @@ Once added to Home Assistant you can configure different settings for your MSR-2
     | **LTR390 Update Interval** | 60 s | How often the LTR390 light and UV sensors poll (1 to 300 seconds). Disabled by default. |
     | **DPS310 Pressure Offset** | 0.0 hPa | Calibration offset for the DPS310 pressure reading (-100 to +100 hPa in 0.1 hPa steps). Disabled by default. A small subset of devices do not include a DPS310 sensor; if this reads *Unknown*, your device may be one of these units. |
     | **DPS Temperature Offset** | 14.54 °C | Offsets heat from the ESP chip for a more accurate DPS310 temperature reading. A small subset of devices do not include a DPS310 sensor. |
+    | **CO2 Auto Calibration** | On | Keeps the SCD40 CO₂ sensor calibrated automatically. The sensor assumes it sees fresh air (about <a href="https://climate.nasa.gov/vital-signs/carbon-dioxide/?intent=121" target="_blank" rel="noopener">420 ppm</a>) at least once a week and corrects its baseline to match. Turn it off if the device sits in a space that rarely gets fresh air, then calibrate manually with **Calibrate SCD40 To 420ppm** every 1 to 2 years. |
     | **Reduce DB Reporting** | Off | Applies filters so many entities only report when they cross a threshold, using less Wi-Fi airtime and less Home Assistant database space. |
     | **Startup Light Blink** | On | Blinks the RGB LED during the MSR-2's initial boot. |
 
diff --git a/docs/products/mtr1/setup/sensor-definitions.md b/docs/products/mtr1/setup/sensor-definitions.md
diff --git a/docs/products/rpro1/calibrating-co2.md b/docs/products/rpro1/calibrating-co2.md
diff --git a/docs/products/rpro1/setup/rpro1-sensor-definitions.md b/docs/products/rpro1/setup/rpro1-sensor-definitions.md
