Is PMS5003 Laser Particulate Matter Sensor Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Laser dust sensor measuring fine airborne particles (PM1.0 PM2.5 PM10) for air purifier automation and smoke detection.
Wiring PMS5003 Laser Particulate Matter Sensor to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VCC (pin 1) | 5V | The fan needs it. Pin numbering counts from the red wire of the supplied lead. |
| GND (pin 2) | GND | |
| SET (pin 3) | unconnected | Sleep control. The config sleeps the sensor over the serial protocol instead, so it can stay unwired. |
| RX (pin 4) | GPIO17 | The sensor's receive line goes to the host's TX. |
| TX (pin 5) | GPIO16 | And its transmit line to the host's RX. The sensor talks at 3.3V, so no divider. |
| RESET (pin 6) | unconnected |
Host pins are the ones the configuration on this page uses. Move a pin here and change it in the YAML — they are documented together so they cannot disagree.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | UART Serial / 3.3V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | PM1.0 (ug/m3) PM2.5 (ug/m3) PM10 (ug/m3) Particle Count Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Intermediate |
| Factory Reset Instruction | Hold BOOT button for 3s. |
Wire, Flash, Adopt, Check
Wire it up
Follow the wiring table above. The ESP32 pins there are the ones the configuration uses, so if you move one, change it in both places.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_pms5003_esphome.yaml and run esphome run emb_esp32_pms5003_esphome.yaml. The first flash goes over USB. If it is not detected, hold BOOT button for 3s to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
Three PM values appear in Home Assistant within about a minute of boot and track a struck match held near the inlet. Values of zero with the fan running are TX and RX crossed the wrong way; a fan that never spins is the 5V rail.
ESPHome Configuration
Starting configuration for PMS5003 Laser Particulate Matter Sensor on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for PMS5003 Laser Particulate Matter Sensor
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_pms5003_esphome
friendly_name: "PMS5003 Laser Particulate Matter Sensor"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
uart:
rx_pin: GPIO16
tx_pin: GPIO17
baud_rate: 9600
sensor:
- platform: pmsx003
type: PMSX003
# With an interval set, the component sleeps the sensor between readings
# (fan and laser off) — the fan is the part that wears out.
update_interval: 120s
pm_1_0:
name: "PM 1.0"
pm_2_5:
name: "PM 2.5"
pm_10_0:
name: "PM 10.0"
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
What Appears in Home Assistant
Atmospheric-corrected µg/m³ with the matching device classes, so Home Assistant charts them and the air quality cards pick them up.
Optional: counts per 0.1L in six size bins from 0.3µm to 10µm, if you add them under the same platform.
Known Problems and Fixes
5V power, 3.3V signals
The sensor runs on 5V and its serial lines are 3.3V logic. Feeding 5V into its RX kills the input; taking its TX straight to an ESP32 pin is fine.
The fan is the wear item
Running continuously, the fan and laser are the first things to go. update_interval: 120s in the config sleeps the sensor between readings; the component wakes it, waits for the airflow to settle, reads, and puts it back to sleep.
The first half minute reads low
After power-up the airflow has not stabilised and the numbers run under. The component allows for it after a sleep; after a cold boot, ignore the first reading.
Humidity inflates the count
Above roughly 70% relative humidity, particles absorb water and grow, and the sensor counts the bigger particle. Readings on a damp night are not wrong, but they are not comparable to a dry afternoon either.
Placement
Away from the node's own heat and from anything that blows on it. The inlet is the small hole on the side; the fan exhausts through the top. Block either and the reading drifts.
Variants
type: PMSX003 covers the PMS1003, 5003, 7003 and A003. The PMS5003T and 5003ST add temperature, humidity and formaldehyde and take their own type values.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for PMS5003 Laser Particulate Matter Sensor? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-pms5003-esphome)
Frequently Asked Questions
Does PMS5003 Laser Particulate Matter Sensor work without an internet connection?
How is PMS5003 Laser Particulate Matter Sensor powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
PMSA003I I2C Particulate Sensor
The same sensor family on I2C, which frees the UART and simplifies wiring.
SPS30 Laser Particulate Sensor
Sensirion's equivalent, with a longer-rated fan and a self-cleaning cycle.
SEN55 Environmental Sensor Node
Particulates plus VOC, NOx, temperature and humidity in one module.
SDS011 Laser PM2.5 Dust Sensor
A bigger, older laser sensor; still accurate, louder fan.