Server Topics API

Authentication

The MQTT authentication is handled by the underlying MQTT client which authenticates and receives a sessionID that isn't required when publishing or subscribing to commands on the endpoints. Each command is transmitted over the established MQTT session.

Publishing

property.publish - Publish the <value> you wish to send as a string to topic thing/<thingKey>/property/<propKey>.  (Equivalent of sending the following TR50 API call.)

{
  "1" : {
    "command" : "property.publish",
    "params" : {
      "thingKey" : "<thingKey>",
      "key" : "<propKey>",
      "value" : <value>
    }
  }
}

alarm.publish - Publish the <state> you wish to set the alarm to as a string to topic thing/<thingKey>/alarm/<alarmKey>. (Equivalent of sending the following TR50 API call.)

{
  "1" : {
    "command" : "alarm.publish",
    "params" : {
      "thingKey" : "<thingKey>",
      "key" : "<alarmKey>",
      "state" : <state>
    }
  }
}

thing.attribute.set - Publish the <value> you wish to set the attribute to as a string to topic thing/<thingKey>/attribute/<attrKey>. (Equivalent of sending the following TR50 API call.)

{
  "1" : {
    "command" : "thing.attr.set",
    "params" : {
      "thingKey" : "<thingKey>",
      "key" : "<attrKey>",
      "value" : <value>
    }
  }
}

Subscriptions

If a client uses MQTT topics such as thing/<thingkey>/property/<propkey> or any of the other server topics, it takes up to 30 seconds for the first subscription to occur before publishes begin to be received by the client. After the first subscription is completed, then any subsequent subscriptions will have immediate effect.

Property changes

  • Subscribe to a topic such as thing/<thingKey>/property/<propKey> to receive the new value set to the property when it changes.
  • The value is published to the topic as a string.
  • Remember, only QoS 0 and 1 are supported.

Alarm changes

  • Subscribe to a topic such as thing/<thingKey>/alarm/<alarmKey> to receive the new state set to the alarm when it changes.
  • The State is published to the topic as a string.
  • Remember, only QoS 0 and 1 are supported.

Location changes

  • Subscribe to a topic such as thing/<thingKey>/location to receive real-time location updates for the given thing.
  • The location is published to the topic as: latitude, longitude, heading, speed, altitude, and fix type.
  • Remember, only QoS 0 and 1 are supported.

Connection state changes

  • Subscribe to a topic such as thing/<thingKey>/connection/+ to receive real-time updates when a thing connects or disconnects from the platform.
  • To receive only connects, subscribe to thing/<thingKey>/connection/connect.
  • To receive only disconnects, subscribe to thing/<thingKey>/connection/disconnect.
  • The timestamp when the event occurred is published to the topic.

 Other topics

  • Use other topics that do not begin with "api" or "thing" for custom application development.  Note that use of other topics is subject to monitoring and additional charges if usage is deemed "excessive".

 Custom thing topics

  • A custom thing topic has the following structure: thing/thingKey/custom/topicString

  • The words "thing" and "custom" in the topic are required.

  • The thingKey represents any valid key for a thing.

  • The topicString can be one or more topic strings.

  • Only users and things that have permission to the named thing will be able to publish and subscribe to the topic