Introduction

Events can be sent to and from devices on the Medium One platform using MQTT.

This guide assumes you have worked with MQTT before. If you are new to MQTT, we recommend following our step-by-step MQTT Tutorial to help you get started.

Definitions

• Valid MQTT topic level: a case-sensitive ASCII string containing no control characters, or '#', '+' or '/' characters
• project_mqtt: unique ASCII string identifier for a Medium One project
• user_mqtt: unique ASCII string identifier for a user in a Medium One project
• client_id: unique string up to 32 characters. Most MQTT clients generate a unique ID. If your MQTT client does not generate a unique MQTT ID, we recommend using your username: "<project_mqtt>/<user_mqtt>"
• device_id: identifier assigned by you for individual devices (or possibly applications on a device). Device IDs must be valid MQTT topic levels.
• group_id identifier assigned by you that may cut across multiple users. Group IDs should follow the same rule as Device IDs.
  • For example, there may be a "microwaves" group, a "2014-microwaves" group and a "MT-2014A" group for a specific model number. An 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 MQTT information

• project_mqtt: can be found at the Project MQTT ID page
• user_mqtt: there are multiple ways to retrieve this
  • Any user type: grab user info from REST API
  • Device (API Basic User): Go to Setup -> Manage Users. You'll see the MQTT ID in the middle column. If you don't have a Basic User, you can simply create one by clicking on Add New User.
  • 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_mqtt>/<user_mqtt>" with a password of the form "<api_key>/<user_password>". Device users can send events associated with their user MQTT, receive messages associated with their user MQTT, and receive group messages associated with their project MQTT.

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 with the received at time.  When using MQTT, be sure to specify the timestamp at 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"}