Naming and Accessing Feeds With the MQTT API

Naming a Feed on the fly and then referring to it reliably can be tricky. Here are the rules we're using right now to generate new Feeds and provide continuing access to them from the MQTT interface. For the purposes of demonstration, we'll be using the example code provided here, but any MQTT publisher or subscriber code should work the same.

1. Listening

Start an MQTT subscription to topic in the form username/f/identifier, for the purpose of the following examples I'll be using, test_username/f/Test Mode. A Feed with the name "Test Mode" doesn't exist yet, but that's okay with the MQTT API. The subscription will remain active and start receiving whenever you start publishing to a Feed whose Name or Key matches the given identifier value exactly.

NOTE: no new Feeds are created in this step.

$ AIO_FEED_NAME='Test Mode' ruby adafruit-errors-sub.rb
CONNECT TO mqtts://test_username:[email protected]
SUB test_username/f/Test Mode

We'll also start an MQTT subscriber listening to test_username/errors. This will let us see when there are problems with publishing or subscribing to Feeds.

$ ruby adafruit-errors-sub.rb
CONNECT TO mqtts://test_username:[email protected]uit.com

2. Initial MQTT publish / creating a new Feed

To create the Feed in Adafruit IO and to start populating it with data, we'll need to publish and MQTT message to the appropriate topic. In this case, we're subscribing to a Feed named "Test Mode", so we'll need to publish on a Feed with the same name.

Using the example script provided, we'll publish a simple MQTT message with the topic test_username/f/Test Mode:

$ AIO_FEED_NAME='Test Mode' ruby adafruit-pub.rb
CONNECT TO mqtts://test_username:[email protected]
PUBLISHING TO test_username/f/Test Mode
PUB 2609815 to test_username/f/Test Mode at 2016-07-11 12:53:23 -0400

If this is your first time publishing to the Feed, the subscriber that's listing to test_username/f/Test Mode should receive its first message:

[test_username/f/Test Mode 2016-07-11 12:53:23 -0400] 2609815

This first is a Feed created message and the second is the actual data received message.

3. Tweaking Names: Publish to a Feed by name with capitalization changed

Once the Feed has been established, publishing to any named Feed whose Key is the same as an existing Feed will add Data to the existing Feeds stream.

PUB 3124870 to test_username/f/test mode at 2016-07-11 12:39:34 -0400

And the original Feed subscriber, which is still watching test_username/f/Test Mode, receives:

[test_username/f/Test Mode 2016-07-11 12:39:34 -0400] 3124870

4. Tweaking Names: Publish to a Feed by key

Once the Feed has been established, publishing to an existing Feed's Key will add Data to the existing Feeds stream.

PUB 1181702 to test_username/f/test-mode at 2016-07-11 12:42:28 -0400

The Feed subscriber, still watching test_username/f/Test Mode, receives:

[test_username/f/Test Mode 2016-07-11 12:42:28 -0400] 1181702

5. Valid name variations for publishing

When publishing, the method Adafruit IO uses internally to convert a given topic in the form username/feeds/identifier to a specific, existing Feed works like this:

  1. Find the Feed belonging to username whose Key is exactly the same as identifier.
  2. If no Feed is found, convert the given identifier using the Name-to-Key translation (described above) and find the Feed belonging to username whose Key is exactly the same as the converted value.
  3. If no Feed is found, find the Feed belonging to username whose Name is exactly the same as identifier.

Thanks to the Name-to-Key conversion rules, the following topics will all publish to the original Feed created in step 2 and be received by the subscriber at test_username/f/Test Mode:

  • test_username/f/Test_Mode
  • test_username/f/Test-Mode
  • test_username/f/Test Mode
  • test_username/f/ Test Mode
  • test_username/f/Test Mode
  • test_username/f/Test -Mode
  • test_username/f/ Test - Mode

And so on, including any variation of modified capitalization.

Some variations that include symbols will be converted to URL-safe Keys when looking up the requested Feed:

  • test_username/f/Test(Mode
  • test_username/f/Test\[Mode
  • test_username/f/Test{Mode
  • test_username/f/test modé
  • test_username/f/test' mode

6. Valid name variations for subscribing

Subscriptions, on the other hand, must use an exact Name or Key. So, for the given examples, the only topics that will produce the Feed we care about are:

  • test_username/f/Test Mode
  • test_username/f/test-mode
This guide was first published on Jul 15, 2016. It was last updated on Jul 15, 2016. This page (Naming and Accessing Feeds With the MQTT API) was last updated on Aug 23, 2019.