Air quality measurement sensor with ESPhome

After seeing all kinds of air purifiers in the market. I got interested in the topic air quality. First, I needed to learn more about how and what to measure, followed by actually measuring the air quality in my home.

I’ve written this walkthrough of how you can build a Particulate Matter Air Quality meter that integrates with your Home Assistant for under 20$, without any soldering or coding skills needed.

It’s build using a PMS5003 particle matter sensor, an ESP board and ESPHome. I’ve found multiple posts covering pieces of this, but no end-to-end tutorial. This tutorial included the use of measurement intervals to extend the lifetime of the laser.

Read the full walkthrough: Build a cheap air quality meter using ESPhome, Home Assistant and a particulate matter sensor

Hope it helps.


You have problems if you have 10mm (millimetre) particles floating in the air!

I think your particle sizes should be in μm (micrometer).

1 Like

That is very good point :crazy_face:. If I had 1 mm particles I would be walking on a layer of dust.

I’ve updated the lovelace code in the article.

Not updating the screenshot :stuck_out_tongue:

1 Like

This is what I’ve been looking for! Wonderful job, I’ve just ordered the sensor (already have the other parts at home) and can’t wait to do this. We have a ventilation system D in our house and our neighbour next door has a stove, and if the wind outside blows in a certain direction then we get all the dirty air from her stove sucked up through the ventilation unit. With this I can hopefully measure when her stove is burning and turn off the ventilation unit with an automation, instead of having to smell the stove while inside. Thank you!

1 Like

good work, already adapted it …my approach was a bit hacky and unstable

1 Like

Just wanted to say I followed your tutorial and thanks to you, I now have a much better working ventilation system. :slight_smile: The sensor is inside the tube that provides the air, and if it reaches a certain treshold then it triggers an automation that will turn off the unit for an hour. After an hour it will turn on the unit again, and then it can check if the air is good again or not.
Sometimes, depending on the wind, air from our neighbor her chimney gets sucked up by our ventilation unit (even though there’s more than enough distance between the intake on our roof and her chimney!), which makes our house smell like smoke and the dirt of the smoke builds up in our vents and on the walls around the fittings, and the filters of our unit turn black as well and need more frequent replacing, thanks to this sensor we’ll no longer have any of those problems!
I didn’t have the housing you suggested though, I used an old gameboy cartridge case, you know the small rectangular transparent ones that were the perfect size for one cartridge. Works just as good. :smiley:

1 Like

Hi everyone,

I’ve attempted to setup my own air quality sensor using Pieters guide however I’m coming across some challenges. I’m using an ESP32-WROOM-32U along with a PMS5003T. I’ve got ESPHome set up properly as I’ve got multiple DIY WEMOS motion and ESP32 temperature sensors working well with it.

I’ve hooked everything up as best as I can according to Pieters guide except for the “d pins”. All the “d pins” on my ESP32-WROOM-32U are apparently reserved for internal use according to multiple sources I should not have anything on those pins. I’ve tried using PINS 33,34,16,17,TX,RX and am having no luck getting a reading. Home Assistant sees the ESP32 board but the air quality readings remain as “unknown”.

I do believe that the PMS5003T does work, as I do hear the fan turn on when the ESP32 is powered up.

Here is the last config I tried and have also tried (I added some comments which hopefully will better explain things).

Any help would be greatly appreciated. Thanks in advance!

  name: esphome-node-2
  platform: ESP32
  board: nodemcu-32s

# Enable logging
  baud_rate: 0
  level: DEBUG
# Enable Home Assistant API

  password: "511c0c9b8bf6d6b6ab51f5d9161f9fd6"

  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
    ssid: "Esphome-Node-2 Fallback Hotspot"
    password: <removed>


  tx_pin: TX # Also tried pin GPIO1 
# tx_pin: GPIO33 #Tried this when physically connected to pin 33
# tx_pin: GPIO17 #Tried this when physically connected to pin 17
  rx_pin: RX
# tx_pin: GPIO32 #Tried this when physically connected to pin 32
# tx_pin: GPIO16 #Tried this when physically connected to pin 16

  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"
# Commented the rest out for testing
#    temperature:
#      name: "Temperature"
#    humidity:
#      name: "Humidity"
#    formaldehyde:
#      name: "Formaldehyde Concentration"

#  - platform: gpio
#    pin: 
#      number: GPIO26
#    id: pms_set
#    name: "Start measuring"
#  - interval: 120s
#    then:
#      - switch.turn_on: pms_set
#      - delay: 20s
#      - switch.turn_off: pms_set

hi @rkhoja5uau, I can’t really answer the questions. The PMS5003 fan will always turn on when provided with power. Have you tried a different ESP? Perhaps an older NodeMCU board?

Thank you for sharing @MagaliDB. Glad to hear that the sensor is working and is providing a solution to make your day-to-day more convenient.

Hi There,

I too used Pieter’s guide (dank je wel Pieter ;-)) on a esp32 it worked flawless.

This is what I have:


  tx_pin: 17
  rx_pin: 16
  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: 5
      name: "Air quality meter Temperature"
      name: "Air quality meter Humidity"
    update_interval: 20s
  - platform: esp32_hall
    name: proximity sensor
    update_interval: 60s
  - platform: gpio
      number: 26
    id: pms_set
    name: "Start measuring"
  - interval: 120s
      - switch.turn_on: pms_set
      - delay: 20s
      - switch.turn_off: pms_set

I too used Pieter’s guide and it worked very well. Thank you! A couple notes below that may help someone else, likely just because this was my first time working with ESPHome.

I’m noticing that the sensor is reading ~20 µg/m³ difference in subsequent readings which is giving me this weird look in my chart. I put in the setting to reduce usage of the sensor. Has anyone seen their sensor do this?

Some of the gotchas:

  1. I have a manual install of HA and wasn’t able to get ESPHome working inside my HA. I used this guide to use the “wizard” and “dashboard”.
  2. Some USBmicro cables are charge-only and won’t work for flashing. If you are having trouble connecting to the ESP32 to flash, it could be that.
  3. I followed this guide for the board and pins. The D# pins isn’t how they numbered on mine; instead the pins are GPIO#.
  4. I was having trouble doing OTA flashing because it was expecting a password and none was provided. Adding a device password and reflashing when plugged in on USB solved that.

To me that happens when I blow out a candle next to the pms or light a match next to it.

I think I had a bum sensor. New one has a 2-3 difference between subsequent readings. Also, don’t put sensor on top of a Sonos (even when not playing anything)…

hi all, i followed the guide and need a little help. i have an ESP8266 nodemcuv2. for some reasons, when hooking up my PMS5003, my ESP node stays offline if I use D3 for the Set pin. If i use other free pins such D0 or D8 for the Set pin, then node does go online but i get no readings from PMS5003. I am getting readings from DHT22 though. Any ideas?

I have the same problem. When I connect the VIN pin the board stays offline.

Did you ever find the reason for this?

Unfortunately not. I wonder if I got a bad board. Will revisit it one of these days

I used a ESP32 board and now it works like it should :slight_smile: The issue was indeed with the ESP8266 board. I don’t know what is wrong with it since the temp works just fine.

1 Like

Oh cool, I’ll give that a try


Thanks for this tuto :slight_smile: verry nice.

I have same problem wich one of my pms5003, the reading value is verry noisy, between 30 seconds window reading i have value go from 4 to 15µg, the first pms5003 seem more stable.
They are on exactly same configuration with esp8266.
So PMS N2 is defect ?

Best regards.