Skip to content
ESPHome - Smart Home Made Simple

Air Quality Index (AQI)

The aqi sensor platform allows you to compute an Air Quality Index from PM2.5 and PM10 particulate matter sensor readings. This sensor works with any PM sensor source, such as Pmsx003, Hm3301, Sds011, or Sps30.

NOTE

The value produced by this component is a PM-only AQI estimate, not a full US EPA Air Quality Index. The official EPA AQI is calculated across five pollutant categories — ground-level ozone (O₃), particle pollution (PM2.5 and PM10), carbon monoxide (CO), sulfur dioxide (SO₂), and nitrogen dioxide (NO₂) — and reports the worst sub-index as the overall AQI. Without sensors for ozone, CO, SO₂, and NO₂, this component cannot produce a true composite AQI; the output reflects particulate matter conditions only and may significantly underestimate actual air quality risk when other pollutants are elevated.

Additionally, the official EPA PM2.5 AQI is defined using 24-hour averaged concentrations (or the EPA NowCast algorithm for real-time hourly estimates). This component applies the AQI breakpoint formula to instantaneous sensor readings, which produces more volatile values that do not correspond to either the daily AQI or the NowCast AQI used in official reporting. See the EPA Technical Assistance Document for full methodology details.

NOTE

This platform replaces the deprecated aqi option previously available in the HM3301 component. The standalone platform is more flexible as it works with any PM sensor.

Two calculation types are supported:

  • AQI: US EPA Air Quality Index (0-500 scale)
  • CAQI: European Common Air Quality Index (0-100+ scale)
# Example configuration entry
sensor:
  - platform: pmsx003
    type: PMSX003
    pm_2_5:
      id: pm25_sensor
      name: "PM2.5"
    pm_10_0:
      id: pm10_sensor
      name: "PM10"


  - platform: aqi
    name: "Air Quality Index"
    pm_2_5: pm25_sensor
    pm_10_0: pm10_sensor
    calculation_type: AQI

Configuration variables

Section titled “Configuration variables”

  • pm_2_5 (Required, ID of a Sensor): The sensor providing PM2.5 concentration readings in µg/m³.

  • pm_10_0 (Required, ID of a Sensor): The sensor providing PM10 concentration readings in µg/m³.

  • calculation_type (Required, enum): The AQI calculation standard to use. Must be one of:

    • AQI: US EPA Air Quality Index breakpoint formula applied to PM2.5 and PM10 only. Returns values from 0-500, where higher values indicate worse air quality. This is not a full EPA AQI — the official standard covers five pollutant categories and also requires ozone, CO, SO₂, and NO₂ measurements. Based on the EPA Technical Assistance Document.

    • CAQI: European Common Air Quality Index. Returns values from 0 upward, where higher values indicate worse air quality. Typically 0-25 is very low, 25-50 is low, 50-75 is medium, 75-100 is high, and >100 is very high.

  • All other options from Sensor.

Example with CAQI

Section titled “Example with CAQI”
sensor:
  - platform: hm3301
    pm_2_5:
      id: pm25
      name: "PM2.5"
    pm_10_0:
      id: pm10
      name: "PM10"


  - platform: aqi
    name: "European Air Quality Index"
    pm_2_5: pm25
    pm_10_0: pm10
    calculation_type: CAQI

See Also

Section titled “See Also”