Basic topic formatting: first level 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.

Messages from device:

  • Event data. Ex: temperature, light level
    • 0/<project_mqtt_id>/<user_mqtt_id>/<device_id>/
    • Here <device_id> may be a zero length string.
    • The message payload will be interpreted as a JSON dictionary that will be sent as the event. The dictionary must have the format {"event_data": <json dictionary>}. 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.

Message to device:

  • Processed events from workflows. E.g.: signal to turn on light
    • 1/<project_mqtt_id>/<user_mqtt_id>/<device_id>/event
    • No constraints are made regarding the contents of the message sent to the device other than the payload constraints of MQTT.
  • Logic, data updates. These would likely be 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>

Device should subscribe to:

  • 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>/#

Device registration:

  • Must be connected as an API Registration User
  • Subscribe to topic:
    • 5/<project_mqtt_id>/<desired_login_id>
  • Publish
    • 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" : "..." }