Open Weather Maps API Key
We'll be using OpenWeatherMaps.org to retrieve the weather info 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 for a free account. Once registered, you'll get an email containing your API key, also known as the "openweather 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" ADAFRUIT_AIO_USERNAME="my_username" ADAFRUIT_AIO_KEY="my_key" openweather_token="xxxxxxxxxxxxxxxxxxxxxxxx"
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 using a text editor on your computer like this:
CIRCUITPY_WIFI_SSID = "your_wifi_ssid" CIRCUITPY_WIFI_PASSWORD = "your_wifi_password" ADAFRUIT_AIO_USERNAME="my_username" ADAFRUIT_AIO_KEY="my_key" openweather_token="xxxxxxxxxxxxxxxxxxxxxxxx"
CircuitPython Code
In the embedded code element below, click on the Download Project Bundle bundle, and save the .zip archive file to your computer.
Then, uncompress the .zip file, it will unpack to a folder named PyPortal_OpenWeather.
Copy the contents of the PyPortal_OpenWeather 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 queries the Open Weather Maps site API to find out the current
weather for your location... and display it on a screen!
if you can find something that spits out JSON data, we can display it
"""
from os import getenv
import sys
import time
import board
from adafruit_pyportal import PyPortal
cwd = ("/"+__file__).rsplit('/', 1)[0] # the current working directory (where this file is)
sys.path.append(cwd)
import openweather_graphics # pylint: disable=wrong-import-position
# Get WiFi details, ensure these are setup in settings.toml
ssid = getenv("CIRCUITPY_WIFI_SSID")
password = getenv("CIRCUITPY_WIFI_PASSWORD")
if None in [ssid, password]:
raise RuntimeError(
"WiFi settings are kept in settings.toml, "
"please add them there. The settings file must contain "
"'CIRCUITPY_WIFI_SSID', 'CIRCUITPY_WIFI_PASSWORD', "
"at a minimum."
)
# Use cityname, country code where countrycode is ISO3166 format.
# E.g. "New York, US" or "London, GB"
LOCATION = "Manhattan, US"
# Set up where we'll be fetching data from
DATA_SOURCE = "http://api.openweathermap.org/data/2.5/weather?q="+LOCATION
DATA_SOURCE += "&appid=" + getenv('openweather_token')
# You'll need to get a token from openweather.org, looks like 'b6907d289e10d714a6e88b30761fae22'
DATA_LOCATION = []
# 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)
gfx = openweather_graphics.OpenWeather_Graphics(pyportal.splash, am_pm=True, celsius=False)
localtile_refresh = None
weather_refresh = None
while True:
# only query the online time once per hour (and on first run)
if (not localtile_refresh) or (time.monotonic() - localtile_refresh) > 3600:
try:
print("Getting time from internet!")
pyportal.get_local_time()
localtile_refresh = time.monotonic()
except RuntimeError as e:
print("Some error occured, retrying! -", e)
continue
# only query the weather every 10 minutes (and on first run)
if (not weather_refresh) or (time.monotonic() - weather_refresh) > 600:
try:
value = pyportal.fetch()
print("Response is", value)
gfx.display_weather(value)
weather_refresh = time.monotonic()
except RuntimeError as e:
print("Some error occured, retrying! -", e)
continue
gfx.update_time()
time.sleep(30) # wait 30 seconds before updating anything again
How It Works
The PyPortal Weather Station has a few steps it takes to provide you with the information you desire! It has a boot-up screen, weather icons, and multiple fonts for displaying the info.
Background
First, it displays a bitmap graphic as the screen's startup background until it connects to the Open Weather Maps server to get the weather info. This is a 320 x 240 pixel RGB 16-bit raster graphic in .bmp format.
Time
Next, the program connects through the WiFi to get the local time via the adafruit.io server, which will be displayed in the upper right corner of the display.
Location
In the code.py file (which you will have renamed from openweather.py) you can change the location for which you want to display the weather in this line:
# Use cityname, country code where countrycode is ISO3166 format. # E.g. "New York, US" or "London, GB" LOCATION = "Manhattan, US"
API Query and JSON
Using this information, the code can then send a query to Open Weather Maps's API that looks something like this:
http://api.openweathermap.org/data/2.5/weather?q=Los Angeles, US&appid=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
(where all of those 'x's are your token).
When this query is complete, it returns a JSON file that looks like this:
{
"coord": {
"lon": -118.24,
"lat": 34.05
},
"weather": [
{
"id": 501,
"main": "Rain",
"description": "moderate rain",
"icon": "10d"
}
],
"base": "stations",
"main": {
"temp": 287.42,
"pressure": 1016,
"humidity": 50,
"temp_min": 285.15,
"temp_max": 289.15
},
"visibility": 16093,
"wind": {
"speed": 3.6,
"deg": 300
},
"rain": {
"1h": 1.52
},
"clouds": {
"all": 75
},
"dt": 1552073935,
"sys": {
"type": 1,
"id": 3514,
"message": 0.0087,
"country": "US",
"sunrise": 1552054308,
"sunset": 1552096542
},
"id": 5368361,
"name": "Los Angeles",
"cod": 200
}
Here is the same file beautified with the Firefox browswer's built in tools (You can also use online code "beautifiers" such as https://codebeautify.org/jsonviewer or http://jsonviewer.stack.hu) :
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 main, description, icon , and temp, and their respective values. So, here are some key : value pairs we care about for the weather station:
"main" : "Rain""description" : "moderate rain""icon" : "10d""temp" : "287.42"
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 'main' weather condition and the 'main' section containing temperature and other data. To avoid name clashing we rely on JSON traversal.
In the openweather_graphics.py file, you'll see how this is done. For example, the main key is found in this hierarchy of the JSON file: ['weather'], [0], ['main']
This means there is a key at the top level of the JSON file called 'weather', which has a sub-tree indexed [0], and then below that is the 'main' key.
This process is used to cast the values of the temperature, weather, description, and which icon to display from the directory of bitmap icons.
These are the icons represented:
Font
The data is displayed as text created with bitmapped fonts to overlay on top of the background. The fonts used here are bitmap fonts made from the Arial typeface. You can learn more about converting type in this guide.
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 pairs we need -
default_bgdefault background color
Fetch
With the PyPortal set up, we can then use pyportal.fetch() to do the query and parsing of the weather data and then display it on screen.
All of the heavy lifting of parsing that data and displaying it as text or bitmaps is done in the openweather_graphics.py code.
Graphics
Let's have a look at how the openweather_graphics.py code places the elements on screen. Below, we can see the icon and text that are displayed. The items in quotes are the key names from the JSON file, and their values are what we see displayed using the CircuitPython label library.
# SPDX-FileCopyrightText: 2019 Limor Fried for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import time
import json
import displayio
from adafruit_display_text.label import Label
from adafruit_bitmap_font import bitmap_font
cwd = ("/"+__file__).rsplit('/', 1)[0] # the current working directory (where this file is)
small_font = cwd+"/fonts/Arial-12.bdf"
medium_font = cwd+"/fonts/Arial-16.bdf"
large_font = cwd+"/fonts/Arial-Bold-24.bdf"
class OpenWeather_Graphics(displayio.Group):
def __init__(self, root_group, *, am_pm=True, celsius=True):
super().__init__()
self.am_pm = am_pm
self.celsius = celsius
root_group.append(self)
self._icon_group = displayio.Group()
self.append(self._icon_group)
self._text_group = displayio.Group()
self.append(self._text_group)
self._icon_sprite = None
self._icon_file = None
self.set_icon(cwd+"/weather_background.bmp")
self.small_font = bitmap_font.load_font(small_font)
self.medium_font = bitmap_font.load_font(medium_font)
self.large_font = bitmap_font.load_font(large_font)
glyphs = b'0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-,.: '
self.small_font.load_glyphs(glyphs)
self.medium_font.load_glyphs(glyphs)
self.large_font.load_glyphs(glyphs)
self.large_font.load_glyphs(('°',)) # a non-ascii character we need for sure
self.city_text = None
self.time_text = Label(self.medium_font)
self.time_text.x = 200
self.time_text.y = 12
self.time_text.color = 0xFFFFFF
self._text_group.append(self.time_text)
self.temp_text = Label(self.large_font)
self.temp_text.x = 200
self.temp_text.y = 195
self.temp_text.color = 0xFFFFFF
self._text_group.append(self.temp_text)
self.main_text = Label(self.large_font)
self.main_text.x = 10
self.main_text.y = 195
self.main_text.color = 0xFFFFFF
self._text_group.append(self.main_text)
self.description_text = Label(self.small_font)
self.description_text.x = 10
self.description_text.y = 225
self.description_text.color = 0xFFFFFF
self._text_group.append(self.description_text)
def display_weather(self, weather):
weather = json.loads(weather)
# set the icon/background
weather_icon = weather['weather'][0]['icon']
self.set_icon(cwd+"/icons/"+weather_icon+".bmp")
city_name = weather['name'] + ", " + weather['sys']['country']
print(city_name)
if not self.city_text:
self.city_text = Label(self.medium_font, text=city_name)
self.city_text.x = 10
self.city_text.y = 12
self.city_text.color = 0xFFFFFF
self._text_group.append(self.city_text)
self.update_time()
main_text = weather['weather'][0]['main']
print(main_text)
self.main_text.text = main_text
temperature = weather['main']['temp'] - 273.15 # its...in kelvin
print(temperature)
if self.celsius:
self.temp_text.text = "%d °C" % temperature
else:
self.temp_text.text = "%d °F" % ((temperature * 9 / 5) + 32)
description = weather['weather'][0]['description']
description = description[0].upper() + description[1:]
print(description)
self.description_text.text = description
# "thunderstorm with heavy drizzle"
def update_time(self):
"""Fetch the time.localtime(), parse it out and update the display text"""
now = time.localtime()
hour = now[3]
minute = now[4]
format_str = "%d:%02d"
if self.am_pm:
if hour >= 12:
hour -= 12
format_str = format_str+" PM"
else:
format_str = format_str+" AM"
if hour == 0:
hour = 12
time_str = format_str % (hour, minute)
print(time_str)
self.time_text.text = time_str
def set_icon(self, filename):
"""The background image to a bitmap file.
:param filename: The filename of the chosen icon
"""
print("Set icon to ", filename)
if self._icon_group:
self._icon_group.pop()
if not filename:
return # we're done, no icon desired
# CircuitPython 6 & 7 compatible
if self._icon_file:
self._icon_file.close()
self._icon_file = open(filename, "rb")
icon = displayio.OnDiskBitmap(self._icon_file)
self._icon_sprite = displayio.TileGrid(
icon, pixel_shader=getattr(icon, 'pixel_shader', displayio.ColorConverter()))
# # CircuitPython 7+ compatible
# icon = displayio.OnDiskBitmap(filename)
# self._icon_sprite = displayio.TileGrid(icon, pixel_shader=background.pixel_shader)
self._icon_group.append(self._icon_sprite)
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.
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 April 14, 2025
Text editor powered by tinymce.
