Keep an eye on your schedule with this MagTag Google Calendar Event Viewer. This CircuitPython project uses the Google Calendar API to retrieve a list of the latest events from your Google Calendar and displays them on the MagTag's e-Ink screen.

Between fetching new events on your calendar, the MagTag goes into a deep sleep mode to conserve battery life. 

Parts

The starter kit includes everything you need to use the Adafruit MagTag.

The Adafruit MagTag combines the new ESP32-S2 wireless module and a 2.9" grayscale E-Ink display to make a low-power IoT display that can show data on its screen...

Or, you can purchase parts for this project individually.

The Adafruit MagTag combines the new ESP32-S2 wireless module and a 2.9" grayscale E-Ink display to make a low-power IoT display that can show data on its screen even when power...
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...
Got a glorious RGB Matrix project you want to mount and display in your workspace or home? If you have one of the matrix panels listed below, you'll need a pack of these...
Here is the perfect kit with two faceplate options for your MagTag, including a vivid Red Arrow plate and a dreamy white Cloud plate. And of course, the mounting hardware is included,...

You'll also want to pick up a USB Type C cable to connect the MagTag to your computer.

As technology changes and adapts, so does Adafruit. This  USB Type A to Type C cable will help you with the transition to USB C, even if you're still...
As technology changes and adapts, so does Adafruit. This  USB Type A to Type C cable will help you with the transition to USB C, even if you're still...

CircuitPython is a derivative of MicroPython designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the CIRCUITPY drive to iterate.

Set Up CircuitPython

Follow the steps to get CircuitPython installed on your MagTag.

Click the link above and download the latest .BIN and .UF2 file

(depending on how you program the ESP32S2 board you may need one or the other, might as well get both)

Download and save it to your desktop (or wherever is handy).

Plug your MagTag into your computer using a known-good USB cable.

A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.

Option 1 - Load with UF2 Bootloader

This is by far the easiest way to load CircuitPython. However it requires your board has the UF2 bootloader installed. Some early boards do not (we hadn't written UF2 yet!) - in which case you can load using the built in ROM bootloader.

Still, try this first!

Try Launching UF2 Bootloader

Loading CircuitPython by drag-n-drop UF2 bootloader is the easier way and we recommend it. If you have a MagTag where the front of the board is black, your MagTag came with UF2 already on it.

Launch UF2 by double-clicking the Reset button (the one next to the USB C port). You may have to try a few times to get the timing right.

If the UF2 bootloader is installed, you will see a new disk drive appear called MAGTAGBOOT

Copy the UF2 file you downloaded at the first step of this tutorial onto the MAGTAGBOOT drive

If you're using Windows and you get an error at the end of the file copy that says Error from the file copy, Error 0x800701B1: A device which does not exist was specified. You can ignore this error, the bootloader sometimes disconnects without telling Windows, the install completed just fine and you can continue. If its really annoying, you can also upgrade the bootloader (the latest version of the UF2 bootloader fixes this warning)

Your board should auto-reset into CircuitPython, or you may need to press reset. A CIRCUITPY drive will appear. You're done! Go to the next pages.

Option 2 - Use esptool to load BIN file

If you have an original MagTag with while soldermask on the front, we didn't have UF2 written for the ESP32S2 yet so it will not come with the UF2 bootloader.

You can upload with esptool to the ROM (hardware) bootloader instead!

Follow the initial steps found in the Run esptool and check connection section of the ROM Bootloader page to verify your environment is set up, your board is successfully connected, and which port it's using.

In the final command to write a binary file to the board, replace the port with your port, and replace "firmware.bin" with the the file you downloaded above.

The output should look something like the output in the image.

Press reset to exit the bootloader.

Your CIRCUITPY drive should appear!

You're all set! Go to the next pages.

Option 3 - Use Chrome Browser To Upload BIN file

If for some reason you cannot get esptool to run, you can always try using the Chrome-browser version of esptool we have written. This is handy if you don't have Python on your computer, or something is really weird with your setup that makes esptool not run (which happens sometimes and isn't worth debugging!) You can follow along on the Web Serial ESPTool page and either load the UF2 bootloader and then come back to Option 1 on this page, or you can download the CircuitPython BIN file directly using the tool in the same manner as the bootloader.

To use the internet-connectivity built into your ESP32-S2 with CircuitPython, you must first install a number of libraries. This page covers that process.

Adafruit CircuitPython Library Bundle

Download the Adafruit CircuitPython Bundle. You can find the latest release here:

Download the adafruit-circuitpython-bundle-version-mpy-*.zip bundle zip file, and unzip a folder of the same name. Inside you'll find a lib folder. The entire collection of libraries is too large to fit on the CIRCUITPY drive. Instead, add each library as you need it, this will reduce the space usage but you'll need to put in a little more effort.

At a minimum we recommend the following libraries, in fact we more than recommend. They're basically required. So grab them and install them into CIRCUITPY/lib now!

  • adafruit_requests.mpy - A requests-like library for HTTP commands.
  • neopixel.mpy - Helper library to use NeoPixel LEDs, often built into the boards so they're great for quick feedback

Once you have added those files, please continue to the next page to set up and test Internet connectivity

Once you have CircuitPython installed and the minimum libraries installed we can get your board connected to the Internet. 

To get connected, you will need to start by creating a secrets.py file.

Secrets File

We expect people to share tons of projects as they build CircuitPython WiFi widgets. What we want to avoid is people accidentally sharing their passwords or secret tokens and API keys. So, we designed all our examples to use a secrets.py file, that is in your CIRCUITPY drive, to hold secret/private/custom data. That way you can share your main project without worrying about accidentally sharing private stuff.

Your secrets.py file should look like this:

# 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

secrets = {
    'ssid' : 'home_wifi_network',
    'password' : 'wifi_password',
    'aio_username' : 'my_adafruit_io_username',
    'aio_key' : 'my_adafruit_io_key',
    'timezone' : "America/New_York", # http://worldtimeapi.org/timezones
    }

Copy and paste that text/code into a file called secrets.py and save it to your CIRCUITPY folder like so:

Inside is a python dictionary named secrets with a line for each entry. Each entry has an entry name (say 'ssid') and then a colon to separate it from the entry key 'home ssid' and finally a comma ,

At a minimum you'll need to adjust the ssid and password for your local WiFi setup so do that now!

As you make projects you may need more tokens and keys, just add them one line at a time. See for example other tokens such as one for accessing github or the hackaday API. Other non-secret data like your timezone can also go here, just cause its called secrets doesn't mean you can't have general customization data in there!

For the correct time zone string, look at http://worldtimeapi.org/timezones and remember that if your city is not listed, look for a city in the same time zone, for example Boston, New York, Philadelphia, Washington DC, and Miami are all on the same time as New York.

Of course, don't share your secrets.py - keep that out of GitHub, Discord or other project-sharing sites.

Don't share your secrets.py file, it has your passwords and API keys in it!

Connect to WiFi

OK now you have your secrets setup - you can connect to the Internet using the Requests module.

First make sure you are running the latest version of Adafruit CircuitPython 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. Our introduction guide has a great page on how to install the library bundle.

  • adafruit_requests
  • neopixel

Before continuing make sure your board's CIRCUITPY/lib folder or root filesystem has the above files copied over.

Once that's done, load up the following example using Mu or your favorite editor:

import ipaddress
import ssl
import wifi
import socketpool
import adafruit_requests

# URLs to fetch from
TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html"
JSON_QUOTES_URL = "https://www.adafruit.com/api/quotes.php"
JSON_STARS_URL = "https://api.github.com/repos/adafruit/circuitpython"

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

print("ESP32-S2 WebClient Test")

print("My MAC addr:", [hex(i) for i in wifi.radio.mac_address])

print("Available WiFi networks:")
for network in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(network.ssid, "utf-8"),
            network.rssi, network.channel))
wifi.radio.stop_scanning_networks()

print("Connecting to %s"%secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print("Connected to %s!"%secrets["ssid"])
print("My IP address is", wifi.radio.ipv4_address)

ipv4 = ipaddress.ip_address("8.8.4.4")
print("Ping google.com: %f ms" % (wifi.radio.ping(ipv4)*1000))

pool = socketpool.SocketPool(wifi.radio)
requests = adafruit_requests.Session(pool, ssl.create_default_context())

print("Fetching text from", TEXT_URL)
response = requests.get(TEXT_URL)
print("-" * 40)
print(response.text)
print("-" * 40)

print("Fetching json from", JSON_QUOTES_URL)
response = requests.get(JSON_QUOTES_URL)
print("-" * 40)
print(response.json())
print("-" * 40)

print()

print("Fetching and parsing json from", JSON_STARS_URL)
response = requests.get(JSON_STARS_URL)
print("-" * 40)
print("CircuitPython GitHub Stars", response.json()["stargazers_count"])
print("-" * 40)

print("done")

And save it to your board. Make sure the file is named code.py.

Open up your REPL, you should see something like the following:

In order, the example code...

Checks the ESP32-S2's MAC address.

print("My MAC addr:", [hex(i) for i in wifi.radio.mac_address])

Performs a scan of all access points and prints out the access point's name (SSID), signal strength (RSSI), and channel.

print("Avaliable WiFi networks:")
for network in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(network.ssid, "utf-8"),
            network.rssi, network.channel))
wifi.radio.stop_scanning_networks()

Connects to the access point you defined in the secrets.py file, prints out its local IP address, and attempts to ping google.com to check its network connectivity. 

print("Connecting to %s"%secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print(print("Connected to %s!"%secrets["ssid"]))
print("My IP address is", wifi.radio.ipv4_address)

ipv4 = ipaddress.ip_address("8.8.4.4")
print("Ping google.com: %f ms" % wifi.radio.ping(ipv4))

The code creates a socketpool using the wifi radio's available sockets. This is performed so we don't need to re-use sockets. Then, it initializes a a new instance of the requests interface - which makes getting data from the internet really really easy.

pool = socketpool.SocketPool(wifi.radio)
requests = adafruit_requests.Session(pool, ssl.create_default_context())

To read in plain-text from a web URL, call requests.get - you may pass in either a http, or a https url for SSL connectivity. 

print("Fetching text from", TEXT_URL)
response = requests.get(TEXT_URL)
print("-" * 40)
print(response.text)
print("-" * 40)

Requests can also display a JSON-formatted response from a web URL using a call to requests.get

print("Fetching json from", JSON_QUOTES_URL)
response = requests.get(JSON_QUOTES_URL)
print("-" * 40)
print(response.json())
print("-" * 40)

Finally, you can fetch and parse a JSON URL using requests.get. This code snippet obtains the stargazers_count field from a call to the GitHub API.

print("Fetching and parsing json from", JSON_STARS_URL)
response = requests.get(JSON_STARS_URL)
print("-" * 40)
print("CircuitPython GitHub Stars", response.json()["stargazers_count"])
print("-" * 40)

OK you now have your ESP32-S2 board set up with a proper secrets.py file and can connect over the Internet. If not, check that your secrets.py file has the right ssid and password and retrace your steps until you get the Internet connectivity working!

A very common need for projects is to know the current date and time. Especially when you want to deep sleep until an event, or you want to change your display based on what day, time, date, etc. it is

Determining the correct local time is really really hard. There are various time zones, Daylight Savings dates, leap seconds, etc. Trying to get NTP time and then back-calculating what the local time is, is extraordinarily hard on a microcontroller just isn't worth the effort and it will get out of sync as laws change anyways.

For that reason, we have the free adafruit.io time service. Free for anyone, with a free adafruit.io account. You do need an account because we have to keep accidentally mis-programmed-board from overwhelming adafruit.io and lock them out temporarily. Again, it's free!

There are other services like WorldTimeAPI, but we don't use those for our guides because they are nice people and we don't want to accidentally overload their site. Also, there's a chance it may eventually go down or also require an account.

Step 1) Make an Adafruit account

It's free! Visit https://accounts.adafruit.com/ to register and make an account if you do not already have one

Step 2) Sign into Adafruit IO

Head over to io.adafruit.com and click Sign In to log into IO using your Adafruit account. It's free and fast to join.

Step 3) Get your Adafruit IO Key

Click on My Key in the top bar

You will get a popup with your Username and Key (In this screenshot, we've covered it with red blocks)

Go to your secrets.py file on your CIRCUITPY drive and add three lines for aio_username, aio_key and timezone so you get something like the following:

# 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

secrets = {
    'ssid' : 'home_wifi_network',
    'password' : 'wifi_password',
    'aio_username' : 'my_adafruit_io_username',
    'aio_key' : 'my_adafruit_io_key',
    'timezone' : "America/New_York", # http://worldtimeapi.org/timezones
    }

The timezone is optional, if you don't have that entry, adafruit.io will guess your timezone based on geographic IP address lookup. You can visit http://worldtimeapi.org/timezones to see all the time zones available (even though we do not use worldtimeapi for time-keeping we do use the same time zone table)

Step 4) Upload Test Python Code

This code is like the Internet Test code from before, but this time it will connect to adafruit.io and get the local time

import ipaddress
import ssl
import wifi
import socketpool
import adafruit_requests
import secrets


TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html"
JSON_QUOTES_URL = "https://www.adafruit.com/api/quotes.php"
JSON_STARS_URL = "https://api.github.com/repos/adafruit/circuitpython"

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

# Get our username, key and desired timezone
aio_username = secrets["aio_username"]
aio_key = secrets["aio_key"]
location = secrets.get("timezone", None)
TIME_URL = "https://io.adafruit.com/api/v2/%s/integrations/time/strftime?x-aio-key=%s" % (aio_username, aio_key)
TIME_URL += "&fmt=%25Y-%25m-%25d+%25H%3A%25M%3A%25S.%25L+%25j+%25u+%25z+%25Z"

print("ESP32-S2 Adafruit IO Time test")

print("My MAC addr:", [hex(i) for i in wifi.radio.mac_address])

print("Available WiFi networks:")
for network in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(network.ssid, "utf-8"),
            network.rssi, network.channel))
wifi.radio.stop_scanning_networks()

print("Connecting to %s"%secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print("Connected to %s!"%secrets["ssid"])
print("My IP address is", wifi.radio.ipv4_address)

ipv4 = ipaddress.ip_address("8.8.4.4")
print("Ping google.com: %f ms" % wifi.radio.ping(ipv4))

pool = socketpool.SocketPool(wifi.radio)
requests = adafruit_requests.Session(pool, ssl.create_default_context())

print("Fetching text from", TIME_URL)
response = requests.get(TIME_URL)
print("-" * 40)
print(response.text)
print("-" * 40)

After running this, you will see something like the below text. We have blocked out the part with the secret username and key data!

Note at the end you will get the date, time, and your timezone! If so, you have correctly configured your secrets.py and can continue to the next steps!

To use all the amazing features of your MagTag with CircuitPython, you must first install a number of libraries. This page covers that process.

Get Latest Adafruit CircuitPython Bundle

Download the Adafruit CircuitPython Library Bundle. You can find the latest release here:

Download the adafruit-circuitpython-bundle-version-mpy-*.zip bundle zip file, and unzip a folder of the same name. Inside you'll find a lib folder. The entire collection of libraries is too large to fit on the CIRCUITPY drive. Therefore, you'll need to copy the necessary libraries to your board individually.

At a minimum, the following libraries are required. Copy the following folders or .mpy files to the lib folder on your CIRCUITPY drive. If the library is a folder, copy the entire folder to the lib folder on your board.

Library folders (copy the whole folder over to lib):

  • adafruit_magtag - This is a helper library designed for using all of the features of the MagTag, including networking, buttons, NeoPixels, etc.
  • adafruit_portalbase - This library is the base library that adafruit_magtag is built on top of.
  • adafruit_bitmap_font - There is fancy font support, and it's easy to make new fonts. This library reads and parses font files.
  • adafruit_display_text - This library displays text on the screen.
  • adafruit_io - This library helps connect the MagTag to our free data logging and viewing service

Library files:

  • adafruit_requests.mpy - This library allows us to perform HTTP requests and get responses back from servers. GET/POST/PUT/PATCH - they're all in here!
  • adafruit_fakerequests.mpy  - This library allows you to create fake HTTP requests by using local files.
  • adafruit_miniqr.mpy  - QR creation library lets us add easy-to-scan 2D barcodes to the E-Ink display
  • neopixel.mpy - This library is used to control the onboard NeoPixels.
  • simpleio.mpy - This library is used for tone generation.

Secrets

Even if you aren't planning to go online with your MagTag, you'll need to have a secrets.py file in the root directory (top level) of your CIRCUITPY drive. If you do not intend to connect to wireless, it does not need to have valid data in it. Here's more info on the secrets.py file.

Obtain Access Tokens

Google provides a Calendar API which lets you access your Google account's calendar events. Let's start by creating an Application and register it with Google's API console.

Navigate to the Google API Credentials page

Click Create Credentials.

From the dropdown, select "OAuth client ID"

Select "TV and Limited Input devices" from the dropdown and give your client a name.

Click "Create".

Copy the Client ID and Client Secret to a text document and save it to your computer's desktop. You'll need these values later.

Before you can use the Google Calendar API to request events on your calendar, you must first authenticate the device with Google's authentication server.

We've handled this authorization "flow" by creating a CircuitPython library for Google's implementation of OAuth2.0 and an application to run on your device.

Secrets File Setup

Open the secrets.py file on your CircuitPython device using Mu or your favorite text editor. If you don't have one, copy the generic one below. You're going to edit this file to enter your Google API credentials.

  • Change aio_username to your Adafruit IO username
  • Change aio_key to your Adafruit IO active key
  • Change timezone to "Etc/UTC"
  • Change google_client_id to the Google client ID you obtained in the previous step
  • Change google_client_secret to the Google client ID you obtained in the previous step

Your secrets.py file should look like this: 

# 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

secrets = {
    'ssid' : 'YOUR_SSID',
    'password' : 'YOUR_SSID_PASS',
    'aio_username': 'YOUR_AIO_USERNAME',
    'aio_key': 'YOUR_AIO_KEY',
    'timezone' : "Etc/UTC", # http://worldtimeapi.org/timezones
    'google_client_id' : 'YOUR_GOOGLE_CLIENT_ID',
    'google_client_secret' : 'YOUR_GOOGLE_CLIENT_SECRET'
    }

Add CircuitPython Code and Project Assets

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

Copy the contents of the MagTag_Google_Calendar directory to your MagTag's CIRCUITPY drive.

If you're having difficulty running this example, it could be because your MagTag CircuitPython firmware or library needs to be upgraded! Please be sure to follow https://learn.adafruit.com/adafruit-magtag/circuitpython to install the latest CircuitPython firmware and then also replace/update ALL the MagTag-specific libraries mentioned here https://learn.adafruit.com/adafruit-magtag/circuitpython-libraries-2
# SPDX-FileCopyrightText: 2021 Brent Rubell, written for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
import ssl
import board
import wifi
import socketpool
import adafruit_requests as requests
from adafruit_oauth2 import OAuth2
from adafruit_display_text.label import Label
from adafruit_bitmap_font import bitmap_font
from adafruit_magtag.magtag import Graphics
from adafruit_display_shapes.rect import Rect

# Add a secrets.py to your filesystem that has a dictionary called secrets with "ssid" and
# "password" keys with your WiFi credentials. DO NOT share that file or commit it into Git or other
# source control.
# pylint: disable=no-name-in-module,wrong-import-order
try:
    from secrets import secrets
except ImportError:
    print("Credentials and tokens are kept in secrets.py, please add them there!")
    raise

print("Connecting to %s" % secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print("Connected to %s!" % secrets["ssid"])

pool = socketpool.SocketPool(wifi.radio)
requests = requests.Session(pool, ssl.create_default_context())

# DisplayIO setup
font_small = bitmap_font.load_font("/fonts/Arial-12.pcf")
font_large = bitmap_font.load_font("/fonts/Arial-14.pcf")

graphics = Graphics(auto_refresh=False)
display = graphics.display

background = Rect(0, 0, 296, 128, fill=0xFFFFFF)
graphics.splash.append(background)

label_overview_text = Label(
    font_large,
    x=0,
    y=10,
    line_spacing=0.75,
    color=0x000000,
    text="Authorize this device with Google:",
)
graphics.splash.append(label_overview_text)

label_verification_url = Label(
    font_small, x=0, y=40, line_spacing=0.75, color=0x000000
)
graphics.splash.append(label_verification_url)

label_user_code = Label(
    font_small, x=0, y=80, color=0x000000, line_spacing=0.75
)
graphics.splash.append(label_user_code)

label_qr_code = Label(
    font_small, x=0, y=100, color=0x000000, text="Or scan the QR code:"
)
graphics.splash.append(label_qr_code)

# Set scope(s) of access required by the API you're using
scopes = ["https://www.googleapis.com/auth/calendar.readonly"]

# Initialize an OAuth2 object
google_auth = OAuth2(
    requests, secrets["google_client_id"], secrets["google_client_secret"], scopes
)

# Request device and user codes
# https://developers.google.com/identity/protocols/oauth2/limited-input-device#step-1:-request-device-and-user-codes
google_auth.request_codes()

# Display user code and verification url
# NOTE: If you are displaying this on a screen, ensure the text label fields are
# long enough to handle the user_code and verification_url.
# Details in link below:
# https://developers.google.com/identity/protocols/oauth2/limited-input-device#displayingthecode
print(
    "1) Navigate to the following URL in a web browser:", google_auth.verification_url
)
print("2) Enter the following code:", google_auth.user_code)
label_verification_url.text = (
    "1. On your computer or mobile device,\ngo to %s" % google_auth.verification_url
)
label_user_code.text = "2. Enter code: %s" % google_auth.user_code

graphics.qrcode(google_auth.verification_url.encode(), qr_size=2, x=240, y=70)
board.DISPLAY.show(graphics.splash)
display.refresh()

# Poll Google's authorization server
print("Waiting for browser authorization...")
if not google_auth.wait_for_authorization():
    raise RuntimeError("Timed out waiting for browser response!")

print("Successfully Authenticated with Google!")
print("Add the following lines to your secrets.py file:")
print("\t'google_access_token' " + ":" + " '%s'," % google_auth.access_token)
print("\t'google_refresh_token' " + ":" + " '%s'" % google_auth.refresh_token)

graphics.splash.pop()
graphics.splash.pop()
graphics.splash.pop()

label_overview_text.text = "Successfully Authenticated!"
label_verification_url.text = (
    "Check the REPL for tokens to add\n\tto your secrets.py file"
)
display.refresh()

Once all the files are copied from your computer to the CircuitPython device, you should have the following files on your CIRCUITPY drive.

 

Note: Make sure you've loaded the adafruit_oauth2 library onto your CIRCUITPY volume.

Authenticator Code Usage

On your CIRCUITPY drive, rename authenticator.py to code.py. Then, open the CircuitPython REPL using Mu or another serial monitor.

Your CircuitPython device should boot into the Google Authenticator code and display a code and URL.

Navigate to the Google Device page and enter the code you see on your device.

Click Next

Select the Google Account you'd like to use with the calendar viewer.

Since Google has not formally verified the application you created in the previous step, you'll be greeted with a warning.

  • Click Advanced
  • Then, Click the Go to {your application name} link

Finally, a dialog will appear displaying the application's requested permissions.

Click Allow.

You'll be presented with a dialog telling you the device has been authenticated.

After 5 seconds, the CircuitPython REPL should display a google_access_token and google_refresh_token.

Copy and paste these lines into the secrets.py file.

Your secrets.py file should look like this:

# 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
 
secrets = {
    'ssid' : 'YOUR_SSID',
    'password' : 'YOUR_SSID_PASS',
    'aio_username': 'YOUR_AIO_USERNAME',
    'aio_key': 'YOUR_AIO_KEY'
    'timezone' : "Etc/UTC", # http://worldtimeapi.org/timezones
    'google_client_id' : 'YOUR_GOOGLE_CLIENT_ID',
    'google_client_secret' : 'YOUR_GOOGLE_CLIENT_SECRET',
    'google_access_token' : 'YOUR_GOOGLE_ACCESS_TOKEN',
    'google_refresh_token' : 'YOUR_GOOGLE_REFRESH_TOKEN'
    }

Now that your device is authorized to make requests to the Google Calendar API, let's use it to fetch calendar events!

Code

In the MagTag_Google_Calendar folder from the previous step, copy code.py to your CIRCUITPY drive. This should overwrite the authenticator code with the calendar event display code.

# SPDX-FileCopyrightText: 2021 Brent Rubell, written for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
import time
import ssl
import board
import rtc
import wifi
import socketpool
import adafruit_requests as requests
from adafruit_oauth2 import OAuth2
from adafruit_display_shapes.line import Line
from adafruit_bitmap_font import bitmap_font
from adafruit_display_text import label
from adafruit_magtag.magtag import MagTag

# Calendar ID
CALENDAR_ID = "YOUR_CALENDAR_ID"

# Maximum amount of events to display
MAX_EVENTS = 3

# Amount of time to wait between refreshing the calendar, in minutes
REFRESH_TIME = 15

# Dict. of month names for pretty-printing the header
MONTHS = {
    1: "Jan",
    2: "Feb",
    3: "Mar",
    4: "Apr",
    5: "May",
    6: "Jun",
    7: "Jul",
    8: "Aug",
    9: "Sep",
    10: "Oct",
    11: "Nov",
    12: "Dec",
}
# Dict. of day names for pretty-printing the header
WEEKDAYS = {
    0: "Monday",
    1: "Tuesday",
    2: "Wednesday",
    3: "Thursday",
    4: "Friday",
    5: "Saturday",
    6: "Sunday",
}

# Add a secrets.py to your filesystem that has a dictionary called secrets with "ssid" and
# "password" keys with your WiFi credentials. DO NOT share that file or commit it into Git or other
# source control.
# pylint: disable=no-name-in-module,wrong-import-order
try:
    from secrets import secrets
except ImportError:
    print("Credentials and tokens are kept in secrets.py, please add them there!")
    raise

print("Connecting to %s" % secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print("Connected to %s!" % secrets["ssid"])

pool = socketpool.SocketPool(wifi.radio)
requests = requests.Session(pool, ssl.create_default_context())

# Initialize an OAuth2 object with GCal API scope
scopes = ["https://www.googleapis.com/auth/calendar.readonly"]
google_auth = OAuth2(
    requests,
    secrets["google_client_id"],
    secrets["google_client_secret"],
    scopes,
    secrets["google_access_token"],
    secrets["google_refresh_token"],
)


def get_current_time(time_max=False):
    """Gets local time from Adafruit IO and converts to RFC3339 timestamp."""
    # Get local time from Adafruit IO
    magtag.get_local_time(secrets["timezone"])
    # Format as RFC339 timestamp
    cur_time = r.datetime
    if time_max:  # maximum time to fetch events is midnight (4:59:59UTC)
        cur_time_max = time.struct_time(
            cur_time[0],
            cur_time[1],
            cur_time[2] + 1,
            4,
            59,
            59,
            cur_time[6],
            cur_time[7],
            cur_time[8],
        )
        cur_time = cur_time_max
    cur_time = "{:04d}-{:02d}-{:02d}T{:02d}:{:02d}:{:02d}{:s}".format(
        cur_time[0],
        cur_time[1],
        cur_time[2],
        cur_time[3],
        cur_time[4],
        cur_time[5],
        "Z",
    )
    return cur_time


def get_calendar_events(calendar_id, max_events, time_min):
    """Returns events on a specified calendar.
    Response is a list of events ordered by their start date/time in ascending order.
    """
    time_max = get_current_time(time_max=True)
    print("Fetching calendar events from {0} to {1}".format(time_min, time_max))

    headers = {
        "Authorization": "Bearer " + google_auth.access_token,
        "Accept": "application/json",
        "Content-Length": "0",
    }
    url = (
        "https://www.googleapis.com/calendar/v3/calendars/{0}"
        "/events?maxResults={1}&timeMin={2}&timeMax={3}&orderBy=startTime"
        "&singleEvents=true".format(calendar_id, max_events, time_min, time_max)
    )
    resp = requests.get(url, headers=headers)
    resp_json = resp.json()
    if "error" in resp_json:
        raise RuntimeError("Error:", resp_json)
    resp.close()
    # parse the 'items' array so we can iterate over it easier
    items = []
    resp_items = resp_json["items"]
    if not resp_items:
        print("No events scheduled for today!")
    for event in range(0, len(resp_items)):
        items.append(resp_items[event])
    return items


def format_datetime(datetime, pretty_date=False):
    """Formats ISO-formatted datetime returned by Google Calendar API into
    a struct_time.
    :param str datetime: Datetime string returned by Google Calendar API
    :return: struct_time

    """
    times = datetime.split("T")
    the_date = times[0]
    the_time = times[1]
    year, month, mday = [int(x) for x in the_date.split("-")]
    the_time = the_time.split("-")[0]
    if "Z" in the_time:
        the_time = the_time.split("Z")[0]
    hours, minutes, _ = [int(x) for x in the_time.split(":")]
    am_pm = "am"
    if hours >= 12:
        am_pm = "pm"
        # convert to 12hr time
        if not hours == 12:
            hours -= 12
    # via https://github.com/micropython/micropython/issues/3087
    formatted_time = "{:01d}:{:02d}{:s}".format(hours, minutes, am_pm)
    if pretty_date:  # return a nice date for header label
        formatted_date = "{} {}.{:02d}, {:04d} ".format(
            WEEKDAYS[r.datetime[6]], MONTHS[month], mday, year
        )
        return formatted_date
    # Event occurs today, return the time only
    return formatted_time


def display_calendar_events(resp_events):
    # Display all calendar events
    for event_idx in range(len(resp_events)):
        event = resp_events[event_idx]
        # wrap event name around second line if necessary
        event_name = magtag.wrap_nicely(event["summary"], 25)
        event_name = "\n".join(event_name[0:2])  # only wrap 2 lines, truncate third..
        event_start = event["start"]["dateTime"]
        print("-" * 40)
        print("Event Description: ", event_name)
        print("Event Time:", format_datetime(event_start))
        print("-" * 40)
        # Generate labels holding event info
        label_event_time = label.Label(
            font_event,
            x=7,
            y=40 + (event_idx * 35),
            color=0x000000,
            text=format_datetime(event_start),
        )
        magtag.splash.append(label_event_time)

        label_event_desc = label.Label(
            font_event,
            x=88,
            y=40 + (event_idx * 35),
            color=0x000000,
            text=event_name,
            line_spacing=0.65,
        )
        magtag.splash.append(label_event_desc)


# Create a new MagTag object
magtag = MagTag()
r = rtc.RTC()

# DisplayIO Setup
magtag.set_background(0xFFFFFF)

# Add the header
line_header = Line(0, 30, 320, 30, color=0x000000)
magtag.splash.append(line_header)

font_h1 = bitmap_font.load_font("fonts/Arial-18.pcf")
label_header = label.Label(font_h1, x=5, y=15, color=0x000000)
magtag.splash.append(label_header)

# Set up calendar event fonts
font_event = bitmap_font.load_font("fonts/Arial-12.pcf")

if not google_auth.refresh_access_token():
    raise RuntimeError("Unable to refresh access token - has the token been revoked?")
access_token_obtained = int(time.monotonic())

while True:
    # check if we need to refresh token
    if (
        int(time.monotonic()) - access_token_obtained
        >= google_auth.access_token_expiration
    ):
        print("Access token expired, refreshing...")
        if not google_auth.refresh_access_token():
            raise RuntimeError(
                "Unable to refresh access token - has the token been revoked?"
            )
        access_token_obtained = int(time.monotonic())

    # fetch calendar events!
    print("fetching local time...")
    now = get_current_time()

    # setup header label
    label_header.text = format_datetime(now, pretty_date=True)

    print("fetching calendar events...")
    events = get_calendar_events(CALENDAR_ID, MAX_EVENTS, now)

    print("displaying events")
    display_calendar_events(events)

    board.DISPLAY.show(magtag.splash)
    board.DISPLAY.refresh()

    print("Sleeping for %d minutes" % REFRESH_TIME)
    magtag.exit_and_deep_sleep(REFRESH_TIME * 60)

You should have the following files on your CIRCUITPY drive.

Set Google Calendar ID

Before using this code with your calendar, you'll need to obtain the Google calendar's unique identifier. Navigate to the Google Calendar Settings Page and click the calendar you'd like to display on the MagTag.

Before using this code with your calendar, you'll need to obtain the Google calendar's unique identifier.

Navigate to the Google Calendar Settings Page and click the calendar you'd like to display on the MagTag.

Scroll down on the page until you see the Calendar ID.

Copy this value to your clipboard.

In the code.py file, set CALENDAR_ID using the calendar ID you obtained above.

CALENDAR_ID = "YOUR_CALENDAR_ID"

Code Usage

Every 15 minutes, the MagTag will attempt to fetch your calendar's latest events and display three of them on the screen. 

Once an event finishes and the MagTag refreshes, it will be removed from the display.

Change the refresh rate

After fetching and displaying calendar events, the MagTag goes into a deep-sleep mode for 15 minutes. Modify the following line in the code to reflect how long the MagTag will enter the deep sleep mode for, in minutes. 

# Amount of time to wait between refreshing the calendar, in minutes
REFRESH_TIME = 15

More frequent refresh will use more battery life. If you want the refresh to be quite frequent, consider using a USB C power supply (or connection to USB power from a computer or phone charger brick) to have the MagTag powered all the time.

The official Raspberry Pi USB-C power supply is here! And of course, we have 'em in classic Adafruit black! Superfast with just the right amount of cable length to get your Pi 4...
$7.95
In Stock
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...
$7.95
In Stock

The Google Calendar Event Display code uses the Google Calendar API's Event list endpoint to return events from a specific calendar.

The results from a GET request to this endpoint will look something like the following:

{
 "kind": "calendar#events",
 "etag": "\"p32c9b6vtqmbes0g\"",
 "summary": "Meetings",
 "updated": "2021-01-12T15:06:56.911Z",
 "timeZone": "America/New_York",
 "accessRole": "owner",
 "defaultReminders": [],
 "nextPageToken": "CigKGjMyajF0bm0xcmwzbDBnbWhmNTNyaW9xb3B2GAEggIDA3tm_zrYXGg0IABIAGJiVm_3Vlu4CIgcIBBC35scP",
 "items": [
  {
   "kind": "calendar#event",
   "etag": "\"3219736474490000\"",
   "id": "32j1tnm1rl3l0gmhf53rioqopv",
   "status": "confirmed",
   "htmlLink": "https://www.google.com/calendar/event?eid=MzJqMXRubTFybDNsMGdtaGY1M3Jpb3FvcHYgYWpmb242cGhsN24xZG1wanNkbGV2dHFhMDRAZw",
   "created": "2021-01-05T17:35:02.000Z",
   "updated": "2021-01-05T17:37:17.245Z",
   "summary": "Adafruit Show and Tell",
   "creator": {
    "email": ""
   },
   "organizer": {
    "email": "@group.calendar.google.com",
    "displayName": "Meetings",
    "self": true
   },
   "start": {
    "dateTime": "2021-01-06T19:30:00-05:00"
   },
   "end": {
    "dateTime": "2021-01-06T20:00:00-05:00"
   },
   "iCalUID": "@google.com",
   "sequence": 0,
   "reminders": {
    "useDefault": true
   }
  }
 ]
}

All events are kept within an items array which contains detailed information about each event. The code parses this array for the event's summary and the event's start dateTime

Refreshing Google API Access Token

The Google Calendar API access token expires after a specific time interval. If the access token is expired, the refresh token in secrets.py is used to POST a request to Google's servers for a new access token.

if (int(time.monotonic()) - access_token_obtained>= google_auth.access_token_expiration):
  print("Access token expired, refreshing...")
  if not google_auth.refresh_access_token():
    raise RuntimeError(
      "Unable to refresh access token - has the token been revoked?"
    )
    access_token_obtained = int(time.monotonic())

Fetching Calendar Events

Prior to calling Google Calendar, a timestamp must be obtained to display the latest events in ascending order. The code calls the Adafruit IO time service to fetch and set the timestamp we'll use for requesting data from Google Calendar.

# fetch calendar events!
print("fetching local time...")
now = get_current_time()

We'll display the current date at the top of the MagTag. Passing a pretty_date argument formats the struct_time timestamp into a human-readable timestamp such as "January 6th, 2021"

# setup header label
label_header.text = format_datetime(now, pretty_date=True)

We use call get_calendar_events with the timestamp to request a list of calendar events in ascending order.

print("fetching calendar events...")
events = get_calendar_events(CALENDAR_ID, MAX_EVENTS, now)

Within get_calendar_events, we perform a HTTP GET to Google Calendar API's event list endpoint

time_max = get_current_time(time_max=True)
    print("Fetching calendar events from {0} to {1}".format(time_min, time_max))

    headers = {
        "Authorization": "Bearer " + google_auth.access_token,
        "Accept": "application/json",
        "Content-Length": "0",
    }
    url = (
        "https://www.googleapis.com/calendar/v3/calendars/{0}"
        "/events?maxResults={1}&timeMin={2}&timeMax={3}&orderBy=startTime"
        "&singleEvents=true".format(calendar_id, max_events, time_min, time_max)
    )
    resp = requests.get(url, headers=headers)

Then, the response is parsed. Each entry in the response's items array is parsed and appended to an items list. This list is returned as events.

resp_json = resp.json()
    if "error" in resp_json:
        raise RuntimeError("Error:", resp_json)
    resp.close()
    # parse the 'items' array so we can iterate over it easier
    items = []
    resp_items = resp_json["items"]
    if not resp_items:
        print("No events scheduled for today!")
    for event in range(0, len(resp_items)):
        items.append(resp_items[event])
    return items

Back in the while True loop, the code passes the event list to display_calendar_events.

print("displaying events")
display_calendar_events(events)

display_calendar_events iterates through the resp_events list. In each iteration, it parses an event's start time and description from the list and generates labels to display the data on the device's screen.

def display_calendar_events(resp_events):
    # Display all calendar events
    for event_idx in range(len(resp_events)):
        event = resp_events[event_idx]
        # wrap event name around second line if necessary
        event_name = magtag.wrap_nicely(event["summary"], 25)
        event_name = "\n".join(event_name[0:2])  # only wrap 2 lines, truncate third..
        event_start = event["start"]["dateTime"]
        print("-" * 40)
        print("Event Description: ", event_name)
        print("Event Time:", format_datetime(event_start))
        print("-" * 40)
        # Generate labels holding event info
        label_event_time = label.Label(
            font_events,
            x=7,
            y=35 + (event_idx * 35),
            color=0x000000,
            text=format_datetime(event_start),
        )
        magtag.splash.append(label_event_time)

        label_event_desc = label.Label(
            font_events,
            x=88,
            y=35 + (event_idx * 35),
            color=0x000000,
            text=event_name,
            line_spacing=0.65,
        )
        magtag.splash.append(label_event_desc)

Finally, the display elements are shown on the screen and the MagTag enters low power mode for REFRESH_TIME minutes.

board.DISPLAY.show(magtag.splash)
board.DISPLAY.refresh()

print("Sleeping for %d minutes" % REFRESH_TIME)
magtag.exit_and_deep_sleep(REFRESH_TIME * 60)

This guide was first published on Jan 13, 2021. It was last updated on Jan 13, 2021.