Thing API

The Thing API describes how things can communicate with Managed IoT Cloud using X.509 certificates.

Managed IoT Cloud uses the MQTT service from the AWS IoT Platform to connect things. AWS IoT is based on MQTT version 3.1.1 with some deviations that are documented here. Communication with a thing must be protected through TLS 1.2 and the use of X.509 certificates. More information can be found here.

Note: although AWS IoT now supports a subset of the features available in the MQTT v5.0 specification, the Thing API does not actively support any MQTT 5 features offered by AWS IoT.

Managed IoT Cloud provides an endpoint to communicate with the IoT Platform: The IoT Endpoint can be found in AppBoard under Settings -> About. The IoT Endpoint uses an Amazon Trust Service (ATS) certificate to verify the communication with Managed IoT Cloud. You can find the ATS CA certificate here. Note: Managed IoT Cloud used to support an endpoint which is now deprecated, read about it here.

Connecting

The API and user interface for creating new things, certificates and policies in AWS IoT is very flexible and requires a lot of steps to get started. This process has been greatly simplified in Managed IoT Cloud using the Thing Batch API, which allows the user to create multiple things in one step using App Board or the Cloud API.

To connect your things you follow these steps:

  1. Create a batch of things with the desired size.
  2. Download the zip file containing certificates and private keys. The zip file contains a folder for each thing that was created in the batch.
  3. Configure each thing with the following information:
    • Thing name (the name of the folder in the zip file)
    • X.509 certificate (cert.pem inside the thing folder)
    • Private key (privkey.pem inside the thing folder)
    • CA certificate (can be downloaded here)
    • Hostname for the MQTT broker (provided by Telenor Connexion when signing up for Managed IoT Cloud)
  4. Use a MQTT library to connect to the broker and use the thing name as the MQTT client identifier.

Communicating with AWS

Managed IoT Cloud mostly uses the Device Shadow service in AWS IoT and its predefined topic scheme, which is documented here. The Device Shadow service payload conventions and topics are used for state updates, synchronization of state and also to get the last known state.

Example payload

To report the state of a thing you publish a message that looks like this to $aws/things/<thingname>/shadow/update. If you don’t include a timestamp, the current time will be used when saving the observation.

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

Besides the predefined payload conventions and topics, Managed IoT Cloud also adds its own payload conventions and topics that you need to know about. If you want an example of how code that connects to Managed IoT Cloud looks like you can read the getting started guide: Using the Thing API.