Events can be sent to and from devices on the Medium One platform using MQTT.
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 projectuser_mqtt
: unique ASCII string identifier for a user in a Medium One projectclient_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 pageuser_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 from the Actions dropdown 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"}