Integration: AWS IoT

Use IoTIFY's network simulator to connect virtual devices to the Amazon Web Services IoT platform.

Introduction

AWS IoT is Amazon’s offering in the market of IoT cloud platforms. It allows IoT devices to exchange data with the cloud using either HTTP, WebSocket or MQTT as communication protocol. This guide describes how to use IoTIFY network simulator to create virtual devices that communicate with AWS IoT.

1. Sign up for AWS IoT and log in to your AWS account

New users of Amazon Web Services can set up an account at https://portal.aws.amazon.com/gp/aws/developer/registration/index.html. After logging in, the user is directed to their account’s AWS console, where all Amazon web services can be managed:

2. Register a device with AWS IoT

Any (physical or virtual) device that wants to connect with the AWS IoT cloud must first be registered in AWS IoT.

From your account’s AWS console, click on the “AWS IoT” entry under the “Internet of Things” section of the list of AWS services; you will be taken to the AWS IoT dashboard:

On the left menu, click on the Registry entry. The registry contains two types of elements: things and types. A “thing” is the representation of a device in AWS IoT; a type is a set of attributes that can be associated to one or more things. Types make it easier to register many devices with a common set of attributes; for example, a temperature and humidity sensor can be represented in the AWS IoT registry as a type with two attributes (temperature and humidity), and then one or more sensors of this type can be registered as things.

In this guide we are going to create a virtual sensor consisting of an accelerometer that measures acceleration values along its 3 spatial axes. First, we create a type that contains the attributes that will hold the acceleration values. From the left menu of the AWS IoT screen, click on the “Types” entry, and then click on the “Create” button at the top right corner. In the type creation screen, give a name to this type (in our example, “IoTIFY_accelerometer”):

Next, we are going to add the 3 attibutes representing the acceleration along the x, y and z axes: for each attribute, click on the “Add another” button and give a name to the attribute:

Finally, click on “Create thing type”. A summary of the type characteristcs is then shown in the next screen:

Click on the left arrow button at the top left of the screen to return to the types screen: your newly defined type will be shown in that screen.

Now we can create a “thing” in the AWS IoT registry and associate it to the accelerometer type. Click on the “Things” entry in the left menu, then click on the “Create” button at the top right. The thing registration screen will be shown; in this screen, give a name to the thing (for example, “my_accelerometer”), then click on “Show optional configuration”:

In the thing type section, select the previously created type; in this way, the attributes defined for the type will be listed as searchable thing attibutes:

Finally, click on the “Create thing” button at the bottom of the screen; the thing details will then be shown on the next screen:

Since any device connecting to AWS IoT needs to be authenticated, now we are going to create security credentials to be used by our device. From the thing details screen, click on “Security” on the left menu, then click on “Create certificate”. A new certificate will be created, and the next screen will provide links to download the certificate and its associated public and private keys, as well as the root CA certificate:

In order to be able to connect our virtual device to AWS IoT, we need to download the certificate, the private key and the root CA certificate; click on the download link for each of these items and save the downloaded files.
The newly created certifcate needs to be activated in order to be accepted by the AWS IoT cloud upon device connection: click on the “Activate” button to activate the certificate.
Finally, click on “Done” at the bottom right of the screen.

A certificate ensures that any device connecting to AWS IoT is properly authenticated. In order to grant access privileges to authenticated devices, AWS IoT uses the concept of “policies”: a policy determines what a device can and cannot do when interacting with the cloud. Policies are attached to certificates, so that when an authenticated device connects to the cloud, it is granted all the access privileges specified in the policies attached to the certificate through which the device has been authenticated.

AWS IoT policies can be managed from within the AWS IoT console by clicking on the “Policies” menu entry under the Security section in the left menu; to create a new policy, click on the “Create” button at the top right of the screen:

In the policy creation screen, assign a name to the policy (for example, “IoTIFY”), then specify a policy statement. Policy statements describe with a formal syntax the content of a policy, i.e. what operations are allowed or denied by the policy. AWS IoT offers a fine degree of control over what a device is allowed to do, for example a policy can allow a given device to subscribe to an MQTT topic and deny publishing operations on that topic, or vice versa. In this simple example, we are going to grant our device the right to do any operation on AWS IoT; to do so, insert the string “iot:*” in the statement action field, and the string “*” in the Resource ARN field, then select the Allow check box:

To create the policy, click on “Create” at the bottom right.

Finally, we need to associate our policy to the certificate. In the AWS IoT console, open the certificates screen by selecting the relevant entry in the left menu, then click on the icon representing the previously created certificate:

Click on the Actions menu at the top left and then on “Attach policy”; in the dialog window that appears, select the previously created policy and click on “Attach”; after that, the attached policy will be shown when selecting the Policies entry in the left menu:

Now that our device and its associated identity and policy have been set up, the AWS IoT cloud is ready to interact with the device. In order to be able to connect to AWS IoT we need another piece of information, that is the URL of the MQTT broker that will be listening for connections from our device; this information can be found by clicking on the “Interact” menu entry in the thing screen:

The URL of the MQTT broker is the same as the REST API endpoint shown under the HTTPS section.

In AWS IoT, each registered device has its “thing shadow”, which is an abstraction used to represent the state of the device. This abstraction allows operating devices even if their connection with the cloud is not always on: when a device is disconnected, its last known state can be retrieved from the cloud by looking at the shadow; conversely, when a command needs to be sent to a disconnected device, it is sent to its shadow in the cloud, then at the next reconnection of the device the command stored in the shadow is delivered to the device.
In our example where the device is an acceleration sensor, the shadow will contain the last known acceleration values at any given time. Each message sent by the device to the cloud will then update the state of the shadow.

In the AWS IoT screen containing details about a registered device, the MQTT topic to which the device should send it status updates can be found under the MQTT section of the above figure: in our example, it is “$aws/things/my_accelerometer/shadow/update”.

3. Set up a template in IoTIFY network simulator

Now that we have registered a device in AWS iOT and know all the details needed to connect to the cloud, we can create a virtual device in IoTIFY network simulator and let this device send its data to AWS IoT.

In the templates section of the web interface of IoTIFY network simulator, click on “Create a new template”. In the template definition screen, give a unique name to the template and select MQTT as network connection type. Then, in the MQTT section select MQTTS as protocol, and insert the URL of the MQTT broker in the “Endpoint URL” field; the URL value can be found in the AWS IoT web interface as detailed in the previous section.

Then, expand the “Provide Credentials” section, and insert the private key, certificate, and CA certificate in the corresponding fields: this data can be read in the files previously downloaded from the AWS IoT console.

Finally, in the “Specify Message Contents” section insert the MQTT topic previously retrieved from the AWS IoT console, insert the following code:

{
var mystate = {
reported: {
x: chance.floating({min: -10, max:10 }),
y: chance.floating({min: -8, max:8 }),
z: chance.floating({min: 0, max:20 })
}
};
return JSON.stringify({ state: mystate}, null, 2);
}

The above function returns a JSON object named “state”, which contains an inner object named “reported”, which contains values for the attributes defined in our accelerometer device. To generate these values, we can use for example methods from the Chance.js library; a possible template is shown below:

Click on SAVE to save the template.

4. Send data to AWS IoT

We can now use the template created in the previous section to start a simulation. In the simulation parameters screen, adjust the settings to your preferences, then click on “Start Simulation”:

The simulated accelerometer sensor will start generating acceleration values and sending them to AWS IoT as MQTT messages; these messages can be viewed in the AWS IoT console by selecting the corresponding device in the things registry and then selecting the Activity item in the left menu:

As mentioned before, each message sent to the cloud updates the status of the thing shadow; the current status, corresponding to the last message received from the device, can be seen by selecting the Shadow menu entry:

This concludes our guide for integrating IoTIFY network simulator with AWS IoT; using different device types and different simulation templates it is possible to simulate many types of IoT deployments and manage them from the AWS IoT console.