Open Weather Maps API Key

We'll be using 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 file that is on the root level of your CIRCUITPY drive, so it looks something like this:

    secrets = {
    'ssid' : 'your_wifi_ssid',
    'password' : 'your_wifi_password',
    '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 file: Adafruit IO username, and Adafruit IO key. Head to 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 file like this:

    secrets = {
    'ssid' : 'your_wifi_ssid',
    'password' : 'your_wifi_password',
    'openweather_token' : 'xxxxxxxxxxxxxxxxxxxxxxxx',
    'aio_username' : '_your_aio_username_',
    'aio_key' : '_your_big_huge_super_long_aio_key_'

CircuitPython Code

In the embedded code element below, click on the Download: Project Zip link, 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's 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
import sys
import time
import board
from adafruit_pyportal import PyPortal
cwd = ("/"+__file__).rsplit('/', 1)[0] # the current working directory (where this file is)
import openweather_graphics  # pylint: disable=wrong-import-position

# Get wifi details and more from a file
    from secrets import secrets
except ImportError:
    print("WiFi secrets are kept in, please add them there!")

# 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 += "&appid="+secrets['openweather_token']
# You'll need to get a token from, looks like 'b6907d289e10d714a6e88b30761fae22'

# Initialize the pyportal object and let us know what data to fetch and where
# to display it
pyportal = PyPortal(url=DATA_SOURCE,

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:
            print("Getting time from internet!")
            localtile_refresh = time.monotonic()
        except RuntimeError as e:
            print("Some error occured, retrying! -", e)

    # only query the weather every 10 minutes (and on first run)
    if (not weather_refresh) or (time.monotonic() - weather_refresh) > 600:
            value = pyportal.fetch()
            print("Response is", value)
            weather_refresh = time.monotonic()
        except RuntimeError as e:
            print("Some error occured, retrying! -", e)

    time.sleep(30)  # wait 30 seconds before updating anything again
If you run into any errors, such as "ImportError: no module named `adafruit_display_text.label`" be sure to update your libraries to the latest release bundle!

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.


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.


Next, the program connects through the WiFi to get the local time via the server, which will be displayed in the upper right corner of the display.


In the file (which you will have renamed from 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: 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 or :

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 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:


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:

  • url to query
  • json_path to traverse and find the key:value pairs we need
  • default_bg default background color


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 code.


Let's have a look at how the 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):
        self.am_pm = am_pm
        self.celsius = celsius

        self._icon_group = displayio.Group()
        self._text_group = displayio.Group()

        self._icon_sprite = None
        self._icon_file = None

        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.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.temp_text = Label(self.large_font)
        self.temp_text.x = 200
        self.temp_text.y = 195
        self.temp_text.color = 0xFFFFFF

        self.main_text = Label(self.large_font)
        self.main_text.x = 10
        self.main_text.y = 195
        self.main_text.color = 0xFFFFFF

        self.description_text = Label(self.small_font)
        self.description_text.x = 10
        self.description_text.y = 225
        self.description_text.color = 0xFFFFFF

    def display_weather(self, weather):
        weather = json.loads(weather)

        # set the icon/background
        weather_icon = weather['weather'][0]['icon']

        city_name =  weather['name'] + ", " + weather['sys']['country']
        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


        main_text = weather['weather'][0]['main']
        self.main_text.text = main_text

        temperature = weather['main']['temp'] - 273.15 # kelvin
        if self.celsius:
            self.temp_text.text = "%d °C" % temperature
            self.temp_text.text = "%d °F" % ((temperature * 9 / 5) + 32)

        description = weather['weather'][0]['description']
        description = description[0].upper() + description[1:]
        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"
                format_str = format_str+" AM"
            if hour == 0:
                hour = 12
        time_str = format_str % (hour, minute)
        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:

        if not filename:
            return  # we're done, no icon desired

        # CircuitPython 6 & 7 compatible
        if self._icon_file:
        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)


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 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!

This guide was first published on Mar 13, 2019. It was last updated on Mar 13, 2019.

This page (Code PyPortal with CircuitPython) was last updated on Sep 30, 2023.

Text editor powered by tinymce.