MQTT with Adafruit

Adafruit is an open-source hardware company that is popular among the maker community. One of their services is Adafruit IO, which is a MQTT broker.

The broker has a free tier with some restrictions. It is perfectly usable for makers with few devices.

Prerequisites

We assume that you have set up your development environment as described in the IDE tutorial.

We also assume that you have flashed your device with Jaguar and that you are familiar with running Toit programs on it. If not, have a look at the Hello world tutorial.

While not necessary, we recommend to do the MQTT tutorial first.

Note that you can do this tutorial without a device. In that case, you need to use the -d host option whenever you invoke jag run. The program will then run on your computer instead of on a device.

Packages

The MQTT functionality is not part of the core libraries and must be imported as a package. See the packages tutorial for details.

We are using the mqtt package. To install it, run the following command:

jag pkg install github.com/toitware/mqtt@v2

When connecting to TLS secured services we will also use the certificate-roots package:

jag pkg install github.com/toitware/toit-cert-roots@v1

Adafruit IO

To use Adafruit IO, you need to create an account. Go to io.adafruit.com and create an account.

Once you have created an account, you need to create a feed. Feeds are topics that you can publish to and subscribe from. Go to io.adafruit.com/feeds and click on the "+ New Feed" button to create a new feed. For this tutorial we will use the feed temperature.

Click on the "AIO Key" button on the top right of the page (next to "+ New Device"). This opens a dialog with your AIO key.

Copy the username and key. You will need them later.

Code

The following code connects to Adafruit IO and publishes a message every 2.5 seconds. The message goes to the feed temperature and will thus be a simple number. The number is a simulated temperature reading, and will randomly fluctuate (starting at 25°C).

Don't forget to replace <YOUR_USERNAME> and <YOUR_KEY> with your username and key. If you created a feed with a different name, you also need to change the ADAFRUIT-IO-FEEDNAME constant.

We will leave the CLIENT-ID empty. This means that the broker will generate a random client ID for us. It also resets the session with every connection. If you want to take full advantage of the broker, you should use a persistent client ID. See the MQTT tutorial for details.

import certificate-roots
import mqtt

ADAFRUIT-IO-USERNAME ::= "<YOUR_USERNAME>"
ADAFRUIT-IO-KEY ::= "<YOUR_KEY>"

ADAFRUIT-IO-FEEDNAME ::= "temperature"

ADAFRUIT-IO-HOST ::= "io.adafruit.com"

CLIENT-ID ::= ""

main:
  certificate-roots.install-common-trusted-roots

  client := mqtt.Client.tls --host=ADAFRUIT-IO-HOST
  /**
  // Alternatively, you can also connect without TLS, by using the
  // following client constructor:
  client := mqtt.Client --host=ADAFRUIT-IO-HOST
  // In that case you can remove the `certificate-roots` import and
  // avoid calling `certificate-roots.install-common-trusted-roots`.
  */

  options := mqtt.SessionOptions
    --client-id = CLIENT-ID
    --username = ADAFRUIT-IO-USERNAME
    --password = ADAFRUIT-IO-KEY

  client.start --options=options

  print "Connected to broker"

  topic := "$ADAFRUIT-IO-USERNAME/feeds/$ADAFRUIT-IO-FEEDNAME"

  // Simulates a temperature sensor.
  temperature := 25.0
  10.repeat:
    temperature += ((random 100) - 50) / 100.0
    client.publish topic "$temperature".to-byte-array
    // Don't publish too often to avoid rate limiting.
    sleep --ms=2_500

  client.close

You can see the published values on https://io.adafruit.com/<ADAFRUIT_IO_USERNAME>/feeds/temperature.

Adafruit IO features

In this tutorial we only publish messages to Adafruit IO. However, Adafruit IO also supports many other features: You can, obviously, also subscribe to feeds. You can also create dashboards and visualize your data. You can also create triggers that send you emails or text messages when certain conditions are met.

The Adafruit IO documentation contains a lot of information about the service.

For MQTT specific information, see Adafruit IO MQTT API.