Skip to content
/ aqi Public

System for sampling a PMS5003 particulate air quality sensor on a raspberry pi and sending it to a database on a server.


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

DIY Air Quality Sensor with Wireless Logging

This is the software for a do-it-yourself air quality sensor system based on the Plantower PMS5003 particulate sensor, which senses PM1.0, PM2.5 and PM10.0 particulates. Each sensor is connected to a Raspberry Pi Zero W, which periodically transmits data wirelessly to a small web server. Any number of sensors are supported. All data is written to a Postgres database, which can be easily visualized with tools such as Grafana. Also included is a 3D printable case I designed to fit the Pi and sensor.

Pi and sensor in case Case with cover Grafana UI


The PMS5003 parsing code is based on Adafruit's and dgj's code.


  • Buy a PMS5003 sensor. They're sold under various brand names on various sites including Adafruit / Mouser, Amazon, BangGood, AliExpress, eBay...

  • Buy a Raspberry Pi Zero W (the WiFi variant) without headers

  • Solder 3 wires from the PMS5003 to the Raspberry Pi. For reference, see the diagrams of the sensor pinout and Pi pinout.

    • Sensor Pin 1 (VCC) to Pi Pin 4 (5V Power)

    • Sensor Pin 2 (GND) to Pi Pin 6 (GND)

    • Sensor Pin 5 (TXD) to Pi Pin 10 (Serial port RX)

  • Optional: 3D print the case I designed. Attach the Pi to the case's integrated standoffs using 4xM2.5 machine screws. The cover also attaches to the case using 4xM2.5 screws.


  • Configure the server that receives the data:

    • Install Postgres on your server. Use a SQL script similar to this example to create a database and table.

    • Install the receiver service's prereqs on your server: python modules aqi and cherrypy

    • Create a configuration file for the receiver service specifying a password of your choice. If you want to use HTTPS (TLS), also specify the path to your HTTPS certficate, key, and cert chain. An example config file can be found here.

      If you'd rather not use HTTPS, leave the certificate configuration lines out of the receiver configuration file. The server will start as HTTP instead of HTTPS. If you do this, make sure you use http:// URLs instead of https:// with the client tools.

    • Run the receiver service using a command line like v3/server/ --config /path/to/config-file.yml. You may wish to use systemd to have the service start automatically; an example systemd config file is here.

    • Test the receiver. Note that by default it runs on port 15000. Run the unit test with a command like

      aqi/v3/test/ --url https://your-server:15000/data/ -s 1000 -n 10 -p 'password-you-picked'

      The return value should be True, indicating success. Check the database table and ensure it has been populated with 10 rows of data (or whatever value you passed to -n) tagged with sensor ID 1000 (or whatever value you passed to -s). A 403 result indicates there was a mismatch between the password you passed to and the one in the receiver's configuration file.

  • Configure each of your RPi sensors:

    • Install the Raspberry Pi OS, configure WiFi, enable ssh

    • Boot the Pi into your new image, connect to it via ssh (or the console). Run raspi-config to configure the serial port to be usable for an external peripheral rather than a console.

    • Use apt-get to install git, python3 and python3-serial . Use git clone to clone this repository into the pi user's home directory.

    • Try running the sensor reader:

      /home/pi/aqi/v3/client/ -v --url https://your-server:15000/data/ -s 1 -p 'password-you-picked'

      The -v (verbose) argument tells the client to print sensor data as it arrives from the serial port; you should see a record about once every second. After 15 seconds it should try to push data to your server. -s 1 means Sensor 1; if you have more than one sensor, give each a unique number.

    • If it works, arrange to have the Pi start automatically on each boot by adding it to systemd; an example config file is here. For example:

      • cp aqi/v3/client/rpi-reader.service /etc/systemd/system

      • vi /etc/systemd/system/rpi-reader.service (customize with your server URL and password)

      • systemctl daemon-reload

      • systemctl start rpi-reader.service

    • Check journalctl -f to look for log messages. You should see rpi-reader reporting that it is sending data to your server every 15 seconds.

  • Optional: install Grafana (or similar tool) to visualize the data from your database.


System for sampling a PMS5003 particulate air quality sensor on a raspberry pi and sending it to a database on a server.








No releases published