Make Your Own Air Quality Sensor Using ESPHome

Air Quality Sensor Blog Post Pinterest Pin

I’ve had a general curiosity about the air quality in and around my home. We use primarily hydronic heating and thus don’t get much airflow without opening the windows. We do have a couple of family members that are more susceptible to allergies than others. Before buying an air purifier, I decided it would be a better idea to measure what the air quality is like in various places in my house. I like to only buy sensors that are smart (connected) and integrate with Home Assistant. I looked at a few sensors but settled in on making my own, and I’m glad I did. Here’s how you can make your own smart air quality sensor.

This page contains affiliate links. If you purchase an item using an affiliate link I will receive a small commission at no cost to you. Affiliates do not influence my recommendations. Read my disclosures for more information.


I started off initially looking for air purifiers that also monitored the air. As always, I was looking for ones that are connected and work with Home Assistant. A couple of purifiers that I looked at were the Xiaomi Mi Air Purifier 3C and the meross Smart Wi-Fi Purifier, both of which work with Home Assistant. But then I started wondering if I even need an air purifier. I was just thinking it might be good since we have some people who get allergies in my house, and we don’t have a lot of airflow in the house.

This led me to look at starting with an air quality monitor first. I found it much harder to find an air quality monitor that works with Home Assistant without the purifier. Most of my research led to people building their own sensors, and I was starting to see why. Here are a few of the sensors I looked into, and why I didn’t choose them.

  • Aqara Indoor Air Quality Monitor — This one looked really promising as it is Zigbee powered and a lot of Aqara products work with Home Assistant. But the reports I heard were that this particular sensor has problems with Home Assistant. It constantly drops its connection and doesn’t always report the air quality metrics.
  • Eve Room — Although this had all the functionality I wanted, the sensor by itself costs as much or more than the air purifiers I was looking at!
  • IKEA VINDRIKTNING — This one is really inexpensive, but the tutorials I’ve seen require you to connect it up to an ESP8266 chip to get it to work with Home Assistant.

There are probably others that some have gotten to work with Home Assistant, but at this point, I was willing to try building my own.

A little bit about measuring air quality

I’ve already got CO2 sensors, smoke detectors, and explosive gas detectors in my home. I’m primarily interested in air quality. I’m not an expert on air quality but here’s what I’ve learned…

Most of the air quality metrics seem to use the PM2.5 readings. PM2.5 refers to atmospheric particulate matter (PM) that has a diameter of fewer than 2.5 micrometers. These particles can only be seen with a microscope.

Studies have linked prolonged exposure to unhealthy levels of PM2.5 to heart and lung disease. On a clear day, PM2.5 concentration will typically be less than 5 μg/m3 (micrograms/cubic meter). Exposure to PM2.5 levels above 35.4 μg/m3 over a 24-hour period is generally considered unhealthy. Consistent exposure to levels above 12 μg/m3 over a longer period of time is also unhealthy. Good air purifiers reduce PM2.5 levels.

See also  5 Downsides Of Having A Smart Home

Materials needed for this project

The materials list below might seem long, but there’s a good chance you probably have some of these around. Since I’m a tinkerer, I already had most of these things on hand. You probably have some type of electrical tape, a micro-USB adapter, and a wire stripper available to you.

You can also substitute some of these items, but these will definitely work:

Alternatively, you can buy the air quality and humidity/temperature sensors from AliExpress for less than you can on Amazon, but they might take a while to arrive. Here are the links in case you are interested:

Here are the tools I used to put this together:

I recommend these and other tools for DIY smart home projects in my HomeTechHacker Shop.

One last thing… Make sure there is good Wi-Fi where you plan to place the sensor.

Building your DIY ESPHome air quality sensor

ESPHome is a system to control your ESP8266/ESP32 chips using simple yet powerful configuration files and control them remotely through home automation systems. You configure how your chip interacts and controls sensors and other devices using YAML (YAML Ain’t Markup Language YAML). YAML is a human-friendly serialization language often used in configuration files like the ones for Home Assistant. I previously used ESPHome to make a fingerprint scanner that can open and close my garage.

Step 1: Install ESPHome

There are many ways to install ESPHome. It works on Windows, macOS, and Linux. Also, it has a Docker container. You can even do it in Home Assistant. I’m old school and like the command line, so I went with the Linux Python install using the steps below. If you want to install it another way or on another platform, the links at the end of this article will point you in the right direction.

To install ESPHome via Python, first, confirm your system has at least Python 3.7:

python3 --version

Then, install ESPHome via pip:

pip3 install --user esphome

That’s it! ESPHome is installed.

Step 2: Wire up the sensors

You can use many different techniques to wire and solder the connections. I used lever nuts and a solderless breadboard. Below is a pinout diagram for the NodeMCU to help clarify the neccessary connections.

And here are the components I’m going to wire up:

air quality sensor, nodemcu, and DHT Humidity + Temperature sensor

To start, I cut one end of the red and black connector wire to expose the individual wires. Then I connected the wires as indicated in this table:

See also  5 Best Home Tech Upgrades That Will Help Sell Your Home
Pin #
Connects toPin #
2——->GND (any GND will do)
3——->GPIO0 (D3)
4——->GPIO12 (D6)
5——->GPIO13 (D7)
PMS5003 to NodeMCU connections

Pins 6, 7, and 8 don’t need to connect to anything.

Note the PMS5003 air quality sensor pins are numbered 1 to 8 from top to bottom as indicated in this diagram:

The DHT22 sensor just has 3 connections. They are sometimes labeled differently depending on where you got your DHT22 sensor, but this is how they should connect to the NodeMCU:

Pin #
Connects toPin #
GND (-)——->GND (any GND will do)
Data ——->GPIO2 (D4)
VSS (+)——->Any 3v3 (3.3V) connection
DHT to NodeMCU connections

Here’s what mine looks like wired up, and then put into a project box. As I mentioned earlier, I used lever nuts instead of soldering, but I’ll probably go back and solder the connections together.

Step 3: Create the ESPHome configuration for your chip

I used the ESPHome wizard to create the initial configuration file:

esphome wizard aqs.yaml

This command asked me a few questions, including credentials to my Wi-Fi network and a password to secure ESPHome installation on the chip (this is optional, but recommended). Then it created the file aqs.yaml in the esphome directory in my filesystem.

I then modified the aqs.yaml with a configuration specific to ESPHome interacting with the air quality, temperature, and humidity sensors. I’m going to put the configuration below and then mention a couple of things about it.

  name: airqualitysensor1

  board: nodemcu

# Enable logging

# Enable Home Assistant API
  password: "xxxxxxxx"

  password: "xxxxxxxx"

#to secure firmware updates over OTA
  password: "xxxxxxxxx"

  ssid: "your-ssid"
  password: "xxxxxxx"

  # Enable fallback hotspot (captive portal) in case wifi connection fails
    ssid: "aqs1"
    password: "xxxxxxxxxxx"


  tx_pin: D6
  rx_pin: D7
  baud_rate: 9600

  - platform: pmsx003
    type: PMSX003
      name: "Particulate Matter <1.0µm Concentration"
      name: "Particulate Matter <2.5µm Concentration"
      name: "Particulate Matter <10.0µm Concentration"
  - platform: dht
    pin: D4
      name: "AQS Meter 1 Temperature"
      name: "AQS Meter 1 Humidity"
    update_interval: 60s

  - platform: gpio
      number: D3
    id: measure_aq
    name: "Start AQS Sensor 1"

  - interval: 120s
      - switch.turn_on: measure_aq
      - delay: 30s
      - switch.turn_off: measure_aq

Here are a few key points about this configuration file:

  • When we add this ESPHome device to Home Assistant, it will create 5 sensors:
    1. A sensor for musing particulate matter less than 1.0µm
    2. A sensor for musing particulate matter less than 2.5µm
    3. A sensor for musing particulate matter less than 10.0µm
    4. A humidity sensor
    5. A temperature sensor
  • It will also create a switch (viewable and controllable from Home Assistant) that controls when the sensor reads values. Instead of having the sensor constantly read values, I have it read values for 30 seconds out of every two minutes. This will extend the life of the sensor. You can set these to whatever you want. You can also manually trigger this measurement in Home Assistant using this switch. This is why we connected PSM5003 pin 3 to the NodeMCU GPIO0 (D3) pin.
  • Make sure to put in your own SSID and password for Wi-Fi settings and OTA updates.

Before adding the sensor to Home Assistant, I recommend you give the sensor a static IP or use your router to give it a static lease (which is what I do). If you want to give your sensor a static IP you can modify the Wi-Fi section of your ESPHome configuration file as follows:

  ssid: "your-ssid"
  password: "xxxxxxxx"

  # Optional manual IP. Use values that work in your home network environment

Step 4: Flash the ESPHome configuration to your NodeMCU

All that’s left is to flash the configuration to the NodeMCU. You’ll need to use a USB cable to connect the NodeMCU chip to your computer to flash the ESPHome configuration the first time. After that, it should connect to your Wi-Fi and be flashable over your network. I simply used the following command to flash my chip:

esphome run aqs.yaml

Replace aqs.yaml with whatever you named your configuration file. You may need to tell it what device your chip is connected to. For me, that was /dev/ttyUSB0. Then I just waited about a minute and then I had a fully functioning air quality sensor!

See also  Xiaomi Mi 3C Smart Air Purifier Review

Step 5: Add the air quality sensor to Home Assistant

While the sensor is up and running head over to the Home Assistant UI. Go to Settings->Devices & Services->Integrations and select + Add Integration at the bottom right of the screen. Select the ESPHome integration. You’ll be asked to input the IP Address or hostname for the ESPHome sensor you created in the earlier steps. And, if you protected the chip with a password, you’ll also need to enter it during this setup. Home Assistant will set up the integration and you’ll have a device that looks like:

Air quality sensor device page in Home Assistant


I set out to test the sensor in various locations in my home. All readings were low and consistent with good air quality. I checked the temperature and humidity against known working sensors and verified my DIY sensor’s readings were accurate.

But how could I know the air quality measurements were good if they always read the same thing? Well, I put the sensor in the garage and then turned on my car (a twin-turbo V6 engine) for a minute. the sensor readings immediately spiked up to the not-so-great range (see chart below).

Air Quality sensor graph garage door closed
Measurements after driving my car out of the garage and leaving the garage door closed.

Interestingly, it took about 18 hours for the readings to go back to regular while mostly leaving the garage door closed. I did open the garage for a minute or two during this time. Can you determine about what time I did it by looking at the chart above?

After levels went back to normal I performed a similar test. I started my car and came and went (ran some errands) a couple of times over the course of few hours, closing the garage door except for the time it took to enter and exit the garage. Then, I left the garage open. It took only about 10 minutes of an open garage for levels to get back to normal (see the chart below). Just goes to show that airflow really can help improve air quality.

Air Quality sensor graph garage door opened
What happens after opening the garage door when air quality has diminished.

I repeated these tests after putting the sensor in the project box, just to make sure it could still get good readings. The results were the same, so this box works well.

Here’s a final picture of what it looks like inside the project box, with a few openings for air to circulate for proper readings:

Air quality sensor inside project box

Editor’s note: I’ve since improved this design with a smaller project box and also added regional air quality monitoring to Home Assistant. You can read about those improvements in this article.

Editor’s note II: I also decided to buy a smart air purifier.

For more information

Here is a listing of the places where you can get more information on ESPHome, the air quality, temperature and humidity sensors, and the sources for my learning for this project:

Final thoughts

This was another fun ESPHome project (the fingerprint scanner I built was fun too). Turns out, the air quality around my house is good. I’ll be interested to find out how it is affected when the air quality outside is bad, or the gas oven has been left on for a while. I’ve decided I’ll build a second sensor so I can have two to make measurements around the house.

Do you have an air purifier and/or an air quality sensor? Let me know if you do or if you build one using these instructions in the comments or on Twitter.

Share this:

2 thoughts on “Make Your Own Air Quality Sensor Using ESPHome”

Comments are closed.

Make Your Own Air Quality Sensor Using ESPHome

by HomeTechHacker time to read: 9 min