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:
A logged in client has the privilege to both subscribe and publish to this topic structure.
Given a thing called
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/myTestThingsubscribe only to events of the thing
thing-update/#subscribe to all events on all things under
rootand 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/myTestThingsubscribe only to events of the thing
thing-update/subdomain1/#subscribe to all events on all things under
subdomain1and on all other things on all other domains beneath
subdomain1. A user identity with the domain
rootcould still of course do a “catch all” subscription by subscribing to
Publishing to the thing-update topic is straight forward and works the same way
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:
- 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.
- 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
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:
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.
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:
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:
and a user with the domain
subdomain2 topics available to this user will be on the form
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:
While MIC will publish messages using topic names ending with a forward slash:
Hence, if using this type of client you must subscribe to two topics in order to receive all intended messages.