AirNow API Key
We'll be using the US government's site airnow.gov to retrieve the air quality index through its API. In order to do so, you'll need to register for an account and get your API key.
Go to this link and register. Once registered, you'll get an email containing your API key, also known as the "airnow token".
Copy and paste this key into your settings.toml file that is on the root level of your CIRCUITPY drive, so it looks something like this:
CIRCUITPY_WIFI_SSID = "your_wifi_ssid" CIRCUITPY_WIFI_PASSWORD = "your_wifi_password" AIRNOW_TOKEN = "XXX0XXXX-0000-0000-0000-XXXXXXXX0000"
Adafruit IO Time Server
In order to get the precise time, our project will query the Adafruit IO Internet of Things service for the time. Adafruit IO is absolutely free to use, but you'll need to log in with your Adafruit account to use it. If you don't already have an Adafruit login, create one here.
If you haven't used Adafruit IO before, check out this guide for more info.
Once you have logged into your account, there are two pieces of information you'll need to place in your settings.toml file: Adafruit IO username, and Adafruit IO key. Head to io.adafruit.com and simply click the View AIO Key link on the left hand side of the Adafruit IO page to get this information.
Then, add them to the settings.toml file like this:
CIRCUITPY_WIFI_SSID = "your_wifi_ssid" CIRCUITPY_WIFI_PASSWORD = "your_wifi_password" AIRNOW_TOKEN = "XXX0XXXX-0000-0000-0000-XXXXXXXX0000" AIO_USERNAME = "your_aio_username" AIO_KEY = "your_aio_key"
CircuitPython Code
In the embedded code element below, click on the Download Project Bundle button, and save the .zip archive file to your computer.
Then, uncompress the .zip file, it will unpack to a folder named PyPortal_AirQuality.
Copy the contents of the PyPortal_AirQuality directory to your PyPortal CIRCUITPY drive.
This is what the final contents of the CIRCUITPY drive will look like:
# SPDX-FileCopyrightText: 2019 Limor Fried for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
This example will access the twitter follow button API, grab a number like
the number of followers... and display it on a screen!
if you can find something that spits out JSON data, we can display it
"""
import os
import time
import board
from adafruit_pyportal import PyPortal
# Change this to your zip code, not all locations have AQI data. Check
# https://airnow.gov/ to see if there's data available!
LOCATION = "90210"
# Set up where we'll be fetching data from
DATA_SOURCE = "http://www.airnowapi.org/aq/forecast/zipCode/?format=application/json"
# You'll need to get a token from airnow.gov, looks like '4d36e978-e325-11cec1-08002be10318'
DATA_SOURCE += "&zipCode="+LOCATION+"&API_KEY="+os.getenv("AIRNOW_TOKEN")
DATA_LOCATION = [1, "AQI"]
# the current working directory (where this file is)
cwd = ("/"+__file__).rsplit('/', 1)[0]
# Initialize the pyportal object and let us know what data to fetch and where
# to display it
pyportal = PyPortal(url=DATA_SOURCE,
json_path=DATA_LOCATION,
status_neopixel=board.NEOPIXEL,
default_bg=0x000000,
text_font=cwd+"/fonts/Helvetica-Bold-100.bdf",
text_position=(90, 100),
text_color=0x000000,
caption_text="Air Quality Index for "+LOCATION,
caption_font=cwd+"/fonts/HelveticaNeue-24.bdf",
caption_position=(15, 220),
caption_color=0x000000,)
while True:
try:
value = pyportal.fetch()
print("Response is", value)
if 0 <= value <= 50:
pyportal.set_background(0x66bb6a) # good
if 51 <= value <= 100:
pyportal.set_background(0xffeb3b) # moderate
if 101 <= value <= 150:
pyportal.set_background(0xf39c12) # sensitive
if 151 <= value <= 200:
pyportal.set_background(0xff5722) # unhealthy
if 201 <= value <= 300:
pyportal.set_background(0x8e24aa) # very unhealthy
if 301 <= value <= 500:
pyportal.set_background(0xb71c1c ) # hazardous
except RuntimeError as e:
print("Some error occured, retrying! -", e)
time.sleep(10*60) # wait 10 minutes before getting again
How It Works
The PyPortal Air Quality Display has a few steps it takes to provide you with the information you desire!
API Query and JSON
Then, it will send a request to the AirNow URL using your LOCATION United States Zip code specified in the code, as well as your AirNow token from the secrets.py file.
The query looks something like this:
http://www.airnowapi.org/aq/forecast/zipCode/?format=application/json&zipCode=90210&API_KEY=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
(where all of those 'x's are your token).
When this query is complete, it returns a JSON file that looks like this:
[
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-10 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "O3",
"AQI": 32,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-10 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "PM2.5",
"AQI": 33,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-10 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "PM10",
"AQI": 7,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-10 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "NO2",
"AQI": 22,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-10 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "CO",
"AQI": 5,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-11 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "O3",
"AQI": 29,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-11 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "PM2.5",
"AQI": 33,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-11 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "PM10",
"AQI": 9,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-11 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "NO2",
"AQI": 18,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
},
{
"DateIssue": "2019-03-09 ",
"DateForecast": "2019-03-11 ",
"ReportingArea": "NW Coastal LA",
"StateCode": "CA",
"Latitude": 34.0505,
"Longitude": -118.4566,
"ParameterName": "CO",
"AQI": 6,
"Category": {
"Number": 1,
"Name": "Good"
},
"ActionDay": false
}
]
You can use online code "beautifiers" such as https://codebeautify.org/jsonviewer or http://jsonviewer.stack.hu to get a nice hierarchical view of the data in the JSON file:
JSON Traversal
The JSON file is formatted in a way that makes it easy to traverse the hierarchy and parse the data. In it, you'll see keys, such as DateIssue, ReportingArea, ParameterName, and AQI, and their respective values. The key : value pair we care about for the Air Quality Display is the Air Quality Index of particle pollution (PM2.5), or AQI. This is the pair:
-
"AQI" : "33"
In order to fetch this data from the file, we need to be able to describe their locations in the file hierarchically. This is helpful, for example, in differentiating between the 'AQI' in the 'PM2.5' section vs. the 'AQI' in the 'NO2' section. To avoid name clashing we rely on JSON traversal.
In the airquality.py file, you'll see how this is done. For example, the key we want for PM2.5 is found in this hierarchy of the JSON file: [1, "AQI"]
This means there is a sub-tree to the top level of the file indexed [1], which is the second section, as the first is indexed zero. Then, below that level is the 'AQI' key we want.
The value of that key in this case is '33' which is considered to be in the "good" range of particle pollution.
Background
For the background, it displays a solid color based on the current air quality index value. 0-50 is considered good, for example, and has a green background. Here is the full set:
- 0-50, "good", green
- 51-100, "moderate", yellow
- 101-150, "sensitive", orange
- 151-200 "unhealthy", red
- 210-300, "very unhealthy", purple
- 301-500, "hazardous", maroon
Font
The AQI value is displayed as text created with a bitmapped font to overlay on top of the background. The fonts used here are bitmap fonts made from the Helvetica typeface. You can learn more about converting type in this guide.
At the bottom of the screen, there is a caption text that types out "Air Quality Index for " followed by the United States Zip code you entered.
PyPortal Constructor
When we set up the pyportal constructor, we are providing it with these things:
-
urlto query -
json_pathto traverse and find the key:value pair we need -
default_bgdefault background color - details of text and caption fonts, positions, and colors
Fetch
With the PyPortal set up, we can then use pyportal.fetch() to do the query and parsing of the AirNow data and then display it on screen.
Text Position
Depending on the design of your background bitmap and the length of the text you're displaying, you may want to reposition the text and caption. You can do this with the text_position and caption_position options.
The PyPortal's display is 320 pixels wide and 240 pixels high. In order to refer to those positions on the screen, we use an x/y coordinate system, where x is horizontal and y is vertical.
The origin of this coordinate system is the upper left corner. This means that a pixel placed at the upper left corner would be (0,0) and the lower right corner would be (320, 240).
So, if you wanted to move the subscriber count text to the right and up closer to the top, your code may look like this for that part of the pyportal constructor: text_position=(250, 10)
Text Color
Another way to customize your display is to adjust the color of the text. The line text_color=0xFFFFFF in the constructor shows how. You will need to use the hexadecimal value for any color you want to display.
You can use something like https://htmlcolorcodes.com/ to pick your color and then copy the hex value, in this example it would be 0x0ED9EE
Now, we'll look at mounting the PyPortal into a case for display!
Page last edited January 21, 2025
Text editor powered by tinymce.
