Add documentation for HC8 CO2 sensor (#5613)

* Add documentation for HC8 CO2 sensor

* AI cleanup

---------

Co-authored-by: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>

Author: omartijn

all_automations.json

@@ -136,6 +136,7 @@
     "grove_tb6612fng.run",
     "grove_tb6612fng.standby",
     "grove_tb6612fng.stop",
+    "hc8.calibrate",
     "homeassistant.action",
     "homeassistant.event",
     "homeassistant.service",

content/automations/all_actions.md

@@ -31,6 +31,7 @@ title: ""
 - **fingerprint_grow:** `aura_led_control`, `cancel_enroll`, `delete`, `delete_all`, `enroll`, `led_control`
 - **globals:** `set`
 - **grove_tb6612fng:** `break`, `change_address`, `no_standby`, `run`, `standby`, `stop`
+- **hc8:** `calibrate`
 - **homeassistant:** `event`, `service`, `tag_scanned`
 - **http_request:** `get`, `post`, `send`
 - **htu21d:** `set_heater`, `set_heater_level`

content/components/_index.md

@@ -240,6 +240,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
 "GCJA5","components/sensor/gcja5","gcja5.svg","Particulate","",""
 "GP2Y1010AU0F","components/sensor/gp2y1010au0f","gp2y1010au0f.png","Particulate","",""
 "Grove Multichannel Gas V2","components/sensor/grove_gas_mc_v2","grove-gas-mc-v2.png","NO₂ & CO & Ethanol & Volatile organics","",""
+"HC8","components/sensor/hc8","hc8.png","CO₂","",""
 "HM3301","components/sensor/hm3301","hm3301.jpg","Particulate","",""
 "iAQ-Core","components/sensor/iaqcore","iaqcore.jpg","eCO₂ & Volatile organics","",""
 "MH-Z19","components/sensor/mhz19","mhz19.jpg","CO₂ & Temperature","",""
@@ -380,6 +381,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
 "EMC2101","components/emc2101","emc2101.jpg","Temperature",""
 "ENS160","components/sensor/ens160","ens160.jpg","eCO₂ & Air Quality",""
 "ENS210","components/sensor/ens210","ens210.jpg","Temperature & Humidity",""
+"HC8","components/sensor/hc8","hc8.png","CO₂",""
 "HDC1080","components/sensor/hdc1080","hdc1080.jpg","Temperature & Humidity",""
 "HDC2010","components/sensor/hdc2010","hdc2010.png","Temperature & Humidity",""
 "HHCCJCY10 (MiFlora Pink)","components/sensor/xiaomi_hhccjcy10","xiaomi_hhccjcy10.jpg","Soil moisture & Temperature & Light",""

content/components/sensor/hc8.md

@@ -0,0 +1,79 @@
+---
+description: "Instructions for setting up HC8 CO2 sensors"
+title: "HC8 CO₂ Sensor"
+params:
+  seo:
+    description: Instructions for setting up HC8 CO2 sensors
+    image: hc8.png
+---
+
+The `hc8` sensor platform allows you to use HC8 CO₂ sensors.
+
+{{< img src="hc8-full.png" alt="HC8 CO₂ Sensor" caption="HC8 CO₂ Sensor." width="50.0%" class="align-center" >}}
+
+As the communication with the HC8 sensor is done using UART, you need
+to have an [UART bus](/components/uart) in your configuration with the `rx_pin` connected to the TX pin of the
+HC8 and the `tx_pin` connected to the RX Pin of the HC8 (it's switched because the
+TX/RX labels are from the perspective of the HC8). Additionally, you need to set the baud rate to 9600.
+
+```yaml
+# Example configuration entry
+sensor:
+  - platform: hc8
+    co2:
+      name: HC8 CO2 Value
+```
+
+## Configuration Variables
+
+- **co2** (*Optional*): The CO₂ data from the sensor in parts per million (ppm).
+  All options from [Sensor](/components/sensor).
+
+- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check the
+  sensor. Defaults to `60s`.
+
+- **uart_id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID of the [UART Component](/components/uart) if you want
+  to use multiple UART buses.
+
+- **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID used for actions.
+
+- **warmup_time** (*Optional*, [Time](/guides/configuration-types#time)): The sensor has a warmup period during which it returns inaccurate readings (e.g., 500ppm, 505ppm). This setting discards readings until the warmup time has elapsed (returning `NaN` during warmup). The datasheet specifies a 10-minute preheating time for full accuracy, with 90% accuracy achieved after 3 minutes. Empirical evidence shows that reasonable values are usually returned after about 1 minute. Defaults to `75s`.
+
+{{< anchor "hc8-calibrate_action" >}}
+
+## `hc8.calibrate` Action
+
+This [action](/automations/actions#all-actions) executes baseline calibration command on the sensor with the given ID.
+
+Before executing baseline calibration, ensure the HC8 sensor has been operating in a stable gas environment
+(with known CO₂ concentration) for at least 2 minutes.
+
+**Warning:** Only calibrate the sensor in a known stable environment (e.g., outdoors or in a well-ventilated room).
+Incorrect calibration will result in inaccurate readings.
+
+```yaml
+on_...:
+  then:
+    - hc8.calibrate:
+        id: my_hc8_id
+        baseline: 420  # Current outdoor CO₂ level
+```
+
+You can provide an [action](/components/api#api-device-actions) to perform from Home Assistant
+
+```yaml
+api:
+  actions:
+    - action: hc8_calibrate
+      variables:
+        my_baseline: int
+      then:
+        - hc8.calibrate:
+            id: my_hc8_id
+            baseline: !lambda 'return my_baseline;'
+```
+
+## See Also
+
+- [Sensor Filters](/components/sensor#sensor-filters)
+- {{< apiref "hc8/hc8.h" "hc8/hc8.h" >}}