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: "<project_hash>/<user_hash>". More information about your username can be found in the "Getting hash information" and "MQTT authentication" sections.
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 (note: you must be logged into M1 for this page to open)
user_hash can be found by grabbing user info from the REST API. It will return user_hash in the user info.
user_hash can also be retrieved from the Medium IoT Platform portal by following these steps.
To retrieve a basic user_hash (for a specific device): Go to Setup -> Manage Users. You'll see the MQTT ID for each device in the middle column. The MQTT ID is the user_hash.
To retrieve the user hash for the device registration user: Go to Setup -> Manage Administrators. Click Edit for the API Registration User type and it will appear in the next page. If you don't have an API Registration User type, you can simply create one by clicking on Add New User.
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.
Note: You can generate an API key under Setup -> Manage API Keys
Timestamping Events
Similar to sending events via REST, you can send the event with the timestamp (ISO format) or without the timestamp. If sending without the timestamp, the server will timestamp it automatically at received time. When using MQTT, be sure to specify the timestamp in microsecond accuracy. Be sure to use "observed_at" as the key at the same level as "event_data" in the JSON message.
Example: {"event_data":{"hello":"world"},"observed_at":"2001-01-01T00:10:10.000000Z"}