It really stinks to get taken by surprise in a negative way when working with code. Reducing surprise of the unpleasant sort andincreasing predictability and stability are the primary motivating factors for the subtle changes this guide introduces.

Publishing to an invalid name

While the Name-to-Key converter keeps things feeling pretty loose and improvisational in terms of referring to Feeds once they exist, if your initial publish is to a Feed that can't be found it will be rejected if it doesn't match the rules for valid Feed names.

In the case of our MQTT example, a publish that looks like this:

PUB 2948554 to test_username/f/Test Modes[ at 2016-07-11 15:42:31 -0400

would trigger a message on the error feed that looks like this:

[test_username/errors 2016-07-11 15:42:31 -0400] "Validation failed: Name may contain only letters, digits, underscores, spaces, or dashes"

If the Feed named "Test Modes" already existed, then the publish would work fine, but because it doesn't Adafruit IO tries to create a Feed with the given identifier, "Test Modes[" as a Name. Since "Test Modes[" is an invalid name, Adafruit IO rejects it :(

Publishing to the wrong identifier

If you set up your MQTT subscription first, it's important to note that no feed will be created, so the Name-to-Key rules laid out above won't have the effect you may have anticipated. This happens when the Feed you eventually publish to doesn't end up with the Key or Name your subscriber has requested. The end result is a subscriber that's silent while your device is merrily publishing away. Maddening! This is a common error of subscription and publishing when trying to juggle the different identifiers that point to a given Feed.

The safest way to avoid this situation is to make sure that your subscribing topic and your publishing topic are exactly the same. If you want to switch to a different identifier--for example, using a Key instead of a Name--copy the value directly from Adafruit IO. When in doubt, use the Name value.

The Feed we're publishing to in the MQTT examples above has the following identifiers:

key:  "test-mode"
name: "Test Mode"

The Name-to-Key translator is how all the "valid name variations" shown above for publishing work, but they only after the Feed already exists. The only way to create this Feed from the MQTT interface is to publish to test_username/f/Test Mode.

Keeping a browser open to your Feeds page while setting up or programming your Adafruit IO devices is recommended.

Modifying a name or key

Remember, changing a Feed's name will automatically update its Key. This is a change to existing behavior and will require modifications to any systems you're running that refer to Feeds by Key, but it prevents more confusing situations from occurring.

Here's a non-hypothetical scenario that illustrates the trouble when we don't keep Keys and Names in sync:

• I make a new Feed and call it, "Light Switch" (IoT light switch, low risk). In JSON, the Feed looks like:

  {
    "name": "Light Switch",
    "key": "light-switch"
  }

• I have a Feather Huzzah controlling a relay, acting as a subscriber listening to username/f/light-switch and a publisher sending data to username/f/Light Switch. Things talk, everything is great with the world.
• I move the hardware over to a new spot and rename the Feed, "Blender Toggle" (IoT blender, high risk). In a non-sync world, the Feed's new Name is "Blender Toggle" and it's Key is still "light-switch. The Feed is now:

  {
    "name": "Blender Toggle", 
    "key": "light-switch"
  }

• My subscriber is still listening to username/f/light-switch, so it still gets all the Feed's messages.
• I build a new remote control and have it publish to username/f/Blender Toggle and it works, because there is a Feed with that exact name.Everything just keeps working, which is okay for now.
• Later on, I decide I'd like to build another remote control light switch, so I put together an Arduino MKR1000 publishing to username/f/Light Switch.
• My new light switch controlling, MKR1000-powered, motion sensor publishes a message to username/f/Light Switch and my blender turns on! What the heck! Hope you're wearing Kevlar gloves!

The MQTT Feed routing rules described earlier mean that a message received on the topic username/f/Light Switch gets routed to the Feed whose Key matches light-switch, which already exists. And controls the blender. Which should not turn on unexpectedly when the room gets dark :P

This is why we keep all Feed Keys updated to match to their respective Feed Names. In Adafruit IO, renaming the Feed to "Blender Toggle" changes the Key to "blender-toggle".

Old Feed:

{
    "name": "Light Switch",
    "key": "light-switch"
}

Change Name to "Blender Toggle" and the Feed now looks like:

{
    "name": "Blender Toggle",
    "key": "blender-toggle"
}

My existing subscriber would immediately stop working because none of the messages sent to username/f/Blender Toggle(new Name) will get routed to the subscriber listening to username/f/light-switch (old Key). This doesn't mean the subscriber breaks or shuts down, only that it stops getting messages for now. This is my chance to realize something is wrong and debug my system.

Here's the tricky bit, if I go in and make a new Feed and name it "Light Switch", it'll get the Key "light-switch". If I didn't update my subscriber when it stopped working, that means it's still listening to username/f/light-switch. When I start posting to my new Feed at username/f/Light Switch, the old subscriber at username/f/light-switch will start getting messages again.

The best defense against confusion is to refer to the Adafruit IO web interface to double check what the Feed you're working with has for Name and Key values. And, when you make changes in Adafruit IO always make sure the cooperating systems are updated, especially when dealing with control systems that interact with the world.

Fixing Existing Feeds

We've updated our Feed identification system, but we didn't go back and change any Feed names or keys for you. That means you might have Feeds you used to be able to reach that don't show up anymore. If this is the case, you should see a warning on https://io.adafruit.com and an indicator on your Feeds page.

The two things you'll need to check if you think there might be a Feed name/key conflict problem are that: 

1. Every Feed has a unique name.
2. No Feed's name matches another Feed's key.

In general, if you're no longer using a Feed, it's a good idea to remove it to avoid conflicts in the future. And, if you're using a lot of similarly named feeds, we strongly recommended that you run through each device or service that is publishing to the feed and do an explicit check to make sure everything is posting to the right place.

And, as in any situation where you're having trouble, please reach out to us on the Adafruit IO forums if you need help. We're here to make things easier!