Overview

Adafruit IO is the easiest way to stream, log, and interact with your data. It's built from the ground up to be easy to use - we do the hard stuff so you can focus on the fun stuff.

If you want to the best way of bringing your project online - combine Adafruit IO and AirLift! Our ESP32-based AirLift boards and breakouts are the newest way to connect your project to Adafruit IO, our internet-of-things service for everyone!

Before you continue with this guide, you should run through the guide for your connecting specific board or breakout to the Internet. This guide assumes your AirLift hardware is set up, connected to the Internet, and ready to connect to Adafruit IO.

Why use AirLift?

Having WiFi managed by a separate chip means your code is simpler, you don't have to cache socket data, or compile in & debug an SSL library. With AirLift, you can send basic but powerful socket-based commands over 8MHz SPI for high speed data transfer. The ESP32 can handle all the heavy lifting of connecting to a WiFi network and transferring data from a site, even if its using the latest TLS/SSL encryption (it has root certificates pre-burned in).

The firmware on board is a slight variant of the Arduino WiFiNINA core, which works great, and our Adafruit IO Libraries for CircuitPython and Arduino support AirLift!

External AirLift

If you already have a project which uses a popular microcontroller (like the ATMega328 or ATSAMD51), you can easily add WiFi by using an externally connected AirLift module.

Adafruit AirLift – ESP32 WiFi Co-Processor Breakout Board

PRODUCT ID: 4201
Give your plain ol' microcontroller project a lift with the Adafruit AirLift - a breakout board that lets you use the powerful ESP32 as a WiFi co-processor. You probably...
$12.95
IN STOCK

AirLift all-in-One Boards

Don't want to add extra hardware to your project? Consider grabbing a board which has an ESP32 WiFi co-processor built-in!

Adafruit Metro M4 Express AirLift (WiFi) - Lite

PRODUCT ID: 4000
Give your next project a lift with AirLift - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the Adafruit Metro...
$34.95
IN STOCK

Adafruit PyPortal - CircuitPython Powered Internet Display

PRODUCT ID: 4116
PyPortal, our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in minutes. Make custom touch screen interface...
$54.95
IN STOCK

Adafruit IO Setup

If you have not already registered an Adafruit IO account, visit the registration page and sign up

Once you have registered an account, navigate to Adafruit IO and log into your account. You'll be directed to the Home page.

Click View AIO Key on the right-hand sidebar to retrieve your Adafruit IO Username and Active Key.

Write these down somewhere safe - you'll need them later!

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.

Arduino IO Library

Adafruit IO Arduino is NOT compatible with AVR boards like the Metro 328p

If you're using a non-SAMD board (such as an Adafruit Metro or Arduino Uno) with an AirLift Co-Processor, you will not be able to use Adafruit IO Arduino with an AirLift Breakout/Shield/FeatherWing (it's a large library and will not fit on these boards).

For using these boards securely with Adafruit IO, we suggest the Adafruit MQTT Library instead of Adafruit IO Arduino. We've added a usage example for AirLift Co-Processors here.

Installation

Installing Adafruit IO on Arduino requires four libraries: Adafruit's WiFiNINAAdafruit IO, Adafruit MQTT, and ArduinoHttpClient.

If you have these libraries already installed - you will need to update them to the versions listed on this page for use with AirLift.

To install the Adafruit WiFiNINA library, click the link below to download the library as a zip file:

To install this library, navigate to the Add .ZIP Library option in the Sketch -> Include Library menu and select the zip file from the file browser.

You are going to install the next few libraries using the Arduino Library Manager. Navigate to the Manage Libraries... option in the Sketch -> Include Library menu.

adafruit_io_library_menu.png

Enter Arduino HTTP into the search box, and click Install on the ArduinoHttpClient library option to install version 0.4.0 or higher.

adafruit_io_Library_Manager.png

Enter Adafruit MQTT into the search box, and click Install on the Adafruit MQTT library option to install version 1.0.0 or higher.

adafruit_io_Library_Manager.png

Enter Adafruit IO Arduino into the search box, and click Install on the Adafruit IO Arduino library option to install version 3.1.0 or higher.

Now that we have installed all of the dependencies, we can try to run one of the Adafruit IO example sketches.

Navigate to the adafruitio_00_publish sketch by opening the File -> Examples -> Adafruit IO Arduino menu.

adafruit_io_select_example.png

Click on the config.h tab, and replace the placeholders with your Adafruit IO info and WiFi connection credentials.

Since we are using AirLift with Adafruit IO Arduino, make sure to uncomment the line #define USE_AIRLIFT line in the sketch so it looks like the following:

Download: file
// uncomment the following line if you are using airlift
#define USE_AIRLIFT

If you do not see this line, upgrade the Adafruit IO Arduino Library to the latest version.

If you're using an externally connected AirLift module (such as a breakout), you'll need to configure your ESP32's pins in the section of config.h where the ESP32 pins are defined:

If you're using an AirLift All-in-One board, you don't need to perform pin configuration - Adafruit IO does this for you automatically based on the board's ESP pin definitions.

Then, compile and upload the sketch to your board.

Usage

Once the sketch is uploaded, you can now click the serial monitor icon to view the output of the sketch.

If everything goes as expected, you should see counter values being sent to Adafruit IO.

  • If you are not connecting to Adafruit IO, check your WiFi and Adafruit IO credentials in config.h and try uploading your sketch again using the process above.

Congrats - you've sent a value to an Adafruit IO Feed!

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 navigate to the monitor page.

If everything worked correctly, you should see an incrementing value sent to the counter feed while the code is running.

Next Steps

You've successfully connected your Arduino board to Adafruit IO - so, 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.

IO FAQ

Can I build my own Client Library for Adafruit IO?

Absolutely - the same API that drives our user interface is available to you. We provide documentation so you can build a library in your favorite language to talk to IO

My data isn't displaying, is Adafruit IO's {service/MQTT/API} down?

Possibly - you can check IO status on the Adafruit Status page

Is my data being sent properly? Am I sending too much data?

There's a monitor page built-into Adafruit IO which provides a live view of incoming data and error messages. Keep this page open while you send data to your Adafruit IO devices to monitor data and errors. 

What about the data that my project generates? Where does it go? What happens to it? Are you going to sell it?

The data your store with IO is yours to manage and control. You can download it all anytime and we will never sell or give it away to another company. We feel strongly enough about this that we put it in our IoT Bill of Rights.

I have an Alexa/Echo Dot/AI Voice Assistant. How do I interface it with Adafruit IO?

Currently, the easiest way of doing this is by chaining events through a web-service such as IFTTT which has integrated Alexa Skills and Google Assistant Skills.

I don't see my question listed.

If you have any questions or issues with Adafruit IO, post up in the Adafruit IO Forums or chat with Adafruit staff and community members in real-time on the adafruit-io channel on the Adafruit Discord server.

This guide was first published on Apr 30, 2019. It was last updated on Apr 30, 2019.