Thing Update API

This API exposes the full underlying AWS IoT MQTT topic structure for a client logged in through the MIC REST Auth API. All client facing topics are qualified by the domain path of the thing.

In effect this API gives publish/subscribe privilege to things without requiring a certificate.

Device Shadow updates

The AWS topic $aws/things/thingName/shadow/update is the primary topic for a Thing to report values on and for a client to set new desired state for a thing. This topic, and all the possibilities of the original topic, is exposed to a client logged in to MIC on this topic structure: thing-update/domainPathOfTheThing/thingName

A logged in client has the privilege to both subscribe and publish to this topic structure.

thing-update subscription

Given a thing called myTestThing with root as its domain and a user with root as its domain the following are valid topic subscriptions (please note that the root domain is implicit in topics).

  • thing-update/myTestThing subscribe only to events of the thing myTestThing.
  • thing-update/# subscribe to all events on all things under root and on all other things on all other domains.

If the domain of the thing myTestThing was a subdomain called subdomain1 and a direct child of root the subscription topics would be:

  • thing-update/subdomain1/myTestThing subscribe only to events of the thing myTestThing.
  • thing-update/subdomain1/# subscribe to all events on all things under subdomain1 and on all other things on all other domains beneath subdomain1. A user identity with the domain root could still of course do a “catch all” subscription by subscribing to thing-update/#.

thing-update publishing

Publishing to the thing-update topic is straight forward and works the same way $aws/things/thingName/shadow/update works.

A message published on thing-update/myTestThing will be routed to $aws/things/myTestThing/shadow/update. Although there are some validation criteria that need to be met before a message can be rerouted:

  1. The full domain path of the thing to publish to must be part of the topic and must be valid, i.e. the domain path must be found in the domain tree.
  2. The name of the thing must be the last part of the topic and the last part of the domain path must match the domain of the thing

Domain path

The domain path of a thing is always part of the topic structure.

Up to 7 levels of domain nesting, including the implicit root domain, is possible for any topic in the API. The below example is a valid topic and the deepest nested topic possible, i.e. only 7 slashed is allowed in a topic name. This is a hard limit given by AWS IoT: thing-update/sub1/sub2/sub3/sub4/sub5/sub6/myTestThing

Getting the domain path for a thing

By adding the attribute domainTopic to a GET action on the Thing Management API it is possible to retrieve a things fully qualified domain path.

For a root domain the domain path will be a single / and for any subdomain will be on the form /subdomain1/subdomain2/ and so on.

Additional topics

There are few extra topics of interest, that the AWS IoT Device Shadow service provides and that we expose in the client facing API.

The AWS Iot topic to client API mappings are:

  • $aws/things/thingName/shadow/update -> thing-update/domainPathOfTheThing/thingName
  • $aws/things/thingName/shadow/update/delta -> thing-update-delta/domainPathOfTheThing/thingName

Topic privileges of a logged in user

When a user is logged in it is only given privileges to the topic structures that match the domain of the user. Given a domain tree structure of:

  • root
    • subdomain1
      • subdomain2

and a user with the domain subdomain2 topics available to this user will be on the form topicName/subdomain1/subdomain2/*.

 

Strict MQTT client implementations

Some MQTT clients may use a strict implementation of the MQTT version 3.1.1 specification which handles subscriptions using the Multi-level wildcard character (#) differently from less stricter clients.

For example, if using this type of client and subscribing to thing-update/#, it would receive messages published for all subdomains except root itself:

  • thing-update
  • thing-update/subdomain1
  • thing-update/subdomain1/
  • thing-update/subdomain1/subdomain2
  • thing-update/subdomain1/subdomain2/
  • ...

While MIC will publish messages using topic names ending with a forward slash:

  • thing-update/
  • thing-update/subdomain1/
  • thing-update/subdomain1/subdomain2/

Hence, if using this type of client you must subscribe to two topics in order to receive all intended messages.

For root:

  • thing-update/
  • thing-update/#

For subdomain1:

  • thing-update/subdomain1/
  • thing-update/subdomain1/#