# IoT Air Quality Sensor with Adafruit IO
## Overview
Breathe easy, knowing that you can track and sense the quality of the air (and environment!) around you with an **IoT Air Quality Sensor.** This sensor **measures PM2.5 (particles that are 2.5 microns or smaller in diameter) dust concentrations, temperature and humidity**. This sensor is small, wall-mountable (indoors or outdoors), weatherproof, and only requires a WiFi network connection and an AC outlet.
You'll **assemble an open source air quality sensor.** Then, you'll **program the sensor using CircuitPython** to measure air quality data and periodically **send measurements to [Adafruit IO, our incredible IoT Service](http://io.adafruit.com/welcome).** Finally, you'll create a beautiful Adafruit IO dashboard to **visualize your sensor data from anywhere in the world**.
## Why would I want to build an Air Quality Monitor?
### Citizen Science
Soon after the Fukushima nuclear disaster in Japan, trustworthy information about radiation levels was publicly unavailable. An international volunteer organization, [Safecast](https://safecast.org/about/), designed devices for radiation mapping and openly shared their measurements to the public.
With the increasing amount of natural disasters, **building an open source air quality monitor is a step towards citizens being able to monitor and share data about essential environmental measurements without the need to trust an environmental regulatory body or wait for an official government response**.
### Open Source Science
While building this sensor, we noticed a large amount of the current air quality sensor offerings on the market are closed source software and have a private API. This means it's impossible to send data from a DIY air quality sensor to their web service. If we purchased one of the company sponsored sensors and the company went out of business, we'd be left with a sensor which couldn't send data to the internet.
Building an own open source air quality monitoring sensor lets you control the hardware going into your IoT air quality sensor, the software running on the sensor (right down to the firmware!) and the web platform. We are using [Adafruit.io](http://io.adafruit.com/welcome) for this guide, but you are free to modify the code to send data to other services such as Google Cloud Platform, Amazon AWS IoT, or Microsoft Azure IoT.
## Parts
Featured
### Adafruit Feather M4 Express - Featuring ATSAMD51
[Adafruit Feather M4 Express - Featuring ATSAMD51](https://www.adafruit.com/product/3857)
It's what you've been waiting for, the Feather M4 Express featuring ATSAMD51. This Feather is fast like a swift, smart like an owl, strong like a ox-bird (it's half ox, half bird, OK?) This feather is powered by our new favorite chip, the **ATSAMD51J19** - with...
In Stock
[Buy Now](https://www.adafruit.com/product/3857)
[Related Guides to the Product](https://learn.adafruit.com/products/3857/guides)
Featured
### Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor
[Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor](https://www.adafruit.com/product/4264)
Give your Feather project a _lift_ with the Adafruit AirLift FeatherWing - a FeatherWing that lets you use the powerful ESP32 as a WiFi co-processor. You probably have your favorite Feather ([like the Feather M4](https://www.adafruit.com/product/3857)) that comes with its own...
In Stock
[Buy Now](https://www.adafruit.com/product/4264)
[Related Guides to the Product](https://learn.adafruit.com/products/4264/guides)
Featured
### PM2.5 Air Quality Sensor and Breadboard Adapter Kit
[PM2.5 Air Quality Sensor and Breadboard Adapter Kit](https://www.adafruit.com/product/3686)
Breathe easy, knowing that you can track and sense the quality of the air around you with th **e PM2.5 Air Quality Sensor with Breadboard Adapter** particulate sensor. [Mad Max & Furiosa definitely should have hooked up one of...](https://en.wikipedia.org/wiki/Mad_Max)
In Stock
[Buy Now](https://www.adafruit.com/product/3686)
[Related Guides to the Product](https://learn.adafruit.com/products/3686/guides)
Featured
### Adafruit BME280 I2C or SPI Temperature Humidity Pressure Sensor
[Adafruit BME280 I2C or SPI Temperature Humidity Pressure Sensor](https://www.adafruit.com/product/2652)
Bosch has stepped up their game with their new BME280 sensor, an environmental sensor with temperature, barometric pressure and humidity! This sensor is great for all sorts of indoor environmental sensing and can even be used in both I2C and SPI!
This precision sensor from...
In Stock
[Buy Now](https://www.adafruit.com/product/2652)
[Related Guides to the Product](https://learn.adafruit.com/products/2652/guides)
Featured
### FeatherWing Doubler - Prototyping Add-on For All Feather Boards
[FeatherWing Doubler - Prototyping Add-on For All Feather Boards](https://www.adafruit.com/product/2890)
This is the **FeatherWing Doubler** - a prototyping add-on and more for all Feather boards. This is similar to our [FeatherWing Proto](https://www.adafruit.com/products/2884) except there are two! The magic of the Doubler comes when stacking a Feather and another...
In Stock
[Buy Now](https://www.adafruit.com/product/2890)
[Related Guides to the Product](https://learn.adafruit.com/products/2890/guides)
Featured
### Flanged Weatherproof Enclosure With PG-7 Cable Glands
[Flanged Weatherproof Enclosure With PG-7 Cable Glands](https://www.adafruit.com/product/3931)
Whether you're raiding tombs or traversing nuclear fallout wastelands, this is the most heavy-duty enclosure for your project! Weatherproof? Check. Tough polycarbonate cover? Check. Built-in gasket seal? Oh yeah, check.
Store your project safe and sound in this **Flanged...**
In Stock
[Buy Now](https://www.adafruit.com/product/3931)
[Related Guides to the Product](https://learn.adafruit.com/products/3931/guides)
### Silicone Cover Stranded-Core Ribbon Cable - 4 Wires 1 Meter Long
[Silicone Cover Stranded-Core Ribbon Cable - 4 Wires 1 Meter Long](https://www.adafruit.com/product/3889)
For those who are fans of our silicone-covered wires, but are always looking to _up their wiring game_. We now have **Silicone Cover Ribbon cables!** These may look _a lot_ like
In Stock
[Buy Now](https://www.adafruit.com/product/3889)
[Related Guides to the Product](https://learn.adafruit.com/products/3889/guides)
### Lithium Ion Polymer Battery Ideal For Feathers - 3.7V 400mAh
[Lithium Ion Polymer Battery Ideal For Feathers - 3.7V 400mAh](https://www.adafruit.com/product/3898)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of **400mAh** for a total of about 1.9 Wh. If you need a larger (or smaller!)...
In Stock
[Buy Now](https://www.adafruit.com/product/3898)
[Related Guides to the Product](https://learn.adafruit.com/products/3898/guides)
### 5V 2A Switching Power Supply w/ USB-A Connector
[5V 2A Switching Power Supply w/ USB-A Connector](https://www.adafruit.com/product/1994)
Our 5V 2A USB power adapter is the perfect choice for powering single-board computers like Raspberry Pi, BeagleBone, or anything else that's power-hungry!
This adapter was specifically designed to provide 5.25V, not 5V, but we still call it a 5V USB adapter. We did this on purpose to...
In Stock
[Buy Now](https://www.adafruit.com/product/1994)
[Related Guides to the Product](https://learn.adafruit.com/products/1994/guides)
### USB A/Micro Cable - 2m
[USB A/Micro Cable - 2m](https://www.adafruit.com/product/2185)
This is your standard USB A-Plug to Micro-USB cable. It's 2 meters long so you'll have plenty of cord to work with for those longer extensions.
Out of Stock
[Buy Now](https://www.adafruit.com/product/2185)
[Related Guides to the Product](https://learn.adafruit.com/products/2185/guides)
# IoT Air Quality Sensor with Adafruit IO
## Adafruit IO Setup
## Obtain Adafruit IO Key
You will need your Adafruit IO username and secret API key.
[**Navigate to Adafruit IO**](https://io.adafruit.com/profile) and **click the Adafruit IO Key button** to retrieve these values. Write them down in a safe place, you'll need them later.
## Create Group
This guide will use multiple Adafruit IO feeds to store sensor values. To organize these feeds, you will need to create a new group.
**Navigate** to [your Adafruit IO Feeds page](https://io.adafruit.com/feeds).
**Click** _Actions -\> Create a New Group_
**Name the group** _Air Quality Sensor_. You can optionally set a description.
**Click Create**
## Add Feeds to Group
Lets add a few feeds to the Air Quality Sensor group to hold sensor measurements and metadata.
**Click** _Actions -\> Create a New Feed_
**Name the feed** _AQI_
**Click** _Add to Groups _and **select the Air Quality Sensor group**
**Click Create**
Repeat the process in the step above to **create feeds for category (AQI category), temperature, and humidity**.
Before proceeding, make sure your Air Quality Sensor group looks exactly like the screenshot below.
## Adafruit IO Dashboard
Dashboards allow you to visualize data and control Adafruit IO connected projects from any modern web browser. We'll be adding gauge widgets to visualize data from the air quality sensor in real-time and charts to display data historically.
Navigate to [the dashboards page on Adafruit IO](https://io.adafruit.com/dashboards).
**Click Actions -\> Create New Dashboard**
**Name the dashboard** My Air Quality Sensor
**Click Create **
You should see your new dashboard pop-up in the list of Dashboards. **Click the My Air Quality Sensor dashboard link** to navigate to the dashboard page.
You should see an empty dashboard. Let's fill it with blocks!
**Click the '+' button on your dashboard to add a new block**.
Let's add a text block to display the air quality condition (Good, Acceptable, Moderate, etc) sent by the sensor.
From the Create a New Block picker, **click the Text Block**
From the Create a New Block picker, **click the Text Block**
On the Choose Feed picker, **select the category feed**
Under Block Settings:
- **Set Block Title** to AQI Category
- **Set Font Size** to Large
- **Click** Create Block
You should see the AQI Category text box appear on the dashboard. We'll organize the dashboard last - let's add the next block.
## Add Gauge Block for Real-Time AQI
The United States Environmental Protection Agency [uses an Air Quality Index (AQI) to communicate air quality.](https://www.airnow.gov/aqi/) While computing the AQI according to the EPA requires a 24 hour average, this gauge displays the real-time AQI.
- **Note:** This guide uses air quality breakpoints and conditions developed by the USA EPA. Other countries have environmental protection agencies with similar countries with air quality indexes using PM2.5 particles. [Check out this Wikipedia page for more info](https://en.wikipedia.org/wiki/Air_quality_index#Indices_by_location).
**Click** Create a New Block
**Select ** the Gauge Block
**Select** the _aqi_ feed
Under Block Settings:
- **Set Block Title** to _Real-Time AQI_
- **Set the Gauge Max Value** to 500
- **Set Gauge Width** to 50px
- **Remove the "Value" text placeholder** **from Gauge Label** , AQI is a unit-less value.
- **Set High Warning Value to 151**
- [This AQI value corresponds with the EPA's "unhealthy" AQI category](https://en.wikipedia.org/wiki/Air_quality_index#Computing_the_AQI).
- **Set Decimal Places** to **0**
- **Tick the Show Icon checkbox**
- **Set Icon ** to **w:cloudy-windy**
- **Click Create Block**
Your dashboard should now show the AQI category text block and the Real-Time AQI gauge.
## Add Gauge Block for Humidity
We'll add another gauge block to display the BME280's humidity reading.
**Click** Create a New Block
**Select ** the Gauge Block
**Select** the _humidity_ feed
Under Block Settings:
- **Set Block Title** to _Current Humidity_
- **Set Gauge Width** to 50px
- **Remove the "Value" text placeholder** **from Gauge Label**
- **Tick the Show Icon checkbox**
- **Set Icon ** to **w:humidity**
- **Click Create Block**
## Add Gauge Block for Temperature
We'll add another gauge block to display the BME280's temperature reading.
**Click** **Create a New Block**
**Select ** the **Gauge** **Block**
**Select** the _humidity_ feed
Under Block Settings:
- **Set Block Title** to _Current Temperature_
- **Set Gauge Width** to 50px
- **Set the Gauge label** to **Degrees F or Degrees C**
- **Click the Show Icon checkbox**
- **Set Icon ** to **thermometer**
- **Click Create Block**
## Add Line Charts
While real-time visualization of PM2.5 measurements over time is immediately useful - looking at the air quality index over time will help you understand the AQI as a more accurate average. Adafruit IO's Line Charts update dynamically whenever new values are pushed to the feed.
Since most environmental groups use a 24-hour average of AQI measurements, we'll create a new line chart block to display the AQI measurements for the past day.
**Click** **Create a New Block**
**Select** the **Line Chart Block**
**Select** the _aqi_ **feed**
Under Block Settings:
- **Set Block Title** to **AQI - 24 Hours**
- **Set Show History ** to **24 Hours**
- Click the **Draw Grid Lines** checkbox
**Click Create Block**
Let's make another line chart block to display the AQI from the past week.
**Click** **Create a New Block**
**Select** the ** Line Chart Block**
**Select** the _aqi_ **feed**
Under Block Settings:
- **Set Block Title** to **AQI - 24 hours**
- **Set Show History ** to **7 Days**
- Click the ** Draw Grid Lines** checkbox
**Click Create Block**
## Organize Dashboard
You can drag the dashboard blocks around to re-organize your dashboard.
Before moving on, make sure your dashboard contains the same blocks as the screenshot below
# IoT Air Quality Sensor with Adafruit IO
## Wiring
## Attach Cables to BME280 and PMS5003 Adaptor
The PMS5003 comes with a breadboard adapter for you to easily hook the sensor up to a microcontroller with UART.
While you could use a female/female header adaptor, wires can easily disconnect. You'll want to solder cables from the FeatherWing Doubler to the breadboard adaptor for a stronger hold.
Let's begin by removing the pins from the breadboard adaptor.
Place the breadboard adaptor into a [vise](https://www.adafruit.com/product/151) and flip the board over.
Using a pair of [flush diagonal cutters](https://www.adafruit.com/product/152), snip between the pins of the plastic header. Make sure to **snip the plastic between each pin**. This will make it easier to pull the pins from the adaptor when you de-solder them.
**Tin the tip of your soldering iron**. Then, **press the edge of your soldering iron against a solder-blob** on the adaptor to heat and liquify the solder.
While **heating the pin, use a pair of tweezers (or needle-nose pliers), wiggle the pin out of the hole in the PCB until it's removed**.
Using desoldering wick or a desoldering pump, r **emove old/excess solder from the adaptor**.
**Cut a long piece of silicone stranded-core ribbon cable from the 1M of cable.** It's always better to have more cable then less!
Then, **peel four cables off the silicone stranded-core ribbon cable.** **Strip a small amount of the silicone sheath from each wire and tin the end of it**.
**Solder a length of wire to each of the VCC, GND, TXD, and RST pins on the adaptor.** Your final adaptor should look like the following:
Cut a new length of silicone stranded-core ribbon cable and **repeat this process for the BME280** breakout. Both breakouts should now have cables attached.
## Wiring
Next, you'll need to connect the BME280 and PM2.5 adaptor to the FeatherWing Doubler. We suggest using one of the two prototyping spots on the front of the FeatherWing Doubler.
**Make the following connections between the BME280 and the FeatherWing:**
- **Board 3V** to **sensor VIN**
- **Board 3V** to **sensor CS**
- **Board GND** to **sensor GND**
- **Board SCL** to **sensor SCK**
- **Board SDA** to **sensor SDI**
**Then, make the following connections between the PM2.5 adaptor and the FeatherWing:**
- **Sensor VCC ** to ** board 5V**
- **Sensor GND ** to ** board GND**
- **Sensor TX ** to ** board RX**
- Remember: **RX does not connect to RX!**
After making the connections above, your FeatherWing should look like the following.
Let's move on to assembling the enclosure.
# IoT Air Quality Sensor with Adafruit IO
## Assembly
## Assemble the FeatherWing Doubler
Plug the Feather M4 into the FeatherWing Doubler.
Then, plug the AirLift FeatherWing into the FeatherWing Doubler
Plug the PM25 sensor into the adaptor breakout.
## Test-Fit Enclosure
Next, you'll want to make sure the enclosure fits the hardware you assembled and check the lengths of the wires you soldered.
Using a phillips head screwdriver, open the enclosure.
Place the PM25 sensor inside the enclosure. It should fit between the four mounting standoffs.
Make sure the sensor's fan faces the bottom of the enclosure and the cable faces the top of the enclosure (the side with the cable glands).
Place the FeatherWing on top of the PM25 sensor and cover it with the lid.
If you noticed the cables you cut were too long or if the solder joints broke, you'll want to fix them now.
## Add Air-Holes to Enclosure
Next, you will use a handheld drill, a drill press, or a rotary tool to add some holes to the bottom of the enclosure. This will allow air particles to enter the enclosure.
The PM2.5 sensor's fan intake is located on the bottom right hand side of the enclosure. The BME280 sensor will also be placed in the same location.
Using a marker and ruler, **mark a few spots at the _bottom right_ of the enclosure**.
**Use a drill and a small-diameter drill bit to drill holes into the enclosure**. Be sure to **use a slow speed on your drill** , the enclosure's material is softer than it seems and you can accidentally drill through too quickly.
Do NOT add a filter to the bottom of the enclosure - it will prevent dust particles from being picked up by the fan.
Using an adhesive of your choice - **affix the PM2.5 sensor to the bottom of the case.**
We used 3M Command Strips for a more temporary hold. If you're also using Command Strips - be sure to place the wall (black) side against the enclosure.
Cut a Micro-USB cable in half with a pair of wire cutters.
Thread the Micro-USB end through the right cable gland.
You'll need to strip and splice together the two ends of the USB cable. [For more information about splicing wires, see this Learning System Guide](https://learn.adafruit.com/make-it-glow-how-to-solder-neopixels-a-beginners-guide/splicing-wires).
Add two adhesive strips to each side of the FeatherWing Doubler and insert the USB cable into the Feather M4.
You may need to re-organize cables at this point. We stored all of the cables in the top section in the case. **Then, press the FeatherWing Doubler onto the PM2.5 sensor**.
**Tighten the cable gland to form a weatherproof seal around the USB cable**. Make sure the left cable gland is also tightened.
**Place the transparent cover over the enclosure** , ensuring the gasket which runs around the enclosure is properly sealed.
**Secure the cover to the enclosure using the four machine screws** included with the enclosure.
That's it! Your air quality sensor is assembled and wired. The next steps will cover adding code to the Feather M4 and using the air quality sensor with Adafruit IO.
# IoT Air Quality Sensor with Adafruit IO
## CircuitPython Setup
## Install CircuitPython
Some CircuitPython compatible boards come with CircuitPython installed. Others are _CircuitPython-ready_, but need to have it installed. As well, you may want to update the version of CircuitPython already installed on your board. The steps are the same for installing and updating.
- To **install (or update) your CircuitPython board**, [follow this page and come back here when you've successfully installed (or updated) CircuitPython.](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython)
## CircuitPython Library Installation
First make sure you are running the [latest version of Adafruit CircuitPython](https://github.com/adafruit/circuitpython/releases) for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle) matching your version of CircuitPython.
CircuitPython hardware shows up on your computer operating system as a flash drive when connected via usb. The flash drive is called **CIRCUITPY** and contains a number of files. You will need to add additional files to enable the features of this project.
First, create a folder on the drive named lib if it is not already there.
Ensure your board's **lib** folder has the following files and folders ** ** copied over. The version of the files must be the same major version as your version of CircuitPython (i.e. 5.x for 5.x, 6.x for 6.x etc.)
- **adafruit\_bus\_device**
- **adafruit\_esp32spi**
- **adafruit\_io**
- **adafruit\_logging.mpy**
- **adafruit\_requests.mpy**
- **adafruit\_pm25**
- **neopixel.mpy**
- **simpleio.mpy**
- **adafruit\_bme280.mpy**
# IoT Air Quality Sensor with Adafruit IO
## Internet Connect!
# Connect to WiFi
OK, now that you have your **settings.toml** file set up - you can connect to the Internet.
To do this, you need to first install a few libraries, into the lib folder on your **CIRCUITPY** drive. Then you need to update **code.py** with the example script.
Thankfully, we can do this in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file. Extract the contents of the zip file, open the directory **examples/** and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your **CIRCUITPY** drive.
Your **CIRCUITPY** drive should now look similar to the following image:
Info: Update to CircuitPython 9.2.x or later to use this example.
https://github.com/adafruit/Adafruit_CircuitPython_ESP32SPI/blob/main/examples/esp32spi_simpletest.py
And save it to your board, with the name **code.py**.
Don't forget you'll also need to create the **settings.toml** file as seen above, with your WiFi ssid and password.
In a serial console, you should see something like the following. For more information about connecting with a serial console, view the guide [Connecting to the Serial Console](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console).
```terminal
>>> import wifitest
ESP32 SPI webclient test
ESP32 found and in idle mode
Firmware vers. 1.7.5
MAC addr: 24:C9:DC:BD:0F:3F
HomeNetwork RSSI: -46
HomeNetwork RSSI: -76
Fios-12345 RSSI: -92
FiOS-AB123 RSSI: -92
NETGEAR53 RSSI: -93
Connecting to AP...
Connected to HomeNetwork RSSI: -45
My IP address is 192.168.1.245
IP lookup adafruit.com: 104.20.39.240
Ping google.com: 30 ms
Fetching text from http://wifitest.adafruit.com/testwifi/index.html
----------------------------------------
This is a test of Adafruit WiFi!
If you can read this, its working :)
----------------------------------------
Fetching json from http://wifitest.adafruit.com/testwifi/sample.json
----------------------------------------
{'fun': True, 'company': 'Adafruit', 'founded': 2005, 'primes': [2, 3, 5], 'pi': 3.14, 'mixed': [False, None, 3, True, 2.7, 'cheese']}
----------------------------------------
Done!
```
Going over the example above, here's a breakdown of what the program is doing:
- Initialize the ESP32 over SPI using the SPI port and 3 control pins:
```python
esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)
#...
else:
spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
```
- Get the socket pool and the SSL context, and then tell the `adafruit_requests` library about them.
```python
pool = adafruit_connection_manager.get_radio_socketpool(esp)
ssl_context = adafruit_connection_manager.get_radio_ssl_context(esp)
requests = adafruit_requests.Session(pool, ssl_context)
```
- Verify an ESP32 is found, checks the firmware and MAC address
```auto
if esp.status == adafruit_esp32spi.WL_IDLE_STATUS:
print("ESP32 found and in idle mode")
print("Firmware vers.", esp.firmware_version)
print("MAC addr:", ":".join("%02X" % byte for byte in esp.MAC_address))
```
- Perform a scan of all access points it can see and print out the name and signal strength.
```python
for ap in esp.scan_networks():
print("\t%-23s RSSI: %d" % (ap.ssid, ap.rssi))
```
- Connect to the AP we've defined here, then print out the local IP address. Then attempt to do a domain name lookup and ping google.com to check network connectivity. (Note sometimes the ping fails or takes a while; this isn't a big deal.)
```python
print("Connecting to AP...")
while not esp.is_connected:
try:
esp.connect_AP(ssid, password)
except OSError as e:
print("could not connect to AP, retrying: ", e)
continue
print("Connected to", esp.ap_info.ssid, "\tRSSI:", esp.ap_info.rssi)
print("My IP address is", esp.ipv4_address)
print(
"IP lookup adafruit.com: %s" % esp.pretty_ip(esp.get_host_by_name("adafruit.com"))
)
```
Now we're getting to the really interesting part of the example program. We've written a library for web fetching web data, named [adafruit\_requests](https://github.com/adafruit/Adafruit_CircuitPython_Requests). It is a lot like the regular Python library named [requests](https://requests.readthedocs.io/en/latest/). This library allows you to send HTTP and HTTPS requests easily and provides helpful methods for parsing the response from the server.
- Here is the part of the example program is fetching text data from a URL.
```python
TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html" # Further up in the program
# ...
print("Fetching text from", TEXT_URL)
r = requests.get(TEXT_URL)
print('-' * 40)
print(r.text)
print('-' * 40)
r.close()
```
- Finally, here the program is fetching some JSON data. The `adafruit_requests` library will parse the JSON into a Python dictionary whose structure is the same as the structure of the JSON.
```auto
JSON_URL = "http://wifitest.adafruit.com/testwifi/sample.json" # Further up in the program
# ...
print("Fetching json from", JSON_URL)
r = requests.get(JSON_URL)
print('-' * 40)
print(r.json())
print('-' * 40)
r.close()
```
# Advanced Requests Usage
Want to send custom HTTP headers, parse the response as raw bytes, or handle a response's http status code in your CircuitPython code?
We've written an example to show advanced usage of the requests module below.
To use with CircuitPython, you need to first install a few libraries, into the lib folder on your **CIRCUITPY** drive. Then you need to update **code.py** with the example script.
Thankfully, we can do this in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file. Extract the contents of the zip file, open the directory **examples/** and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your **CIRCUITPY** drive.
https://github.com/adafruit/Adafruit_CircuitPython_Requests/blob/main/examples/esp32spi/requests_esp32spi_advanced.py
Your **CIRCUITPY** drive should now look similar to the following image:
# WiFi Manager
The way the examples above connect to WiFi works but it's a little finicky. Since WiFi is not necessarily so reliable, you may have disconnects and need to reconnect. For more advanced uses, we recommend using the `WiFiManager` class. It will wrap the connection/status/requests loop for you - reconnecting if WiFi drops, resetting the ESP32 if it gets into a bad state, etc.
Here's a more advanced example that shows using the `WiFiManager` and also how to fetch the current time from a web source.
https://github.com/adafruit/Adafruit_CircuitPython_ESP32SPI/blob/main/examples/esp32spi_localtime.py
# Further Information
For more information on the basics of doing networking in CircuitPython, see this guide:
### Networking in CircuitPython
[Networking in CircuitPython](https://learn.adafruit.com/networking-in-circuitpython)
# IoT Air Quality Sensor with Adafruit IO
## Code Usage
## Text Editor
Adafruit recommends using the Mu editor for editing your CircuitPython code. You can get more info in [this guide](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor).
Alternatively, you can use any text editor that saves simple text files.
## Settings File Setup
Open the **settings.toml** file on your CircuitPython device using Mu or your favorite text editor. You're going to edit this file to enter your WiFi credentials along with your keys.
- Replace `"your-wifi-ssid"` with **your Wi-Fi SSID**
- Replace `"your-wifi-password"` with **your Wi-Fi password**
- Replace `"your-aio-username"` with **your Adafruit IO username**
- Replace `"your-super-long-aio-key"` with **your Adafruit IO key**
```python
# This file is where you keep secret settings, passwords, and tokens!
# If you put them in the code you risk committing that info or sharing it
CIRCUITPY_WIFI_SSID="your-wifi-ssid"
CIRCUITPY_WIFI_PASSWORD="your-wifi-password"
ADAFRUIT_AIO_USERNAME="your-aio-username"
ADAFRUIT_AIO_KEY="your-super-long-aio-key"
timezone="America/New_York" # http://worldtimeapi.org/timezones
latitude=MY_LAT # https://www.latlong.net/
longitude=MY_LON
elevation=MY_ELE
```
Next, let's to add your location's latitude, longitude and altitude data to the settings file. Entering your location will allow the Map Block to show an image of your sensor's location.
**For privacy reasons, we suggest limiting your location data to your city, town, or municipality**. Instead of setting our sensor's location to Adafruit's exact address, we'll set it to New York City.
[Navigate to this website to find your location's GPS latitude, longitude and altitude coordinates](https://www.maps.ie/coordinates.html) and enter your city/town.
In the settings file, change `MY_LAT`, `MY_LON`, and `MY_ELE` to the values obtained from the website above.
## Code
Click the Download: Project Zip File link below in the code window to get a zip file with all the files needed for the project. Copy **code.py** from the zip file and place on the **CIRCUITPY** drive.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Adafruit_IO_Air_Quality/code.py
Once all the files are copied from your computer to the Feather, you should have the following files on your **CIRCUITPY** drive:
## Code Usage
Before permanently installing the sensor, you should test the sensor to make sure the sensors are wired correctly and the board can publish data to Adafruit IO.
**Plug the sensor into a mini-USB power cable**. and **navigate to the Adafruit IO Dashboard you created earlier**. Every ten minutes all the blocks populate with values.
Since the air quality index values are measured in real-time, they may be higher than EPA NowCast real-time AQI values. After a day of the sensor capturing and logging data, the AQI - 1 Day line chart block will display air quality measurements every hour for the previous day.
## Install Sensor
Before deploying your air quality monitor, make sure there's a WiFi network in the location you're planning on deploying to. If you're unsure about connectivity - stand exactly where you want to install the sensor, open your mobile phone/tablet, connect to your WiFi network and navigate to [Adafruit IO](http://io.adafruit.com/) with your web browser.
If the test above was successful, let's move on to installing the sensor. The mounting technique you may use for this sensor varies by installation type.
### Indoor Mounting
If you want to mount your sensor indoors, we suggest using 3M Command Strips.
Peel the plastic backing off a command strip and affix it to the back of the enclosure. Attach a _second_ command strip to the wall.
Press the enclosure into the wall and hold it for a few seconds.
## Outdoor Mounting
You can also install this sensor outdoors. Make sure you have a WiFi connection and A/C power available.
The flanged weatherproof enclosure has four mounting holes with a 6mm diameter. You can pick up the appropriate screws from your local hardware store's website.
# IoT Air Quality Sensor with Adafruit IO
## Code Walkthrough
## Hardware Setup and Configuration
The first chunk of code imports the **settings.toml** file containing WiFi details, Adafruit IO credentials, and location metadata.
```python
# Get WiFi details and Adafruit IO keys, ensure these are setup in settings.toml
# (visit io.adafruit.com if you need to create an account, or if you need your Adafruit IO key.)
ssid = getenv("CIRCUITPY_WIFI_SSID")
password = getenv("CIRCUITPY_WIFI_PASSWORD")
aio_username = getenv("ADAFRUIT_AIO_USERNAME")
aio_key = getenv("ADAFRUIT_AIO_KEY")
```
```python
# AirLift FeatherWing
esp32_cs = DigitalInOut(board.D13)
esp32_reset = DigitalInOut(board.D12)
esp32_ready = DigitalInOut(board.D11)
spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
status_pixel = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.2)
wifi = adafruit_esp32spi_wifimanager.WiFiManager(esp, ssid, password, status_pixel=status_pixel)
```
The PM2.5 sensor is initialized with UART. The BME280 sensor is also initialized with I2C.
```python
# Connect to a PM2.5 sensor over UART
reset_pin = DigitalInOut(board.G0)
reset_pin.direction = Direction.OUTPUT
reset_pin.value = False
uart = busio.UART(board.TX, board.RX, baudrate=9600)
pm25 = PM25_UART(uart, reset_pin)
# Connect to a BME280 sensor over I2C
i2c = busio.I2C(board.SCL, board.SDA)
bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c)
```
## Reading and Calculating AQI
The `calculate_aqi` function calculates a real-time qualitative Air Quality Index (AQI). This function does not use the quantitative EPA NOWCast Real-Time AQI function since this code does not store values over time. Values are stored and processed by Adafruit IO.
The function takes a sensor reading of PM2.5 size particles and returns both the AQI value and the AQI category.
The Air Quality Index developed by the EPA is divided into **six ** categories. Each of the six category names has an index. These categories range from the least amount of health concern ("Good") to immediate health concern where you'll need to don a respirator ("Hazardous").
The breakpoints (_CLow, CHigh, ILow, IHigh_) in this function are provided by the United State's Environmental Protection Agency (EPA), [for more information on the AQI calculation check out this Wikipedia article](https://en.wikipedia.org/wiki/Air_quality_index#Computing_the_AQI).
- If you are in a country other than the United States, this Wikipedia article [contains air quality indices for locations all over the world](https://en.wikipedia.org/wiki/Air_quality_index#Indices_by_location).
```python
### Sensor Functions ###
def calculate_aqi(pm_sensor_reading):
"""Returns a calculated air quality index (AQI)
and category as a tuple.
NOTE: The AQI returned by this function should ideally be measured
using the 24-hour concentration average. Calculating a AQI without
averaging will result in higher AQI values than expected.
:param float pm_sensor_reading: Particulate matter sensor value.
"""
# Check sensor reading using EPA breakpoint (Clow-Chigh)
if 0.0 <= pm_sensor_reading <= 12.0:
# AQI calculation using EPA breakpoints (Ilow-IHigh)
aqi_val = map_range(int(pm_sensor_reading), 0, 12, 0, 50)
aqi_cat = "Good"
elif 12.1 <= pm_sensor_reading <= 35.4:
aqi_val = map_range(int(pm_sensor_reading), 12, 35, 51, 100)
aqi_cat = "Moderate"
elif 35.5 <= pm_sensor_reading <= 55.4:
aqi_val = map_range(int(pm_sensor_reading), 36, 55, 101, 150)
aqi_cat = "Unhealthy for Sensitive Groups"
elif 55.5 <= pm_sensor_reading <= 150.4:
aqi_val = map_range(int(pm_sensor_reading), 56, 150, 151, 200)
aqi_cat = "Unhealthy"
elif 150.5 <= pm_sensor_reading <= 250.4:
aqi_val = map_range(int(pm_sensor_reading), 151, 250, 201, 300)
aqi_cat = "Very Unhealthy"
elif 250.5 <= pm_sensor_reading <= 350.4:
aqi_val = map_range(int(pm_sensor_reading), 251, 350, 301, 400)
aqi_cat = "Hazardous"
elif 350.5 <= pm_sensor_reading <= 500.4:
aqi_val = map_range(int(pm_sensor_reading), 351, 500, 401, 500)
aqi_cat = "Hazardous"
else:
print("Invalid PM2.5 concentration")
aqi_val = -1
aqi_cat = None
return aqi_val, aqi_cat
```
The `sample_aq_sensor` function samples a PM2.5 sensor. Since the PlanTower updates the counts every 2.3 seconds, yet outputs data every 1 second. The sensor could possibly take two successive, identical, samples. This function samples the sensor for 2.3 seconds and averages the amount of samples over the number of samples obtained in that time interval.
- For more information about how the PM2.5 sensor calculates and outputs data, [check out this page of the PM2.5 sensor's learn guide featuring StanJ's analysis report](https://learn.adafruit.com/pm25-air-quality-sensor/usage-notes).
```python
def sample_aq_sensor():
"""Samples PM2.5 sensor
over a 2.3 second sample rate.
"""
aq_reading = 0
aq_samples = []
# initial timestamp
time_start = time.monotonic()
# sample pm2.5 sensor over 2.3 sec sample rate
while time.monotonic() - time_start <= 2.3:
try:
aqdata = pm25.read()
aq_samples.append(aqdata["pm25 env"])
except RuntimeError:
print("Unable to read from sensor, retrying...")
continue
# pm sensor output rate of 1s
time.sleep(1)
# average sample reading / # samples
for sample in range(len(aq_samples)):
aq_reading += aq_samples[sample]
aq_reading = aq_reading / len(aq_samples)
aq_samples.clear()
return aq_reading
```
The `read_bme_280` function reads the BME280 sensor temperature and humidity and returns it as a tuple. If you set `USE_CELSIUS` at the top of the code to `True`, the temperature value will be returned in Celsius instead of Fahrenheit.
```python
def read_bme280(is_celsius=False):
"""Returns temperature and humidity
from BME280 environmental sensor, as a tuple.
:param bool is_celsius: Returns temperature in degrees celsius
if True, otherwise fahrenheit.
"""
humid = bme280.humidity
temp = bme280.temperature
if not is_celsius:
temp = temp * 1.8 + 32
return temperature, humid
```
## Adafruit IO Setup and Configuration
Next is the Adafruit IO initialization and configuration. An instance of the Adafruit IO HTTP client is created.
```python
# Create an instance of the Adafruit IO HTTP client
io = IO_HTTP(aio_username, aio_key, wifi)
```
The feeds you created earlier are initialized using calls to `get_feed`.
```python
# Describes feeds used to hold Adafruit IO data
feed_aqi = io.get_feed("air-quality-sensor.aqi")
feed_aqi_category = io.get_feed("air-quality-sensor.category")
feed_humidity = io.get_feed("air-quality-sensor.humidity")
feed_temperature = io.get_feed("air-quality-sensor.temperature")
```
The location values (latitude, longitude, elevation) are pulled from your settings file and initialized as a tuple, `location_metadata`.
```python
# Set up location metadata from settings.toml file
location_metadata = {
"lat": getenv("latitude"),
"lon": getenv("longitude"),
"ele": getenv("elevation"),
}
```
## Main Loop
The `while True` loop fetches the current time from Adafruit IO's time API (we don't need a real-time-clock or timezone calculations) and reads/publishes sensor data to Adafruit IO when a time interval elapses.
### Obtaining time from Adafruit IO
The Adafruit IO time service does not replace a time-synchronization service like NTP, but it can help you figure out your local time on an Internet of Things device that doesn't have a built in clock.
Instead of using a software-based timer, this code will fetch the current time from Adafruit IO using a call to `receive_time()` every 30 seconds. Then, it will keep track of the minutes elapsed.
```python
try:
print("Fetching time...")
cur_time = io.receive_time()
print("Time fetched OK!")
# Hourly reset
if cur_time.tm_min == 0:
prv_mins = 0
except (ValueError, RuntimeError) as e:
print("Failed to fetch time, retrying\n", e)
wifi.reset()
wifi.connect()
continue
if cur_time.tm_min >= prv_mins:
print("%d min elapsed.."%elapsed_minutes)
prv_mins = cur_time.tm_min
elapsed_minutes += 1
```
### Sample and Publish Data to Adafruit IO
When `PUBLISH_INTERVAL` elapses, the loop will sample the air quality sensor and environmental sensor. Values are printed to the REPL.
Once values are obtained, each value is published to its respective Adafruit IO Feed using calls to `io.send_data`.
Finally, the sensor sleeps 30 seconds before running again.
```python
if elapsed_minutes >= PUBLISH_INTERVAL:
print("Sampling AQI...")
aqi_reading = sample_aq_sensor()
aqi, aqi_category = calculate_aqi(aqi_reading)
print("AQI: %d"%aqi)
print("Category: %s"%aqi_category)
# temp and humidity
print("Sampling environmental sensor...")
temperature, humidity = read_bme280(USE_CELSIUS)
print("Temperature: %0.1f F" % temperature)
print("Humidity: %0.1f %%" % humidity)
# Publish all values to Adafruit IO
print("Publishing to Adafruit IO...")
try:
io.send_data(feed_aqi["key"], str(aqi), location_metadata)
io.send_data(feed_aqi_category["key"], aqi_category)
io.send_data(feed_temperature["key"], str(temperature))
io.send_data(feed_humidity["key"], str(humidity))
print("Published!")
except (ValueError, RuntimeError) as e:
print("Failed to send data to IO, retrying\n", e)
wifi.reset()
wifi.connect()
continue
# Reset timer
elapsed_minutes = 0
time.sleep(30)
```
## Guide Products
### Adafruit Feather M4 Express - Featuring ATSAMD51
[Adafruit Feather M4 Express - Featuring ATSAMD51](https://www.adafruit.com/product/3857)
It's what you've been waiting for, the Feather M4 Express featuring ATSAMD51. This Feather is fast like a swift, smart like an owl, strong like a ox-bird (it's half ox, half bird, OK?) This feather is powered by our new favorite chip, the **ATSAMD51J19** - with...
In Stock
[Buy Now](https://www.adafruit.com/product/3857)
[Related Guides to the Product](https://learn.adafruit.com/products/3857/guides)
### Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor
[Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor](https://www.adafruit.com/product/4264)
Give your Feather project a _lift_ with the Adafruit AirLift FeatherWing - a FeatherWing that lets you use the powerful ESP32 as a WiFi co-processor. You probably have your favorite Feather ([like the Feather M4](https://www.adafruit.com/product/3857)) that comes with its own...
In Stock
[Buy Now](https://www.adafruit.com/product/4264)
[Related Guides to the Product](https://learn.adafruit.com/products/4264/guides)
### PM2.5 Air Quality Sensor and Breadboard Adapter Kit
[PM2.5 Air Quality Sensor and Breadboard Adapter Kit](https://www.adafruit.com/product/3686)
Breathe easy, knowing that you can track and sense the quality of the air around you with th **e PM2.5 Air Quality Sensor with Breadboard Adapter** particulate sensor. [Mad Max & Furiosa definitely should have hooked up one of...](https://en.wikipedia.org/wiki/Mad_Max)
In Stock
[Buy Now](https://www.adafruit.com/product/3686)
[Related Guides to the Product](https://learn.adafruit.com/products/3686/guides)
### Adafruit BME280 I2C or SPI Temperature Humidity Pressure Sensor
[Adafruit BME280 I2C or SPI Temperature Humidity Pressure Sensor](https://www.adafruit.com/product/2652)
Bosch has stepped up their game with their new BME280 sensor, an environmental sensor with temperature, barometric pressure and humidity! This sensor is great for all sorts of indoor environmental sensing and can even be used in both I2C and SPI!
This precision sensor from...
In Stock
[Buy Now](https://www.adafruit.com/product/2652)
[Related Guides to the Product](https://learn.adafruit.com/products/2652/guides)
### FeatherWing Doubler - Prototyping Add-on For All Feather Boards
[FeatherWing Doubler - Prototyping Add-on For All Feather Boards](https://www.adafruit.com/product/2890)
This is the **FeatherWing Doubler** - a prototyping add-on and more for all Feather boards. This is similar to our [FeatherWing Proto](https://www.adafruit.com/products/2884) except there are two! The magic of the Doubler comes when stacking a Feather and another...
In Stock
[Buy Now](https://www.adafruit.com/product/2890)
[Related Guides to the Product](https://learn.adafruit.com/products/2890/guides)
### Flanged Weatherproof Enclosure With PG-7 Cable Glands
[Flanged Weatherproof Enclosure With PG-7 Cable Glands](https://www.adafruit.com/product/3931)
Whether you're raiding tombs or traversing nuclear fallout wastelands, this is the most heavy-duty enclosure for your project! Weatherproof? Check. Tough polycarbonate cover? Check. Built-in gasket seal? Oh yeah, check.
Store your project safe and sound in this **Flanged...**
In Stock
[Buy Now](https://www.adafruit.com/product/3931)
[Related Guides to the Product](https://learn.adafruit.com/products/3931/guides)
### Silicone Cover Stranded-Core Ribbon Cable - 4 Wires 1 Meter Long
[Silicone Cover Stranded-Core Ribbon Cable - 4 Wires 1 Meter Long](https://www.adafruit.com/product/3889)
For those who are fans of our silicone-covered wires, but are always looking to _up their wiring game_. We now have **Silicone Cover Ribbon cables!** These may look _a lot_ like
In Stock
[Buy Now](https://www.adafruit.com/product/3889)
[Related Guides to the Product](https://learn.adafruit.com/products/3889/guides)
### Lithium Ion Polymer Battery Ideal For Feathers - 3.7V 400mAh
[Lithium Ion Polymer Battery Ideal For Feathers - 3.7V 400mAh](https://www.adafruit.com/product/3898)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of **400mAh** for a total of about 1.9 Wh. If you need a larger (or smaller!)...
In Stock
[Buy Now](https://www.adafruit.com/product/3898)
[Related Guides to the Product](https://learn.adafruit.com/products/3898/guides)
## Related Guides
- [Adafruit Feather M4 Express](https://learn.adafruit.com/adafruit-feather-m4-express-atsamd51.md)
- [Adafruit AirLift FeatherWing - ESP32 WiFi Co-Processor](https://learn.adafruit.com/adafruit-airlift-featherwing-esp32-wifi-co-processor-featherwing.md)
- [Party Parrot Zoetrope](https://learn.adafruit.com/party-parrot-zoetrope.md)
- [Adafruit Hallowing M0](https://learn.adafruit.com/adafruit-hallowing.md)
- [CircuitScheme - Lisp on CircuitPython](https://learn.adafruit.com/scheme-in-circuitpython.md)
- [CircuitPython displayio Setup for TFT FeatherWings](https://learn.adafruit.com/using-circuitpython-displayio-with-a-tft-featherwing.md)
- [MakeCode Arcade with SAMD51 M4](https://learn.adafruit.com/makecode-arcade-with-samd51-m4.md)
- [Butterfly Bench with Edge Lit Acrylic](https://learn.adafruit.com/butterfly-bench-with-edge-lit-acrylic.md)
- [Networking in CircuitPython](https://learn.adafruit.com/networking-in-circuitpython.md)
- [Super Nintendo USB Controller](https://learn.adafruit.com/super-nintendo-usb-controller.md)
- [3D Printed Dragon Lamp](https://learn.adafruit.com/dragon-lamp.md)
- [Reindeer Mask with Animated Eyes](https://learn.adafruit.com/reindeer-mask-with-animated-eyes.md)
- [Holiday Tree with Feather RP2040 Scorpio](https://learn.adafruit.com/holiday-tree-with-scorpio.md)
- [LED Matrix Scoreboard](https://learn.adafruit.com/led-matrix-scoreboard.md)
- [Rezz-Inspired NeoPixel Glasses](https://learn.adafruit.com/rezz-inspired-neopixel-glasses.md)
- [CircuitPython Libraries on Linux and the 96Boards DragonBoard 410c](https://learn.adafruit.com/circuitpython-libraries-on-linux-and-the-96boards-dragonboard-410c.md)
- [Halo Energy Sword RP2040](https://learn.adafruit.com/halo-energy-sword-rp2040.md)