Topics

Topics enable communication between the platform and devices.

The first level of the topic contains a number, which is a message delivery classification.

0 indicates a message from device to the cloud. 1 indicates a message from the cloud to a specific device. 2 indicates a message from the cloud to a group of devices.

Publish message to cloud

The device will send event data to the cloud, for example, it could send temperature data or a light sensor reading.

  • Topic: 0/<project_mqtt_id>/<user_mqtt_id>/<device_id>/
  • Payload: JSON dictionary of the format {"event_data": <data to send to cloud>, "observed_at": <ISO timestamp>}. See CRUD Events for more information on formatting events. 
    • If <device_id> is not a zero length string, then "device": <device_id> will be added to the event_data dictionary.
    • If "observed_at" is not part of the dictionary, server time will be added as the "observed_at" time.

Publish message to device

The device can receive different types of data sent from the cloud. No constraints are made regarding the contents of the message sent to the device other than the payload constraints of MQTT.

Processed Workflow Events

The device will receive data from the cloud which will be sent from a workflow. This could be a signal to turn on a light for example.

  • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/event

Logic + Data Updates

The device will receive data from the cloud sent as retained messages so that a device would be able to receive messages sent when not connected. Ex: new filters, ML models

  • Could be user/device specific: such as ML model
    • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/update/<update_type>
  • For updates for all devices for a user _all can be used as a device ID.
    •  1/<project_mqtt_id>/<user_mqtt_id>/_all/update/<update_type>
  • Could be general for all users for a project or a subset of the users (all users that share a device type, device model, firmware version, etc.)
    • 2/<project_mqtt_id>/_all/<update_type>
    • 2/<project_mqtt_id>/<group_id>/<update_type>

Subscribe to messages from cloud on device

These are the topics your devices should subscribe to in order to receive messages from the cloud.

  • If the project uses device IDs:
    • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/#
    • 1/<project_mqtt_id>/<user_mqtt_id>/_all/#
  • Otherwise:
    • 1/<project_mqtt_id>/<user_mqtt_id>/#
  • 2/<project_mqtt_id>/_all/#
  • For every relevant group:
    • 2/<project_mqtt_id>/<group_id>/#

Register a device

  • Must be connected as an API Registration User
  • Subscribe to topic:
    • 5/<project_mqtt_id>/<desired_login_id>
  • Publish to topic:
    • 4/<project_mqtt_id>/<desired_login_id>
    • Message should be an empty JSON object {}
  • 'desired_login_id' is the username of the device you want to register
  • Once the user is created, you will receive a message to your subscription of the format:
    • { "mqtt_id" : "..." , "password" : "..." }