How to: build an air quality monitor that triggers an air filtration system when detected values of particulate (PM2.5) exceeds a certain threshold.
The PMS7003 particulate sensor measures the air quality and transmits data in a serial stream from the transmitter pin (TX) to the receiver pin (RX pin) on the Raspberry Pi.
The website pinout.xyz is a helpful resource with the exact layout and role of each pin for Raspberry Pi.
Refer to the following wiring diagram to connect the Raspberry Pi to the PMS7003 air monitoring device.
- Pin 4 (3V) to VCC (Power)
- Pin 6 (GND) to GND (Ground)
- Pin 8 (TX) to RX (receiver)
- Pin 10 (RX) to TX (transmitter)
To power the Raspberry Pi, you can use the USB cord from earlier to continue providing power from your computer, or use a separate USB power supply.
Make sure to use an appropriate 5V power supply to run the Raspberry Pi, so you don't damage the device.
Set up your air filterMake your own air purifier by combining a box fan and air filter to effectively clean the air in a small to medium sized, closed room.
- Attach the filter to the back of the fan, ensuring the airflow arrow points toward the fan. The fan should pull air through the filter when operating. If the filter will block access to the fan's power knob, now is a good time to switch it to an
on
position. - Secure the filter using 3D-printed clips or duct tape. Write the date when the filter is first used directly on the filter.
- Plug your Kasa smart plug into a power outlet.
- Set up your smart plug and connect it to your local Wifi using the Kasa mobile app from the App Store or Google Play.
- Find your smart plug's IP address on your router's admin page. From a web browser, enter your router's IP address (commonly
192.168.1.1
or192.168.0.1
) and log in using your admin username and password. Look for a section like "Connected Devices, " "Device List, " or "DHCP Clients." Locate your Kasa smart plug by its name, MAC address (shown in the Kasa mobile app), or manufacturer name (usually TP-Link). Make a note of the IP address since we'll need it again soon.
Command line alternative install thepython-kasa
library, and enter the commandkasa discover
to locate the IP address of the connected device.
- Plug the box fan into the Kasa smart plug.
The Raspberry Pi boots from a USB flash drive (or microSD card). You need to install Raspberry Pi OS on a USB flash drive that you will use with your Pi. For more details about alternative methods of setting up your Raspberry Pi, refer to the Viam docs.
Install Raspberry Pi OS- Connect the USB flash drive (or microSD card) to your computer.
- Download the Raspberry Pi Imager and launch it.
- Click CHOOSE DEVICE. Select your model of Pi, which is Raspberry Pi 5.
- Click CHOOSE OS. Select Raspberry Pi OS (64-bit) from the menu.
- Click CHOOSE STORAGE. From the list of devices, select the USB flash drive you intend to use in your Raspberry Pi.
- Configure your Raspberry Pi for remote access. Click Next. When prompted to apply OS customization settings, select EDIT SETTINGS.
- Check Set hostname and enter the name you would like to access the Pi by in that field, for example,
air
. - Select the checkbox for Set username and password and set a username (for example, your first name) that you will use to log into the Pi. If you skip this step, the default username will be
pi
(not recommended for security reasons). And specify a password. - Connect your Pi to Wi-Fi so that you can run
viam-server
wirelessly. Check Configure wireless LAN and enter your wireless network credentials. SSID (short for Service Set Identifier) is your Wi-Fi network name, and password is the network password. Change the sectionWireless LAN country
to where your router is currently being operated.
- Select the SERVICES tab, check Enable SSH, and select Use password authentication.
Be sure that you remember thehostname
andusername
you set, as you will need this when you SSH into your Pi.
- Save your updates, and confirm
YES
to apply OS customization settings. ConfirmYES
to erase data on the USB flash drive. You may also be prompted by your operating system to enter an administrator password. After granting permissions to the Imager, it will begin writing and then verifying the Linux installation to the USB flash drive. - Remove the USB flash drive from your computer when the installation is complete.
Place the USB flash drive into your Raspberry Pi and boot the Pi by plugging it in to an outlet. A red LED will turn on to indicate that the Pi is connected to power.
Make sure you are using a 5V 5A (25W) power supply. USB boot is disabled by default when connected to a 3A power supply, so adequate amperage is required for the optimal performance of your Raspberry Pi 5.
- Once the Pi is started, connect to it with SSH. From a command line terminal window, enter the following command. The text in <> should be replaced (including the < and > symbols themselves) with the user and hostname you configured when you set up your Pi.
ssh <USERNAME>@<HOSTNAME>.local
- If you are prompted "Are you sure you want to continue connecting?", type "yes" and hit enter. Then, enter the password for your username. You should be greeted by a login message and a command prompt.
- Update your Raspberry Pi to ensure all the latest packages are installed
sudo apt update
sudo apt upgrade
Enable communication protocolsLaunch the Pi configuration tool by running the following command
sudo raspi-config
- Use your keyboard to select "Interface Options", and press return.
- Enable the relevant protocols to support our hardware. Since you are using a sensor that communicates over the serial port, enable Serial Port.
- Confirm the options to enable the serial login shell and serial interface. And reboot the Pi when you're finished.
- In the Viam app, create a machine by typing in a name and clicking Add machine.
- Click View setup instructions.
- Install
viam-server
on the Raspberry Pi device that you want to use to communicate with and control your air sensor. Select theLinux / Aarch64
platform for the Raspberry Pi to control the air sensor, and leave your installation method asviam-agent
.
- Use the
viam-agent
to download and installviam-server
on your Raspberry Pi. Follow the instructions to run the command provided in the setup instructions from the SSH prompt of your Raspberry Pi.
The setup page will indicate when the machine is successfully connected.
Add your Raspberry Pi- In the Viam app, find the CONFIGURE tab. It's time to configure your hardware.
- Click the + icon in the left-hand menu and select Component.
- Select
board
, and find thepi5
module. This adds the module for working with the Raspberry Pi 5's GPIO pins. Leave the default nameboard-1
for now. - Notice adding this module adds the board hardware component called
board-1
. The collapsible card on the right corresponds to the part listed in the left sidebar.
- Click Save in the top right to save and apply your configuration changes.
If any problems occur, check under the LOGS tab to see what might be going wrong.
- Click Save in the top right to save and apply your configuration changes.If any problems occur, check under the LOGS tab to see what might be going wrong.
- In the Viam app, click the + icon and select Component. Select
sensor
, find theair:pms7003
module, and click Add module. This module provides the sensor model that supports the specific hardware we are using for this tutorial. Leave the default namesensor-1
for now.
- Notice adding this module adds the sensor hardware component called
sensor-1
as well as a module calledpms7003
which contains the logic for how our Raspberry Pi and air sensor work with each other.
- Save your updates.
- In the Viam app, let's configure the rest of our hardware so that your machine can communicate with the smart plug over wifi. Click the + icon in the left-hand menu and select Component. Select
generic
, and find thekasa:switch
module. This is a generic module that's been configured to use thepython-kasa
library. In other words, it's a layer of abstraction that lets us use the Kasa manufacturer's APIs with Viam.
- Notice adding this module adds the generic hardware component called
generic-1
as well as a module calledkasasmartplug
which contains the logic for how our Raspberry Pi and smart plug work with each other. - Under the CONFIGURE section of the
generic-1
card, add your own smart plug's IP address that you found in a previous step, formatted like the following.
{
"plug_ip": "192.168.1.169"
}
- Save your updates.
- In the Viam app under the CONTROL tab, you can see two hardware components called
generic-1
andsensor-1
. They are your smart plug and air sensor that you configured on the CONFIGURE tab.
- Find the
sensor-1
card, and expand the TEST accordion. The module we added has aGetReadings
function to get the readings from our air sensor. SelectManual refresh
, and then click the refresh icon to manually get the readings.
If any problems occur, check under the LOGS tab to see what might be going wrong.
If you're curious about what these values mean, refer to the U.S. Environmental Protection Agency's basics on particulate matter (PM). For measuring the indoor air quality in your home, we'll be looking at PM2.5, a very small particle size.Test the smart plug
- Next, test that your smart plug is working properly. Make sure the fan is still plugged in to the powered smart plug. Also make sure the fan knob is set to on.
- In the Viam app under the CONTROL tab, find the
generic-1
card, and expand the DOCOMMAND accordion. The module we added has a few functions to control the smart plug. Under the Input section, add the following JSON object (if your fan is still running), and then click Execute to toggle off the smart plug.
{
"toggle_off": []
}
- Now update
"toggle_off"
to"toggle_on"
in the JSON object, and Execute once again. - From the module listing in the registry, you may be able to refer to additional documentation in the module's README to learn about other functions you can use to test your hardware.
At this point, you have configured and tested your machine and peripherals, but nothing is happening automatically. In the next section, program your air monitoring device to be a little smarter. Make your machine periodically get readings, turn on the air filter if the values are high, and turn off again when the values are low.
Create an automation scriptTo configure the machine to automatically run a command to execute a script, use a Viam process. Create a new file on your computer called process.py
.
$ touch process.py
- Copy and paste this sample code into the new file
process.py
. This code will allow your Raspberry Pi to connect to both our sensor and plug and execute our logic. - Now it's time to move your control code to your Raspberry Pi device. SSH into your Raspberry Pi if you're not already SSH'd.
- From the SSH prompt on your Raspberry Pi, install the Python package manager.
$ sudo apt install -y python3-pip
- Install the Viam Python SDK into a new directory called
process
.
$ pip3 install --target=process viam-sdk
- Display the full path of the current directory you are working in on your Raspberry Pi with the
pwd
command. Make a note of this output for the next steps.
$ pwd
- Find the executable path of Python3 to run
process.py
on your Raspberry Pi withwhich Python3
. Again, make a note of this output for the next steps.
$ which Python3
- Run the following command from your computer (not the SSH prompt to your Raspberry Pi) to copy the code from your computer to your Raspberry Pi. In the command, you will copy
process.py
over to your Raspberry Pi, with the section following the colon:
indicating where your file should be copied to on the Raspberry Pi (the path of the directory you are working in on your Raspberry Pi, along with the filename).
$ scp process.py user@host.local:/home/myboard/process/process.py
Configure a Viam process- Now let's allow
viam-server
to run the process as the root user on your Raspberry Pi by configuring a Viam process. In the Viam app under the CONFIGURE tab, click the + icon in the left-hand menu and select Process. - Find the corresponding card to
process-1
. Enter the executable path of Python3 running on your Raspberry Pi that you output from a previous step. Add an argument of theprocess.py
file to run on your Raspberry Pi. Enter the working directory where you want the process to execute.
- Still within the
process-1
card, select the advanced settings icon near the top right corner to review the configuration JSON. Create a newenv
property, and add your environment variables within the new property, formatted like the following with your own credentials.
"env": {
"SENSOR_NAME": "sensor-1",
"PLUG_NAME": "generic-1",
"ROBOT_API_KEY": "your-api-key",
"ROBOT_API_KEY_ID": "your-api-key-id",
"ROBOT_ADDRESS": "your-robot-address"
},
TheSENSOR_NAME
andPLUG_NAME
are the default names for our air sensor and smart plug when added to our Viam machine. Other machine credentials can be found under the CONNECT tab, selecting an SDK, and toggling Include API key to reveal your credentials within the code sample.
- Save your updates.
- You can test the code by updating the
process.py
file on your Raspberry Pi to update thedo_command
when thresholds are low fromtoggle_off
totoggle_on
. Save your code changes, and Restart the machine to see if the fan turns on when the air quality is healthy.
You can either edit the file on your computer and copy the updated file over to your Raspberry Pi usingscp
like we did previously. Or you can use the default command-line text editor on Raspberry Pi OSnano
by enteringnano process.py
from the SSH prompt.
Alternatively, you can blow on the air sensor until the values rise above the threshold.Finishing Touches
Now that your system is working the way you want it, it's time to tidy up our project so it's not a loose jumble of wires and parts.
- 3D print (or buy) an enclosure for your Raspberry Pi and sensor. I found an existing design that I liked to fit a standard Raspberry Pi 5. Using a piece of heavy-duty velcro, I mounted the sensor on top to ensure the sensor could accurately measure the surrounding air.
- You might prefer to have the Raspberry Pi and air sensor within the same case. If you're planning to design your own enclosure, make sure the air sensor receives adequate ventilation and isn't placed too close to the Raspberry Pi chip, as it can get a bit hot.
Now that you have created an air quality monitoring device with a smart plug, you can customize and make it your own. Suggestions for next steps include the following:
- Improve the design: Improve on the design of the air filter, like a Corsi Rosenthal box.
- Modify the sensing: Swap out the sensor to one that detects temperature or humidity.
- Modify the actuation: Swap out the actuation mechanism to turn on a light or trigger a notification.
You can scale up your air monitoring system by creating air sensors in different rooms or different locations, like in this tutorial to Monitor Air Quality with a Fleet of Sensors.
- Sensor fusion: Collect and aggregate data from different types of sensors to specify the precise conditions that trigger the actuation using Viam data management and machine learning.
- Build a mobile app: Use Viam's SDK libraries to build a Flutter mobile app or TypeScript web app.
This codelab was originally published on Viam.
Comments