Topics

Besides the topics defined by the Device Shadow service in AWS IoT, Managed IoT Cloud have its own set of topics that is used for auxiliary services to provide functionality that AWS doesn’t provide.

TCXN topic namespace

The tcxn/things/<thingName> prefix is guaranteed to be accessible by the specific thing only, much like the AWS Device Shadow topics. The following topics are available:

Backdating observations

tcxn/things/<thingName>/shadow/backdate

Under certain circumstances, for example when a device has been offline and needs to send buffered observations for that period, you want to pass the actual timestamp of the observation. There are two ways of doing this.

1. Create a normal payload, include a timestamp and send it to $aws/things/<thingName>/shadow/update.

   This works just as you’d expect. The device shadow is updated and all rules are triggered but the timestamp of the observation will be taken from the payload instead of using the current time.

2. Use tcxn/things/<thingName>/shadow/backdate instead.

   This works the same way as the $aws/things/<thingName>/shadow/update topic with the exception that the device shadow will not be updated and no rules will be triggered. This can be very useful if you want to send many observations and just want to store them in Managed IoT Cloud. These observations are not forwared to the Thing Update API.

Example payload

{
  "timestamp": 1498451590923, // <EPOCH timestamp in milliseconds>
  "state": {
    "reported": {
      "resource1": 102,
      "resource2": 232
    }
  }
}

Last Will and Testament (LWT)

tcxn/things/<thingName>/shadow/update

Last Will and Testament (LWT) is used in MQTT to notify other clients about an ungracefully disconnected client. This can be used in Managed IoT Cloud to set the correct connection_status for instance.

Currently, LWT messages sent to AWS IoT reserved topics (topics that begin with $) are ignored. Instead Managed IoT Cloud have a republish rule from tcxn/things/<thingName>/shadow/update to $aws/things/<thingName>/shadow/update. So to configure LWT you should use that topic instead.

To get started using Last Will and Testament:

1. LWT should be sent to topic tcxn/things/<thingName>/shadow/update from where it´s republished to normal update topic.
2. LWT is triggered in three cases:

• DUPLICATE_CLIENTID
  When device reconnects when broker has an active session with device, since there can only be one session per thingName/ClientID
• CONNECTION_LOST
  When device disconnects without sending an MQTT DISCONNECT message, i.e. a non graceful disconnect, an unintentional disconnect
• MQTT_KEEP_ALIVE_TIMEOUT
  When device has failed to communicate within it´s keep alive period time multiplied with 1.5.
  Notes about keep alive period time:
  • The default keep-alive interval is 1200 seconds.
  • If a client requests a keep-alive interval of zero, the default keep-alive interval is used.
  • If a client requests a keep-alive interval greater than 1200 seconds, the default keep-alive interval is used.
  • If a client requests a keep-alive interval shorter than 30 seconds but greater than zero, the server treats the client as though it requested a keep-alive interval of 30 seconds.

Example Last Will and testament message

This message will set the connection_status in the tcxn object to 0, which indicates disconnected status, see payload conventions

{
  "state":{
    "reported":{
      "tcxn":{
        "connection_status":0
      }
    }
  }
}

Invoke Service

tcxn/things/<thingName>/fn/<action>

Managed IoT Cloud provides an invoke service where things can call functions from the backend that performs a specific task and returns the response over MQTT. Responses are sent on tcxn/things/<thingName>/fn/<action>/response.

For more information about the services available see the documentation.

Public

public

All topics under this prefix are open to everybody, i.e no restrictions on either publish or subscribe.