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 and the use of X.509 certificates. More information can be found here.

Managed IoT Cloud provides two endpoints to communicate with the IoT Platform: IoT Endpoint ATS and IoT Endpoint. These two endpoints can be found in AppBoard under Settings -> About. IoT Endpoint ATS uses an Amazon Trust Service (ATS) certificate to verify the communication with Managed IoT Cloud while IoT Endpoint uses a VeriSign certificate. You can find the ATS CA certificate here and the VeriSign CA certificate here. Note: IoT Endpoint is deprecated due to a distrust of Symantec Certificate Authorities, you can read more 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 Thing Shadows service in AWS IoT and its predefined topic scheme, which is documented here. The Thing Shadows 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.