CircuitPython

To easily connect AirLift hardware to Adafruit IO using CircuitPython, we've written an Adafruit IO CircuitPython module to provide simple interaction with the Adafruit IO HTTP and MQTT APIs.

Install CircuitPython

Some of the 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. 

Internet Connect!

Once you have CircuitPython setup and libraries installed, you can get your project connected to the Internet.

To do this, you'll be editing CircuitPython code and will need an editor. We suggest using Mu, a lightweight text editor with support for CircuitPython built-in. 

Click the button below to get instructions on how to install the Mu Editor.

If you have not yet connected your board to the Internet, follow one of the guides below and come back when you've successfully connected to the internet:

Secrets File Setup for Adafruit IO

While you created a secrets file and connected to the Internet in the previous step, you'll need to edit the secrets file to include your Adafruit IO Username and Secret Key.

Add the following code to your secrets.py file, replacing _your_adafruit_io_username with your Adafruit IO username.

Then, replace _your_big_huge_super_long_aio_key_ with your Adafruit IO Active Key.

Download: file
secrets = {
    'ssid' : '_your_wifi_ssid',
    'password' : '_your_wifi_password',
    'aio_username' : '_your_adafruit_io_username',
    'aio_key' : '_your_big_huge_super_long_aio_key_'
    }

Make sure you save this file before proceeding as secrets.py in the root directory of your board CIRCUITPY drive.

CircuitPython Library Installation

To interface your AirLift breakout/board with and the Internet - you'll need to install a few CircuitPython libraries on your board.

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 matching your version of CircuitPython. 

Before continuing - make sure your board's lib folder has the following files and folders copied over.

  • adafruit_io
  • adafruit_esp32spi
  • adafruit_bus_device 
  • neopixel.mpy

CircuitPython Usage

Copy the following code to your code.py file on your microcontroller:

"""
Sending data to Adafruit IO and receiving it.
"""
from random import randint
import board
import busio
from digitalio import DigitalInOut

# ESP32 SPI
from adafruit_esp32spi import adafruit_esp32spi, adafruit_esp32spi_wifimanager

# Import NeoPixel Library
import neopixel

# Import Adafruit IO HTTP Client
from adafruit_io.adafruit_io import IO_HTTP, AdafruitIO_RequestError

# 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

# ESP32 Setup
try:
    esp32_cs = DigitalInOut(board.ESP_CS)
    esp32_ready = DigitalInOut(board.ESP_BUSY)
    esp32_reset = DigitalInOut(board.ESP_RESET)
except AttributeError:
    esp32_cs = DigitalInOut(board.D9)
    esp32_ready = DigitalInOut(board.D10)
    esp32_reset = DigitalInOut(board.D5)

spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
status_light = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.2) # Uncomment for Most Boards
"""Uncomment below for ItsyBitsy M4"""
#status_light = dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1, brightness=0.2)
wifi = adafruit_esp32spi_wifimanager.ESPSPI_WiFiManager(esp, secrets, status_light)

# Set your Adafruit IO Username and Key in secrets.py
# (visit io.adafruit.com if you need to create an account,
# or if you need your Adafruit IO key.)
aio_username = secrets['aio_username']
aio_key = secrets['aio_key']

# Create an instance of the Adafruit IO HTTP client
io = IO_HTTP(aio_username, aio_key, wifi)

try:
    # Get the 'temperature' feed from Adafruit IO
    temperature_feed = io.get_feed('temperature')
except AdafruitIO_RequestError:
    # If no 'temperature' feed exists, create one
    temperature_feed = io.create_new_feed('temperature')

# Send random integer values to the feed
random_value = randint(0, 50)
print('Sending {0} to temperature feed...'.format(random_value))
io.send_data(temperature_feed['key'], random_value)
print('Data sent!')

# Retrieve data value from the feed
print('Retrieving data from temperature feed...')
received_data = io.receive_data(temperature_feed['key'])
print('Data from temperature feed: ', received_data['value'])

Connect to the serial monitor to see the output. It should look something like the following:

Download: file
code.py output:
Sending 13 to temperature feed...
Data sent!
Retrieving data from temperature feed...
Data from temperature feed:  13

If the REPL outputs an AttributeError instead of running the code - you'll need to manually configure the AirLift module pin connections.

To do this, edit the following lines of code by replacing the pin values of esp32_cs, esp32_ready, and esp32_reset with the pinout from your AirLift module:

Download: file
except AttributeError:
    esp32_cs = DigitalInOut(board.D9)
    esp32_ready = DigitalInOut(board.D10)
    esp32_reset = DigitalInOut(board.D5)

Congrats - you've sent a value to an Adafruit IO Feed, and retrieved it back!

Adafruit IO Usage

While you sent data to Adafruit IO, how do you know that Adafruit IO is receiving this data?

One of the most important places to check is the Adafruit IO Monitor Page. This page displays incoming data from your active feeds and any errors which might've occurred. 

To do this, log into Adafruit IO and click here to navigate to the monitor page.

If everything worked correctly, you should see a random value sent to the temperature feed when the code is run.

Next Steps

You've successfully connected your CircuitPython board to Adafruit IO, now what?

Would you like to add a sensor to your project? What about displaying your data on a graph? Control a motor from the Internet? Set the colors of a RGB LED from the Internet? Monitor the temperature and humidity of a room from across the world?

To continue your educational journey with Adafruit IO, click here to visit the Adafruit IO Basics series for guides about the topics listed and more!

Need some inspiration for your next project? We have lots of Adafruit IO-specific guides on the Adafruit Learning System. Click here to view more projects and guides for Adafruit IO.

This guide was first published on Apr 30, 2019. It was last updated on Apr 30, 2019. This page (CircuitPython) was last updated on Aug 18, 2019.