Using the Thing API

The Thing API describes how things can communicate with a Managed IoT Cloud (MIC) instance using X.509 certificates.

Connecting a thing to a MIC instance can be done using any programming language, and to make it even easier, you can use our Device Application Platform that will handle everything for you.

If you just want to get started, though, you can follow this guide to connect to the Thing API using Node.js. This is a perfect solution if you want to connect a Raspberry Pi (or another hardware platform that can run Node.js). It can also be run on you own machine if you just want to play around.

Preparations

Before you start, you need to have access to a MIC instance. This can be through an account on demo.mic.telenorconnexion.com or through your dedicated MIC instance. You also need to have Node.js installed.

The first step is to log in to App Board, create a thing and download the certificate for it. Unpack the files into a new folder, then download the CA certificate here and save it as ca.pem in the new folder.

The code

Create a new file called package.json in the folder you unpacked your certificate to and enter the follwing code:

{
  "name": "thing-api-example",
  "version": "1.0.0",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "mqtt": "^2.8.2"
  }
}

Save it and run npm install in a terminal.

The next step is to create the actual application that will connect to the Thing API by creating a file called index.js and adding the following code:

const fs = require("fs");
const mqtt = require("mqtt");

// TODO: Change this to the name of your thing.
const thingName = "00000001";

// TODO: Change this to the hostname for the MQTT broker.
// If you have an account on demo.mic.telenorconnexion.com
// you can leave the current value.
const hostname = "a1ek3lbmx2jfb9-ats.iot.eu-west-1.amazonaws.com";

// Configure a mqtt client and use it to connect to AWS.
// TODO: Make sure that the name of the files matches yours.
const mqttClient = mqtt.connect({
  ca: fs.readFileSync("ca.pem"),
  cert: fs.readFileSync("cert.pem"),
  clientId: thingName,
  hostname: hostname,
  key: fs.readFileSync("privkey.pem"),
  port: 8883,
  protocol: "mqtts"
});

mqttClient.on("connect", () => {
  console.log("Connected to MQTT");

  // Subscribe to the delta topic to receive requests for state changes.
  mqttClient.subscribe(`$aws/things/${thingName}/shadow/update/delta`);
});

mqttClient.on("message", (topic, message) => {
  const msg = JSON.parse(Buffer.from(message, "base64").toString("ascii"));
  console.log("Got a request to change state to", msg.state);

  // When you receive a request to change the state you should do it here.
  // How you do it depends on your hardware and the API it provides but if
  // you're using a Raspberry Pi you can use a lib such as `onoff` to sync
  // the state with your GPIO.

  // If the change is successful you should communicate this back to
  // Managed Iot Cloud using the reported state and clearing desired.

  const state = {
    desired: null,
    reported: {
      counter: msg.state.counter
    }
  }

  // Add a delay just so it the different stages can be seen in App Board.
  setTimeout(() => {
    mqttClient.publish(`$aws/things/${thingName}/shadow/update`, JSON.stringify({state}));
  }, 2500);
});

var counter = 0;

// Schedule a request to update a counter every 5 seconds.
setInterval(() => {
  const state = {
    desired: { counter: ++counter }
  }

  mqttClient.publish(`$aws/things/${thingName}/shadow/update`, JSON.stringify({state}));
}, 5000);

If you read through the code, fix the TODOs and read through the other comments, you should get a pretty good idea about how it works. Now you can run it in the terminal using npm start. You should see some logs in the console, and if you go to the thing details dashboard in App Board, you will see the counter resource updating its value as new values are sent from your program.

For more information about how the Thing API works, please read the documentation.