Step-by-step MQTT Tutorial
Definitions
Project hash and user hash are unique ASCII string identifiers for projects and users respectively that are legal MQTT topic levels (no control characters, or '#', '+' or '/' characters). Note that as they are used in MQTT topic levels, these are case sensitive.
Important Note: client_id is part the MQTT protocol. It’s required to be a unique string (up 32 characters). Most MQTT clients generate a unique ID. If your MQTT client does not generate a unique MQTT ID (ie. using Arduino, we’ll need to supply a unique client_id). We recommend using your username: /
Device IDs are identifiers assigned by you for individual devices (or possibly applications on a device). Device IDs must be valid MQTT topic levels (valid UTF-8 strings without the characters '+', '/' or '#" or any control characters). It's highly recommended that device IDs be restricted to ASCII alphanumeric characters and the characters '-' and '_'. Failing that, standard ASCII (again excluding control characters, '+', '/' or '#") , or finally normalized unicode strings.
Groups IDs are identifiers assigned by you that may cut across multiple users. Group IDs should follow the same rule as Device IDs. For instance there may be a "microwaves" group, a "2014-microwaves" group and a "MT-2014A" group for a specific model number. A MT-2014A microwave might listen to messages sent to all three groups.
Note: There are no formal controls for groups or device IDs, which groups a device should listen to are up to you. Nothing prevents a dishwasher from listening to the microwave group, and nothing prevents device A from sending messages as device B or listening to messages for device B.
Getting hash information
project_hash can be found at the Project MQTT ID page
user_hash can be found by grabbing user info from the REST API. It will return user_hash in the user info.
MQTT authentication
Device users authenticate with a username of the form "<project_hash>/<user_hash>" with a password of the form "<api_key>/<user_password>". Device users can send events associated with their user hash, receive messages associated with their user hash, and receive group messages associated with their project hash.