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.
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
$ 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:
- Find the Feed belonging to
usernamewhose Key is exactly the same as
- If no Feed is found, convert the given
identifierusing the Name-to-Key translation (described above) and find the Feed belonging to
usernamewhose Key is exactly the same as the converted value.
- If no Feed is found, find the Feed belonging to
usernamewhose Name is exactly the same as
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
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:
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: