ESPHome Air Quality Sensor (eCO2 and TVOC)

Total Volatile Organic Compounds (TVOC) are a group of compounds present in the air (VOC), these are emitted from everyday activities, which are colourless and some odourless and some are toxic. TVOC monitoring is an efficient way to detect exposure to toxic VOCs. For example, applied to home monitoring, higher TVOC level may require ventilation on your room.

TVOC ppb Reference Table

This parameter can be measured using a CCS811 sensor, which is a gas sensor that detect a wide range of Volatile Organic Compounds (VOCs) and equivalent carbon dioxide (eCO2), mainly for indoor air quality monitoring.

The CCS811 can be connected with a Wemos D1 ESP8266 module and to Home Assistant using a few ESPHome code lines.

Wiring diagram

ESPHome code

It’s based on the ccs811 sensor platform. Official documentation (LINK)

  name: air-quality-sensor

  board: d1_mini_lite

# Enable logging

# Enable Home Assistant API

  password: "8bd619f3f098c60427d9ffd802422226"

  ssid: !secret wifi_ssid
  password: !secret wifi_password


  sda: D2
  scl: D1

  - platform: ccs811
      name: "eCO2"
      id: ccs811_eco2
      name: "Total Volatile Organic Compound"
      id: ccs811_tvoc
    address: 0x5A
    update_interval: 60s

Sensor Calibration

Calibrating Baseline

The sensor needs some calibration at first boot, so follow this steps:

o have consistent values, you need to specify a static baseline value (the calibration factor). To do this, first let the sensor boot up with no baseline set and let the sensor calibrate itself. After around 20-30 minutes you can then view the remote logs on the ESP. The next time the sensor is read out, you will see a log message with something like baseline=0xA483.

  • Startup the sensor
  • Open LOG window from your ESPHome Dashboard
  • The log will show state 0.000
  • Wait around 15 minute until the log will to show something similar to baseline=0x147F
  • Copy that value and paste it in your code sensor section
  • Save and Re-Install the code

Home Assistant Integration

  • Go to Settings Integration menu
  • The new device should automatically be available
  • Click CONFIGURE and add it to your HA instance
  • Two new entities will be available
  • If you like it, you can create a Gauce card