Overview

Want to make your project talk to the Internet? Connect your existing project to the Internet to log, stream, and interact with the data it produces? What about all this Internet-of-Things (IoT) stuff?

Adafruit IO is a platform designed (by us!) to display, respond, and interact with your project's data. We also keep your data private (data feeds are private by default) and secure (we will never sell or give this data away to another company) for you. It's the internet of things - for everyone!

Why We Built Adafruit IO

Here at Adafruit, we sell all of these amazing components, but we couldn't find a good way to interact with them over the Internet. There are certainly a lot of great services out there for datalogging, or communicating with your microcontroller over the web, but these services are either too complicated to get started, or they aren't particularly fun to use. So, we decided to experiment with our own system, and that's Adafruit IO.

What is Adafruit IO?

Adafruit.io is a cloud service - that just means we run it for you and you don't have to manage it. You can connect to it over the Internet. It's meant primarily for storing and then retrieving data but it can do a lot more than just that!

What can Adafruit IO do for me?

  • Display your data in real-time, online
  • Make your project internet-connected: Control motors, read sensor data, and more!
  • Connect projects to web services like Twitter, RSS feeds, weather services, etc.
  • Connect your project to other internet-enabled devices
  • The best part? All of the above is do-able for free with Adafruit IO

Dashboards

Adafruit.io can handle and visualize multiple feeds of data. Want to display data from a temperature-humidity sensor alongside data from an air quality sensor and add a button to turn on the air-conditioner in your room?

No problem! Dashboards are a feature integrated into Adafruit IO which allow you to chart, graph, gauge, log, and display your data. You can view your dashboards from anywhere in the world. 

Triggers

Use triggers in Adafruit IO to control and react to your data. Configure triggers to email you when your system goes offline, react to a temperature sensor getting too hot, and publish a message to a new feed.  

Integration with IFTTT and Zapier

Want to make your project react to an email, display trending tweets, or turn on the front lights when your pizza is on the way? We baked in integrations with IFTTT and Zapier to connect your project's sensors to hundreds of web services.  

Getting Started with Adafruit IO

GOOD NEWS - we integrated Adafruit IO with your adafruit.com account so you don't need to create yet-another-online-account! 

You need an account because we want to make sure the data you upload is available to you and only you until you are ready to make it public

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.

You will be directed to your profile page showing your plan, connected services, and account data:

From here, you'll want to learn about two important features of Adafruit IO before proceeding further -  Feeds and Dashboards

Feeds

Feeds are the core of Adafruit IO. They hold both the data you uploaded and meta-data about the data your sensors push to Adafruit IO. For example, the date and time when it was uploaded. Or, the GPS coordinates where the data came from.

 

Want to share your data feed with the world, a group of people, or just a friend? Adafruit IO has integrated feed sharing with fine-tuned privacy controls to allow (and restrict) access to your data. 

 

Click here to learn more about Feeds in Adafruit IO Basics: Feeds

Dashboards

Dashboards are a feature integrated into Adafruit IO which allow you to chart, graph, gauge, log, and visualize your data. You can view your dashboards from anywhere in the world. 

 

Click here to learn more about Dashboards in Adafruit IO Basics: Dashboards

Arduino and Adafruit IO

Have an Arduino or Arduino-Compatable board which you want to use with Adafruit IO? Want to adapt your sketch to Adafruit IO? It's easy! We provide two libraries which work with lots of compatable hardware. 

Need inspiration or project examples? We built sixteen examples sketches to get you up and running, along with six guides to follow-along to. 

Compatible Hardware

The Adafruit IO Arduino Libraries can connect with Adafruit IO using Arduino. You can connect your projects using a connected-interface of your choosing: WiFi (ESP8266, ESP82, WINC1500, and WICED), Ethernet, or Cellular. 

There's a ton of hardware using these interfaces available, but this guide is going to highlight boards Adafruit produces and sells:

WiFi

You know WiFi - you use it all-day every-day. It’s the standard wireless protocol for connecting to the Internet. It’s available not only at home and work but also in stores, cafes, trains, planes and in most major cities. The worldwide universality of WiFi makes it a common first choice for IoT. - All the Internet of Things

The Adafruit IO Arduino and MQTT libraries are compatible with hardware using using ESP8266, ESP32, WINC1500, and WICED interfaces. 

We offer two ESP8266-based platforms:

 

  • Adafruit Feather HUZZAH with ESP8266 is our take on an 'all-in-one' ESP8266 WiFi development board with built in USB and battery charging. Its an ESP8266 WiFi module with all the extras you need, ready to rock!

 

  • Adafruit HUZZAH ESP8266 Breakout is what we designed to make working with this chip super easy and a lot of fun. We took a certified module with an onboard antenna, and plenty of pins, and soldered it onto our designed breakout PCBs. This version is tougher to use than the Feather because it needs a separate cable, so its not recommended for beginners

The Adafruit HUZZAH32 is our ESP32-based Feather, made with the official WROOM32 module. We packed everything you love about Feathers: built in USB-to-Serial converter, automatic bootloader reset, Lithium Ion/Polymer charger, and just about all of the GPIOs brought out so you can use it with any of our Feather Wings.

Adafruit Feather M0 WiFi w/ATWINC1500 is our take on an 'all-in-one' Arduino-compatible + high speed, reliable WiFi with built in USB and battery charging. Its an Adafruit Feather M0 with a WiFi module, ready to rock!

The ATWINC1500 802.11bgn-capable WiFi module is the best new thing for networking your devices, with built-in low-power management capabilites, Soft-AP, SSL TSL 1.2 support and rock solid performance.

Ethernet 

Good ol' Ethernet. This ‘ancient’ protocol has withstood the test of time. You almost certainly use Ethernet at home and at work. Ethernet has a standardized connector, the venerable RJ-45. When you need something to "just work," often a wire will do that. (Just because it's "IoT" doesn't mean it's wireless, just that many Things happen to be wireless.) - All the Internet of Things

Our Adafruit IO libraries can also talk to Adafruit IO using ethernet!

Ethernet FeatherWing will let you add quick and easy wired Internet. Just plug in a standard ethernet cable, and run the Ethernet2 library for cross-platform networking. Works with all/any of our Feather boards!

Cellular Connectivity 

Cell phones can go just about anywhere - there are towers across every country, in almost any place there are people. And cellular towers can be very powerful. When coupled with a high power transceiver on your device, range can easily hit miles away. - All the Internet of Things

The Adafruit FONA is a all-in-one cellular phone module which lets you connect your project using Adafruit IO to a cellular network. This is great for projects which either move around (like a car-interface) or are in remote places (like a data-logger!)

Libraries

Before you get started using Adafruit IO with your Arduino, you'll need to select a library. We provide and support both of these libraries, but try starting with the Adafruit IO Arduino Library below:

Adafruit IO Arduino Library

The Adafruit IO Arduino Library is a simple library to send and receive feed data using the Adafruit IO REST API. We suggest using it before moving onto the more advanced features of the MQTT Library.

The library supports the following network platforms and hardware: 

Installation

You can install the library through the Arduino Library Manager (click: Sketch -> Include Library -> Manage Libraries...)

Usage

The included examples sketches will walk you through all of the features of the library. They can be used on all platforms, but they default to WiFi. Most of the sketches have companion projects on the Adafruit Learning system.

To change between platforms, you will need to change two lines of code in the config.h tab of the example. It is recommended that you start with one of the Adafruit WiFi feathers before moving on to cellular or ethernet.

For all examples, you will need to set IO_USERNAME and IO_KEY in the config.h tab:

To find your IO_USERNAME, navigate to your profile on Adafruit IO and click View AIO Key. Copy the Username field (ctrl+c or command+c)

Then, in the config.h tab, replace the "your_username" text with your the username from your profile:

To find your IO_Key, navigate to your profile, click View AIO Key, and copy the ACTIVE KEY field to your clipboard (ctrl+c or command+c).

In config.h, replace the IO_KEY with the IO Key copied to your clipboard.

Using the Adafruit IO Arduino Library with WiFi

If you are using the included examples, you do not need to change anything for the Adafruit WiFi Feathers. All WiFi based Feathers (ESP8266, M0 WiFi, WICED) will work with the examples out of the box once you add your WiFi SSID and Password to the config.h file. 

In the config.h tab, replace "your_ssid" with your WiFi's SSID and "your_pass" with your WiFi's password:

Using the Adafruit IO Arduino Library with Ethernet

For Ethernet, you will only need to change from the default WiFi constructor to the Ethernet specific constructor in the config.h tab. The rest of the sketch remains the same.

You will need to comment out these WiFi lines in config.h:

#include "AdafruitIO_WiFi.h"
AdafruitIO_WiFi io(IO_USERNAME, IO_KEY, WIFI_SSID, WIFI_PASS);

and uncomment the Ethernet lines in config.h:

#include "AdafruitIO_Ethernet.h"
AdafruitIO_Ethernet io(IO_USERNAME, IO_KEY);

Using the Adafruit IO Arduino Library with Cellular (32u4 FONA)

For FONA, you will only need to change from the default WiFi constructor to the FONA specific constructor in the config.h tab. The rest of the sketch remains the same.

You will need to comment out these WiFi lines in config.h:

#include "AdafruitIO_WiFi.h"
AdafruitIO_WiFi io(IO_USERNAME, IO_KEY, WIFI_SSID, WIFI_PASS);

and uncomment the FONA lines in config.h:

#include "AdafruitIO_FONA.h"
AdafruitIO_FONA io(IO_USERNAME, IO_KEY);

If your carrier requires APN info, you can set it by adding a call to io.setAPN() after io.connect() in the setup()function of the sketch.

void setup() {
  // start the serial connection
  Serial.begin(115200);
  // connect to io.adafruit.com
  io.connect();
  io.setAPN(F("your_apn"), F("your_apn_user"), F("your_apn_pass"));
}

Adafruit MQTT Arduino Library  

We also have a library to provide support for accessing Adafruit IO using MQTT. This is a general-purpose MQTT library for Arduino that's built to use as few resources as possible so that it can work with platforms like the Arduino Uno.  Unfortunately platforms like the Trinket 3.3V or 5V (based on the ATtiny85) have too little program memory to use the library--stick with a Metro 328p or better!

The MQTT library supports the following network platforms and hardware:

Installation

You can install the library through the Arduino Library Manager (click: Sketch -> Include Library -> Manage Libraries...)

If you're using an Adafruit FONA, you'll need to install an additional two libraries for the MQTT Library to work properly:

Projects

Adafruit IO Basics

Todd Treece has put together seven guides using Adafruit IO for input, temperature, humidity, servo control, and so much more:

Digital Input: Wire a circuit to send momentary button press data to your Adafruit IO Dashboard

Digital Output: Turn on a LED or a lamp from anywhere in the world!

Color: Send data from Adafruit IO to control a RGB LED. 

Temperature and Humidity: Send humidity and temperature values from a DHT22 sensor to Adafruit IO 

Analog Output: LED and other analog hardware control from Adafruit IO.

Analog Input: Send light sensor data in real-time and view it using using Adafruit IO.

Servo Control: Move physical objects...without wires!

Adafruit IO on the Adafruit Learning System

The Adafruit Learning System is also a great place to find learning guides which answer the age-old maker question of "what do I build next?".

Here are some of our favorite guides using Adafruit IO:

Gmailbox

Build a physical mailbox for your emails using Adafruit IO and IFTTT

Adafruit IO Environmental Monitor for Feather or Raspberry Pi

Build an internet-enabled environmental monitor to see what's in the air you breathe using Arduino

Adafruit IO Home: Lights and Temperature

Learn all about home automation by building a cardboard smart-house, controlling its lights, and monitoring temperature!

Home Automation in the Cloud with the ESP8266 & Adafruit IO

Build a simple home automation system & control it from anywhere!

Cloud Cam: Internet-Connected Security Camera

Build a camera that detects motion and sends images to cloud services like Dropbox & Adafruit IO!

Smart Toilet Light

Make your toilet bowl glow with data from Adafruit IO!

Adafruit IO Projects on the Blog!

The Adafruit Blog is also a good resource for finding your next project. Check out the Adafruit IO blog posts here!

Python and Adafruit IO

Want to use Adafruit IO with your computer or a Raspberry Pi? 

The Adafruit IO Python library provides two clients for accessing Adafruit IO (MQTT and HTTP) and lots of examples. It's compatible with any system running CPython3 and also compatible with Single-Board computers like the Raspberry Pi.

Compatible Hardware

Write your code in Python and connect it to the internet with Adafruit IO!

CircuitPython Libraries for Raspberry Pi

We’ve written a special library called Adafruit Blinka to provide the layer that translates the CircuitPython hardware API to whatever library the Linux board provides.

We’ve got tons of projects, libraries and example code for CircuitPython on microcontrollers, and thanks to the flexibility and power of Python, it’s easy to get it working with microcomputers like Raspberry Pi or other ‘Linux with GPIO pins available’ single board computers.

What does this mean for Adafruit IO?

You can control your Raspberry Pi by writing Python code, but what about connecting that to the internet? 

We've updated the Adafruit IO library with usage examples for Python and Adafruit IO

Suggested Hardware

The Raspberry Pi Zero W offers all the benefits of the full-sized Pi and built-in WiFi. This board is perfect for Adafruit IO projects which require a Feather-like form factor.

Raspberry Pi Zero W

PRODUCT ID: 3400
If you didn't think that the Raspberry Pi Zero could possibly get any better, then boy do we have a pleasant surprise for you! The new Raspberry Pi Zero W...
$10.00
IN STOCK

The Raspberry Pi 3 Model B+ boasts a 64-bit quad core processor, 5GHz wireless LAN and faster (300mbps) Ethernet. If you'd like to have a beefier hardware platform to use with Adafruit IO and possibly some more intensive libraries (such as OpenCV) - this is the ideal hardware platform for your project.. 

Raspberry Pi 3 - Model B+ - 1.4GHz Cortex-A53 with 1GB RAM

PRODUCT ID: 3775
The Raspberry Pi 3 Model B is the most popular Raspberry Pi computer made, and the Pi Foundation knows you can always make a good thing better! And what could make the Pi 3...
$35.00
OUT OF STOCK

I don't see the board I wish to use listed here.

Adafruit Blinka is in development. As we continue to develop it, we'll be adding more board support. 

For a complete list of boards supported, visit the CircuitPython.org page for Blinka.

Client Library

Installing Adafruit IO Python

If you have PIP installed (typically with apt-get install python-pip on a Debian/Ubuntu-based system), run:

sudo pip3 install adafruit-io

This will automatically install the Adafruit IO Python client code for your Python scripts to use. There are usage examples within the examples folder of the GitHub repository for use with MQTT, API, and Basic IO functionality. 

Note: This library requires Python3. It is incompatible with Python2.

Library Usage

We provide usage examples within the examples folder of the GitHub repository for the REST API and MQTT.

If you want to download all the examples to your computer, clone the repository in a easy-to-access location.

To do this, type this in your terminal to navigate to your desktop:

cd Desktop

Download the latest version of the repository by entering the following command into your terminal:  

git clone https://github.com/adafruit/Adafruit_IO_Python.git

Then, navigate to the examples folder by entering the following into your terminal:

cd Adafruit_IO_Python/examples/

Note: For all examples in this folder, you'll need to set the ADAFRUIT_IO_KEY and ADAFRUIT_IO_USERNAME before running the program.

Library Documentation

Documentation for all methods and classes in the Adafruit IO Python library can be found on the ReadTheDocs page for this project

Projects

Adafruit IO Basics for CircuitPython

We've updated our Adafruit IO Basics Series to add compatibility for using Adafruit IO and Python. These are the best examples if you're looking to get started building projects.

Projects and Inspiration

You can find projects which use Adafruit IO Python in the Adafruit Learning System's IoT Category.

Other Client Libraries

We also support a few other languages with our client libraries:

Node.js

Writing a Node.js web application? We provide a Node.js client, local server, and TLS tunnel for io.adafruit.com on our GitHub. This library can use both the REST API and the MQTT API to access feeds and data on Adafruit IO.

The library readme on GitHub describes how to install and use the library.

Ruby

If you have a Ruby program you'd like to interface with Adafruit IO, we provide a Ruby Client on our Github. This library wraps the REST API to access feeds and data on Adafruit IO. The library readme shown on GitHub describes how to install and use the library.  

Be sure to also see the examples included for use with this library.

Go

You can also talk to your io.adafruit.com account using our go client library. The library requires go version 1.2 and running tests requires the testify library, which can be installed with:

Download: file
$ go get github.com/stretchr/testify

Be sure to also see our usage notes along with the godoc page for full package documentation.

IO Plus

Your Adafruit IO experience is even better with IO+. The 'plus' stands for MORE STUFF! More feeds, dashboards, storage, speed. IO+ unlocks more data, more storage, and more feeds than our free service.

Upgrading your account to IO+ gives you:

  • 60 data points per minute
  • 60 days of data storage
  • Unlimited dashboards
  • Unlimited feeds

Subscribing to Adafruit.IO

Ready to subscribe to Adafruit IO+? Visit your profile page and click the Upgrade to IO+ button:

Then, fill out your payment information, and your Adafruit IO account will be upgraded to IO Plus!

IO Plus FAQ

Why should I subscribe to IO Plus? How is it billed?

For one, uncomplicated price you get unlimited feeds and dashboards, a higher data input rate, and longer data storage.

IO+ subscriptions are billed immediately when you subscribe and then monthly or yearly, repeating each month or year on the same day you signed up until you cancel.

Payments and Credit Card Processing

We use Stripe for payment processing and subscription management and are currently able to accept every major credit card including: Visa, Master Card, American Express, Discover, JCB, and Diners Club. All charges are denominated in USD (United States dollars) but international customers are welcome!

What if I want to cancel my IO+ Subscription?

It's easy and painless - when you cancel your Adafruit IO+ subscription, your access to IO+ will continue until the end of your current billing cycle. At then end of your subscription period you account will be restored to IO Free account limits. Right now that's 10 feeds, 5 dashboards, 30 days of data storage, and a 30 data points per minute data rate. Data that has already been stored will be preserved, and all extra feeds and dashboards will be archived.

I'm having trouble with billing, or payment processing. Can you help?

Absolutely! If you have a question we haven't answered here or on the Adafruit IO forums, or if you have a question about your subscription specifically, you can use the Adafruit Contact page to get in touch with our support team directly.

Is there a way to purchase IO+ for a yearly fee instead of billing monthly?

Sure, we offer a one-year subscription pass in the Adafruit store. 

Can I gift an IO Plus subscription to my friend, coworker, family-member, or a fellow maker?

You can purchase the subscription pass for yourself or as a gift, and send it to a family or friend. Code is redeemable within https://io.adafruit.com once you are signed in to your account. The code is not locked to any specific account until it is redeemed.

Troubleshooting your Adafruit IO Project

The Problem with IoT Project Troubleshooting

Much like a sandwich, Adafruit IO projects have a lot of layers where things can go wrong. As a result, it becomes much harder to troubleshoot these types of projects.

There's the hardware (like a Feather ESP8266) layer which brings issues such as "why isn't my motor turning". Your wiring may be an issue. The code could be incorrect. It could even be a networking issue, which brings us to the next layer...

Then, there's networking which connects your internet-controlled project to the internet. Problems could arise here resulting to DNS configuration, port forwarding problems, or your router simply not talking to The Internet™.

There's also The Internet™, and that brings a lot of problems too. Finally there's Adafruit IO, a web service that we built and support. 

...and there could be problems with any layer of this delicious sandwich. 

How to Help Out ("I have a problem that's not listed here, what now?")

If your project is not working properly, the Adafruit community is here to help you out. 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.

While we help out and see repeated issues, we'll add them to this page to help others. 

Common Issues

My Serial Monitor prints "..." endlessly after the "Connecting to Adafruit IO" message

Your board is not connecting to Adafruit IO, but why? Let's find out:

First, check in config.h that you have the correct IO_USERNAME, IO_KEY, WIFI_SSID, and WIFI_PASS are set correctly. 

Next, we're going to modify the while loop which waits for an IO connection in your sketch. Change the line in the status check loop from Serial.println(.); to Serial.println(io.statusText());

// wait for a connection
while(io.status() < AIO_CONNECTED) {
Serial.println(io.statusText());
delay(500);
}

Verify and re-upload the sketch. If you're receiving a Network disconnected error message, the board is not able to talk to the internet. Re-check your hardware, connections, and router settings. 

If it's still not showing Adafruit IO connected, check the IO status on the Adafruit Status page to make sure the service is online.

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

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. 

My dashboard is reporting a temperature reading in Fahrenheit/Celsius but I need it in the opposite unit

The dashboard displays information from feeds. Chances are, the sensor you are using is outputting a temperature in Fahrenheit/Celsius but you need to convert it (in your code) to the opposite unit. Here's some handy pseudo-code to help out:

From Fahrenheit to Celsius:

   degreesFahrenheit = degreesCelsius × 9/5 + 32

From Celsius to Fahrenheit: 

   degreesCelsius = (degreesFahrenheit - 32) × 5/9

I'm using an Feather M0 WiFi (ATWINC1500) and it's not connecting to Adafruit IO.

If you're using a Feather M0 WiFi and receiving a Disconnected from Adafruit IO message in your serial monitor, you'll want to check two things:

  1. Make sure that you have the correct Adafruit IO Keys in your sketch, and that the router/network configuration is correct. 
  2. The SSL ceritifcates on your device for Adafruit IO need to be up-to-date. It's hard to check if they're up-to-date from the device, so we suggest running through the process of adding a new SSL certificate through the Arduino IDE. You can find the guide for that here.

Board-Specific Issues

ESP8266

Error: 'AdafruitIO_WiFi' does not name a type

From Boards Manager, downgrade from ESP8266 v2.5.0-beta2 to stable 2.4.2.

REST API Documentation

The Adafruit IO HTTP API provides access to your Adafruit IO data from any programming language or hardware environment that can speak HTTP. 

To view the most current HTTP API documentation, click the button below. 

The source code for our documentation in Open API v2 format is available at https://github.com/adafruit/io-api.

For questions or comments regarding this documentation, post up on the Adafruit IO Subforum or the help-with-adafruit-io channel on the Adafruit Discord server.

MQTT API Documentation

MQTT, or message queue telemetry transport, is a protocol for device communication that Adafruit IO supports. Using a MQTT library or client you can publish and subscribe to a feed to send and receive feed data.

If you aren't familiar with MQTT check out this introduction from the HiveMQ blog.  All of the subsequent posts in the MQTT essentials series are great and worth reading too.

To use the MQTT API that Adafruit IO exposes you'll need a MQTT client library.  For Python, Node.js, and Arduino you can use Adafruit's IO client libraries as they include support for MQTT (see the client libraries section).  For other languages or platforms look for a MQTT library that ideally supports the MQTT 3.1.1 protocol.

Connection Details

You will want to use the following details to connect a MQTT client to Adafruit IO:

  • Host: io.adafruit.com
  • Port: 1883 or 8883 (for SSL encrypted connection)
  • Username: your Adafruit account username (see the accounts.adafruit.com page here to find yours)
  • Password: your Adafruit IO key (click the AIO Key button on a dashboard to find the key)

We strongly recommend using SSL if your MQTT client allows it.

If the MQTT library requires that you set a client ID then use a unique value like a random GUID.  Most MQTT libraries handle setting the client ID to a random value automatically though.

Topics

Adafruit IO's MQTT API exposes feed data using special topics.  You can publish a new value for a feed to its topic, or you can subscribe to a feed's topic to be notified when the feed has a new value.  Any one of the following topic forms is valid for a feed:

  • (username)/feeds/(feed name or key)
  • (username)/f/(feed name or key)

And for groups:

  • (username)/groups/(group name or key)
  • (username)/g/(group name or key)

Where (username) is your Adafruit IO username (the same as specified when connecting to the MQTT server) and (feed name or key) is the feed's name or key.  The smaller '/f/' path is provided as a convenience for small embedded clients that need to save memory.

Check out our guide to Feed Naming for the full details.

For example if your username is mosfet and you're accessing a feed called Photocell One (which has a Key of photocell-one) you can use any of these paths:

  • mosfet/feeds/Photocell One
  • mosfet/f/Photocell One
  • mosfet/feeds/photocell-one
  • mosfet/f/photocell-one

In order to reduce confusion, however, we always recommend using the Key to refer to a specific feed or group in code.

To append a new value to a feed perform a MQTT publish against the feed topic and provide the new feed value as the payload of the request.

To be notified of a change in a feed perform a MQTT subscribe to the feed topic.  When a new value is added to the feed then the Adafruit IO MQTT server will send a notification with the new feed value in the payload.

You can also subscribe to the parent 'feeds' path to be notified when any owned feed changes using MQTT's # wildcard character.  For example the mosfet user could subscribe to either:

  • mosfet/feeds/#
  • mosfet/f/#

Once subscribed to the path above any change to a feed owned by mosfet will be sent to the MQTT client.  The topic will specify the feed that was updated, and the payload will have the new value.

Be aware the MQTT server sends feed updates on all possible paths for a specific feed. For example, subscribing to mosfet/f/# and publishing to mosfet/f/photocell-one would produce messages from: mosfet/f/photocell-one, mosfet/f/photocell-one/json, and mosfet/f/photocell-one/csv; each referring to the same updated value.  To reduce noise, make sure to grab the specific topic of the feed / format you're interested in and change your subscription to that.

PLEASE NOTE: as we adjust which identifiers we use for Feeds internally, the feed updates you receive when using a wildcard will include but may not be limited to the ones shown above.

If you'd like to avoid the formatted feeds ("/json" and "/csv" topics) but still see all the feeds you're publishing to, you can use MQTT's + wildcard in place of #. In this case, subscribing to mosfet/f/+ would produce output on mosfet/f/photocell-one, but not mosfet/f/photocell-one/json.

Publish QoS Levels

One feature of MQTT is the ability to specify a QoS, or quality of service, level when publishing feed data.  This allows an application to confirm that its data has been sucessfully published.  If you aren't familiar with MQTT QoS levels be sure to read this great blog post explaining their meaning.

For publishing feed values the Adafruit IO MQTT API supports QoS level 0 (at most once) and 1 (at least once) only.  QoS level 2 (exactly once) is not currently supported.

Rate Limit

Adafruit IO's MQTT server imposes a rate limit to prevent excessive load on the service.  If a user performs too many publish actions in a short period of time then some of the publish requests might be rejected.  The current rate limit is at most 1 request per second (or 60 requests within 60 seconds).

If you exceed this limit, a notice will be sent to the (username)/throttle topic. You can subscribe to the topic if you wish to know when the Adafruit IO rate limit has been exceeded for your user account.

This limit applies to all connections so if you have multiple devices or clients publishing data be sure to delay their updates enough that the total rate is below 2 requests/second.

Data Format

There are a few ways to send data to our MQTT API if you're writing your own client library.

The simplest way to send values to an IO Feed topic is to just send the value. For example, a temperature sensor is going to produce numeric values like 22.587. If you're sending to mosfet/feeds/photocell-one you can use the raw number or a string. That means either 22.587 or "22.587" will be accepted as a numeric value. Adafruit IO does its best to treat data as numeric values so that we can show you your data as a chart on an Adafruit IO dashboard and through our Charting API.

Data with Location

To tag your data with a location value, you'll either need to wrap it in a JSON object first or send it to the special /csv formatted MQTT topic.

Sending JSON

JSON can be sent to either the base topic or the /json topic - for example mosfet/feeds/photocell-one or mosfet/feeds/photocell-one/json. The proper format for location tagged JSON data is:

{
  "value": 22.587, 
  "lat": 38.1123,
  "lon": -91.2325, 
  "ele": 112
}

Specifically, JSON objects must include a "value" key, and may include "lat", "lon", and "ele" keys. 

Sending CSV

Alternatively, you can send location tagged data to /csv topics. In this example, that would be the topic mosfet/feeds/photocell-one/csv instead of mosfet/feeds/photocell-one. Both store data in the same feed. The format IO expects for location tagged CSV data is VALUE, LATITUDE, LONGITUDE, ELEVATION.

With the example data shown before, that means you could publish the string "22.587,38.1123,-91.2325,112" to mosfet/feeds/photocell-one/csv. to store the value "22.587" in the location latitude: 38.1123, longitude: -91.2325, elevation: 112.

Examples

Using a simple Ruby MQTT library and the data shown, all these examples publish the same data to the same feed:

Download: file
# first you'll need https://github.com/njh/ruby-mqtt
require 'mqtt'

username = 'test_username'
key      = 'not-a-real-key'
url      = "mqtts://#{ username }:#{ key }@io.adafruit.com"

mqtt_client = MQTT::Client.connect(url, 8883)

# simplest thing that could possibly work
mqtt_client.publish('test_username/feeds/example', 22.587)

# sending numbers as strings is fine, IO stores all data internally
# as strings anyways
mqtt_client.publish('test_username/feeds/example', '22.587')

# CSV formatted, no location
mqtt_client.publish('test_username/feeds/example/csv', '22.587')

# CSV formatted, with location
mqtt_client.publish('test_username/feeds/example/csv', 
                    '22.587,38.1123,-91.2325,112')

# JSON formatted, no location 
mqtt_client.publish('test_username/feeds/example', '{"value":22.587}')
mqtt_client.publish('test_username/feeds/example/json', '{"value":22.587}')

# JSON formatted, with location
mqtt_client.publish('test_username/feeds/example', 
  '{"value":22.587,"lat":38.1123,"lon":-91.2325,"ele":112}')
mqtt_client.publish('test_username/feeds/example/json',
  '{"value":22.587,"lat":38.1123,"lon":-91.2325,"ele":112}')

Sending JSON data through Adafruit IO

Because Adafruit IO supports additional features beyond a basic MQTT brokering service, such as location tagging for data points, the service supports data in the JSON format described above. Namely:

{
  "value": 22.587, 
  "lat": 38.1123,
  "lon": -91.2325, 
  "ele": 112
}

This lets us store the individual value, 22.587, and data about the value: its latitude, longitude, and elevation. Metadata!

But what happens when the value you want to send is itself JSON? Good news! There are a few solutions available to you in that situation.

 

IO formatted JSON

The simplest way to send JSON data to Adafruit IO is to wrap it in the format described above. For example, if instead of 22.587, I wanted to send something like, {"sensor-1":22.587,"sensor-2":13.182}, the "wrapped" version would look like this:

{
  "value": {"sensor-1":22.587,"sensor-2":13.182}, 
  "lat": 38.1123,
  "lon": -91.2325, 
  "ele": 112
}

It's worth noting that because Adafruit IO parses the entire JSON object that you send it, any valid JSON will be parsed and when it is stored in our system and forwarded to any subscribers, it will be regenerated. The significance of that is that if you publish JSON data with whitespace, it will be stored and republished without whitespace, because our generator produces the most compact JSON format possible.

 

Double encoded JSON strings

The second way you can send JSON data as a value is to "double encode" it before sending, in which case IO will treat it as a raw string. If you're using something like javascript's JSON.stringify function or Ruby's JSON.generate, double encoding means passing the result of JSON.stringify through JSON.stringify a second time. In this node.js console example, you can see the difference:

> JSON.stringify({"sensor-1":22.587,"sensor-2":13.182})
'{"sensor-1":22.587,"sensor-2":13.182}'
> JSON.stringify(JSON.stringify({"sensor-1":22.587,"sensor-2":13.182}))
'"{\"sensor-1\":22.587,\"sensor-2\":13.182}"'


The double encoded JSON string can be sent directly through Adafruit IO without interference from our processing system, because the processing system will not interpret it as JSON. In your receiving code, because the value passed through includes surrounding double quotes, you have to call your parse function twice to restore the JSON object.

> var input = '"{\\\"sensor-1\\\":22.587,\\\"sensor-2\\\":13.182}"'
> JSON.parse(JSON.parse(input))
{ 'sensor-1': 22.587, 'sensor-2': 13.182 }

 

Non-IO formatted JSON

The third way you can send raw JSON data is to just send it. If Adafruit IO doesn't find a "value" key in the JSON object you send, it will treat the whole blob as plain text and store and forward the data. That means with our example JSON object, sending the string {"sensor-1":22.587,"sensor-2":13.182} will result in {"sensor-1":22.587,"sensor-2":13.182} being stored in IO and sent to MQTT subscribers.

If you're dynamically generating JSON and want to avoid 

Using Group Topics

You aren't limited to just Feed based MQTT topics, Adafruit IO supports grouped feeds as well. Similar to our HTTP group data creation API, you can publish to multiple feeds or subscribe to multiple feeds through a single MQTT topic.

The topics formats for publishing or subscribing are:

  • (username)/groups/(group name or key)
  • (username)/groups/(group name or key)/json
  • (username)/groups/(group name or key)/csv

Publishing to feeds in a group

If you use the /json or /csv endings on your group MQTT topic, your data should be formatted in JSON or CSV, respectively. By default, IO expects published values to be in JSON format.

The JSON format IO expects looks like this:

{
  "feeds": {
    "key-1": "value 1",
    "key-2": "value 2",
    "key-3": "value 3"
  },
  "location": {
    "lat": 0.0,
    "lon": 0.0,
    "ele": 0.0
  }
}

The CSV format IO expects is:

key-1,value 1
key-2,value 2
key-3,value 3
location,0.0,0.0,0.0

Guidelines for publishing to group MQTT topics:

  • In each payload format, "key-1" represents the respective feed's key and "value 1" represents the value you'd like to publish to that feed.
  • For CSV location values, the location is interpreted as `lat`, `lon`, `ele` and `ele` is optional / not required.
  • Any number of feeds present in the group may be included.
  • Each value may be either a string or a number.
  • If any feed key is included that does not already belong to a feed in the group, then a new feed with the given key as its name will be created.

Subscribing to groups

If you use the /json or /csv endings when subscribing to your group MQTT topic, your data will be formatted in JSON or CSV, respectively. By default, IO publishes values in JSON format.

The formats your subscription will receive are the same as the formats IO expects to receive, so in the case of JSON:

{
  "feeds": {
    "key-1": "value 1",
    "key-2": "value 2",
    "key-3": "value 3"
  },
  "location": {
    "lat": 1.0,
    "lon": 2.0,
    "ele": 3.0
  }
}

And CSV:

key-1,value 1
key-2,value 2
key-3,value 3
location,1.0,2.0,3.0

It's important to note that you will only receive updated values for the feeds that received new values. That means if you're subscribed to {username}/groups/example and publish to {username}/feeds/key-1, the subscription will receive:

{
  "feeds": {
    "key-1": "value 1"
} }

It's also worth noting that JSON subscription formats will always receive string type values, regardless of whether a string or number was published.

Retrieving the Last Published Value

MQTT is a tremendously useful protocol for building small connected devices and is relatively simple to understand and implement (if implementing networking protocols is your thing). Unfortunately, a few features of the Adafruit IO platform make it difficult for us to support the entire MQTT 3.1+ protocol specification in our broker. Specifically, one particular feature, the publish retain flag.

In the MQTT protocol, setting the retain flag on a published message asks the MQTT broker (server) to store that message. Then any new clients which connect and subscribe to that topic will immediately receive the retained message. Retain makes writing basic MQTT-only Internet of Things clients easier, without it, a client that connects and subscribes to a feed topic has to wait until a new value is published on the feed to know what state it should be in. In the case of slowly updated feeds, there could be hours between updates which means a device that disconnects and reconnects (for example, due to power cycling or sleeping) might lose the current value for a long time between updates.

Among other factors, our scale, Adafruit IO's mix of MQTT & HTTP APIs, the speed at which we’re taking in new data, and the fact that we’re already storing almost every message that is sent mean that a “simple” feature like retain becomes difficult to support without making MQTT service performance worse for everyone.

Since we don’t actually store data in the broker but at a lower level and can’t support PUBLISH retain directly, we’re proposing a different solution for the retaining problem: the /get topic modifier.

The way it works is that for any given Adafruit IO MQTT feed or group, subscribe to the appropriate topic, then add /get to the topic you subscribed to and publish anything to that new topic (our Arduino library uses the null character: '\0') . IO will immediately publish, just for that client, the most recent value received on the feed.

For example, let's imagine we have a device that subscribes to a counter feed: uname/f/counter. If we want to get the latest value, the /get topic we should publish to is uname/f/counter/get. After connecting, subscribing, and publishing to the /get topic, we will immediately receive a message on our uname/f/counter subscription with the last value that was published to the feed.

If you’re using the Adafruit IO Arduino library, you can add /get support to your project in one line of code:

// ... from the adafruitio_01_subscribe example sketch
AdafruitIO_Feed *counter = io.feed("counter");

void setup() {

  // 1. start IO connection
  io.connect();

  // 2. prepare MQTT subscription with handler function
  counter->onMessage(handleMessage);

  // 3. wait for successful connection
  while(io.mqttStatus() < AIO_CONNECTED) {
    delay(500);
  }

  // 4. send /get message, requesting last value
  counter->get(); // ask Adafruit IO to resend the last value

}
// ....

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 Jun 13, 2018. It was last updated on Jun 13, 2018.