AirGradient with ESPHome (Home Assistant)

by Achim Haug


An air quality monitor is a great addition to a smart home system and one of the most popular integration with AirGradient is to Home Assistant with ESPHome.

ESPHome is a super simple way to connect devices to Home Assistant. You just need to flash one time the ESPHome base image on the AirGradient monitor and then configure the monitor with a YAML configuration file.

In case you do not yet have ESPHome installed on your Home Assistant, you can follow the ESPHome Getting Started Guide.

We recommend the ESPHome integrations from AJFriesen and MallocArray.

Supported Models

The ESPHome Versions from AJFriesen and MallocArray both support the Basic and Pro models. AJFriesen also has a configuration for the outdoor monitor.

Supported Features

Both versions support the following:

  • SenseAir S8 CO2 Sensor
  • Plantower PMS5003 Sensor
  • SHT30/SHT40 sensor for Temperature / Humidity (if you use SHT3x you need to adjust the YAML file)
  • OLED Display
  • Parallel connection to the AirGradient dashboard

Features currently only supported by MallocArray:

  • SGP40 for TVOC/NOx Index
  • Push button to switch between Fahrenheit and Celsius
  • When connected to Home Assistant, there are buttons for manual calibration and disable/enable automatic calibrations

Planned Features from MallocArray:

  • Start manual CO2 calibration with long button press
  • Disable display during certain time windows
  • Add config switches in Home Assistant to toggle different display contents

Thank You

We would like to say a big thank you to both AJFriesen and MallocArray to maintain these repositories. If you have any specific questions or problem, please reach out to the AirGradient Forum with many good discussions around ESPHome.