AWS IoT

The Amazon Web Services Internet-of-Things (AWS IoT) library enables applications to connect to, and exchange messages with the AWS IoT Core service. The library supports the following technologies:

TLS secured MQTT transmission protocol
Firmware-Over-The-Air (FOTA)

Setup and configuration 

To connect a device to AWS IOT Core, complete the following steps:

Setting up AWS and configuring permissions
Generating and provisioning certificates
Creating a policy
Creating a Thing
Configuring the library

Setting up AWS and configuring permissions 

The initial AWS account setup required for using AWS IoT Core is described in Set up your AWS account.

For development purposes, the AWS managed policies AWSIoTConfigAccess and AWSIoTDataAccess provide sufficient permissions to manage AWS IoT. If you want to use AWS FOTA, the AmazonS3FullAccess policy can be used to obtain access to AWS S3.

Note

These policies provide a large number of permissions to the user. Though this can be acceptable for development purposes, you should operate on a least-privilege principle whenever possible.

To complete the steps described in this document, make sure that the following prerequisites are met:

Install AWS Command Line Interface on your system and configure AWS with the aws configure command to generate the key pair. See the Authentication and access credentials page for more details on AWS configuration.
To use the nrfcredstore tool, the dependencies in the nrf/scripts/requirements-extra.txt file must be installed. Enter the following command in a terminal window to install all the dependencies in the file:
```
pip3 install -r nrf/scripts/requirements-extra.txt
```

Generating and provisioning certificates 

Things in AWS IoT are typically authenticated using device certificates. There are multiple ways to generate and register these certificates:

The device key pair and certificate are generated by AWS and downloaded onto the device.
The device generates the key pair and a Certificate Signing Request (CSR). This request is uploaded to AWS to obtain a device certificate and is used to generate a self-signed device certificate.

Note

Generating a key pair on device requires an nRF91 Series device. If you are using an nRF9160 DK, modem version v1.3.x or later is required.

Important

Program the Cellular: AT Client sample to your device before following this guide.

Complete the following steps to generate a key pair and CSR on the modem, which is then used to obtain a device certificate signed by AWS:

Obtain a list of installed keys using the following command:
```
nrfcredstore <serial port> list
```
where <serial port> is the serial port of your device.
Select a security tag that is not yet in use. This security tag must match the value set in the CONFIG_MQTT_HELPER_SEC_TAG Kconfig option.
Generate a key pair and obtain a CSR using the following command:
```
nrfcredstore <serial port> generate <sec tag> device_cert.csr.der
```
where <serial port> is the serial port of your device and <sec tag> is the previously chosen unused security tag.

Convert the CSR from DER format to PEM format using the following command:

openssl req -inform DER -in device_cert.csr.der -outform PEM -out device_cert.csr.pem

Obtain a signed certificate using the following command:

aws iot create-certificate-from-csr --certificate-signing-request file://device_cert.csr.pem --certificate-pem-outfile device_cert.pem --set-as-active --no-cli-pager --query certificateArn

Take note of the certificate ARN, as it will be required later.
Provision the certificate using the following command:
```
nrfcredstore <serial port> write <sec tag> CLIENT_CERT device_cert.pem
```
where <serial port> is the serial port of your device and <sec tag> is the previously chosen unused security tag.
Download the Amazon Root CA 1 PEM file.
Provision the certificate using the following command:
```
nrfcredstore <serial port> write <sec tag> ROOT_CA_CERT AmazonRootCA1.pem
```
where <serial port> is the serial port of your device and <sec tag> is the previously chosen unused security tag.

Warning

This option is not recommended for production scenarios, since the private key leaves the device.

Important

Program the Cellular: AT Client sample to your device before following this guide.

To obtain a key pair and certificate generated by AWS, and to provision them to the modem, complete the following steps:

Generate the key pair and certificate using the following command:

aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile device_cert.pem --public-key-outfile pub_key.pem --private-key-outfile priv_key.pem --no-cli-pager --query certificateArn

Take note of the certificate ARN, as it will be required later.
Obtain a list of installed keys using the following command:
```
nrfcredstore <serial port> list
```
where <serial port> corresponds to the serial port of your device.
Select a security tag that is not yet in use. This security tag must match the value set in CONFIG_MQTT_HELPER_SEC_TAG Kconfig option.
Provision the client certificate using the following command:
```
nrfcredstore <serial port> write <sec tag> CLIENT_CERT device_cert.pem
```
where <serial port> is the serial port of your device and <sec tag> is the previously chosen unused security tag.
Provision the client key using the following command:
```
nrfcredstore <serial port> write <sec tag> CLIENT_KEY priv_key.pem
```
where <serial port> is the serial port of your device and <sec tag> is the previously chosen unused security tag.
Download the Amazon Root CA 1 PEM file.
Provision the certificate using the following command:
```
nrfcredstore <serial port> write <sec tag> ROOT_CA_CERT AmazonRootCA1.pem
```
where <serial port> is the serial port of your device and <sec tag> is the previously chosen unused security tag.

To obtain a key pair and certificate generated by AWS, complete the following steps:

Generate the key pair and certificate using the following command:

aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile client-cert.pem --public-key-outfile public-key.pem --private-key-outfile private-key.pem --no-cli-pager --query certificateArn

Take note of the certificate ARN, as it will be required later.
Download the Amazon Root CA 1 PEM file as ca-cert.pem. If the file is saved as .txt file, you need to rename it back to a .pem file.
Place the PEM files into the folder path specified by the CONFIG_MQTT_HELPER_CERTIFICATES_FOLDER option, default is <app_src_dir>/certs/. Ensure that the CONFIG_MQTT_HELPER_PROVISION_CERTIFICATES option is set.

Note

It is not necessary to set the CONFIG_MQTT_HELPER_CERTIFICATES_FOLDER Kconfig option if the file is placed in a folder named certs under the application source directory.
If the files are placed correctly, the MQTT helper library finds the certificates and provisions them to the Mbed TLS stack when connecting to AWS IoT.

Creating a policy 

AWS IoT Core policies determine which permissions a Thing has and are required to connect to the AWS IoT data plane. To create a policy, complete these steps:

Create a file policy.json with the following content:
```
{
   "Version": "2012-10-17",
   "Statement": [
       {
         "Effect": "Allow",
         "Action": "iot:*",
         "Resource": "*"
       }
    ]
 }
```
Note

This policy example is only intended for development environments. Make sure to update this to a more restrictive policy before you go into production. For more information, refer to the example policies listed in AWS IoT Core policy examples and Security best practices in AWS IoT Core.

Create the policy using the following command:

aws iot create-policy --policy-name my-policy --policy-document file://policy.json

Attach the policy to the previously registered certificate using the following command:
```
aws iot attach-policy --target <certificate arn> --policy-name my-policy
```
where <certificate arn> is the ARN of the previously generated device certificate.

Creating a Thing 

Create a Thing in AWS IoT core by completing the following steps:

Create a Thing using the following command:
```
aws iot create-thing --thing-name <thing name>
```
where <thing name> is the desired name for the Thing, for example, my-thing.
Attach the certificate to the Thing using the following command:
```
aws iot attach-thing-principal --principal <certificate arn> --thing-name <thing name>
```
where <certificate arn> is the ARN of the previously generated device certificate and <thing name> is the previously chosen name of the Thing.

Configuring the library 

Complete the following steps to set the required library options:

Obtain the AWS IoT broker endpoint using the following command:
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
Set the CONFIG_AWS_IOT_BROKER_HOST_NAME Kconfig option to the obtained endpoint value. For information on how to set this value at runtime, refer to Setting the AWS host name at runtime.
Set the CONFIG_AWS_IOT_CLIENT_ID_STATIC Kconfig option to the name of the Thing created earlier. For information on how to set this value at runtime, refer to Setting client ID at run-time.
Set the CONFIG_MQTT_HELPER_SEC_TAG to the security tag for which the key and certificate were provisioned earlier.

Optional library options

To subscribe to the various AWS IoT Device Shadow Topics , set the following options:

Other options:

MQTT helper library specific options:

Note

If you are using a longer client ID that is either set by the option CONFIG_AWS_IOT_CLIENT_ID_STATIC or passed in during connect, it might be required to increase the value of the option CONFIG_AWS_IOT_CLIENT_ID_MAX_LEN to reserve enough space for the client ID string.

Usage 

The AWS IoT sample showcases the use of this library and can be used to verify a connection to AWS IoT. To configure and run the sample, complete the steps described in Setup and Building and running.

Initializing the library 

The library is initialized by calling the aws_iot_init() function. If this API call fails, the application must not make any other API calls to the library.

Connecting to the AWS IoT MQTT broker 

After the initialization, the aws_iot_connect() function must be called to connect to the AWS IoT broker. If this API call fails, the application must retry the connection by calling aws_iot_connect() again.

Note

The connection attempt can fail due to several reasons related to the network. Due to this its recommended to implement a routine that tries to reconnect the device upon a disconnect.

During an attempt to connect to the AWS IoT broker, the library tries to establish a connection using a TLS handshake, which usually spans a few seconds. When the library has established a connection and subscribed to all the configured and passed-in topics, it will propagate the AWS_IOT_EVT_CONNECTED event to signify that the library is connected and ready to be used.

Subscribing to non-AWS specific topics 

To subscribe to non-AWS specific topics, pass a list containing the topics using the aws_iot_application_topics_set() function before calling the aws_iot_connect() function.

The following code example shows how to subscribe to non-AWS specific topics:

#define CUSTOM_TOPIC_1  "my-custom-topic/example"
#define CUSTOM_TOPIC_2  "my-custom-topic/example2"

static const struct mqtt_topic topic_list[] = {
        {
                .topic.utf8 = MY_CUSTOM_TOPIC_1,
                .topic.size = strlen(MY_CUSTOM_TOPIC_1),
                .qos = MQTT_QOS_1_AT_LEAST_ONCE,
        },
        {
                .topic.utf8 = MY_CUSTOM_TOPIC_2,
                .topic.size = strlen(MY_CUSTOM_TOPIC_2),
                .qos = MQTT_QOS_1_AT_LEAST_ONCE,
        }
};

err = aws_iot_application_topics_set(topic_list, ARRAY_SIZE(topic_list));
if (err) {
        LOG_ERR("aws_iot_application_topics_set, error: %d", err);
        FATAL_ERROR();
        return err;
}

Publishing to non-AWS specific topics 

To publish to a non-AWS specific topic, complete the following steps:

Populate a aws_iot_topic_data with the custom topics that you want to publish to. It is not necessary to set the topic type when populating the aws_iot_topic_data structure. This type is reserved for AWS IoT shadow topics.
Pass in the entry that corresponds to the topic that the payload is to be published to in the message structure aws_iot_data. This structure is then passed into the aws_iot_send() function.

The following code example shows how to publish to non-AWS specific topics:

#define MY_CUSTOM_TOPIC_1 "my-custom-topic/example"
#define MY_CUSTOM_TOPIC_1_IDX 0

static struct aws_iot_topic_data pub_topics[1] = {
        [MY_CUSTOM_TOPIC_1_IDX].str = MY_CUSTOM_TOPIC_1,
        [MY_CUSTOM_TOPIC_1_IDX].len = strlen(MY_CUSTOM_TOPIC_1),
};

struct aws_iot_data msg = {
        /* Pointer to payload */
        .ptr = buf,

        /* Length of payload */
        .len = len,

         /* Message ID , if not set it will be provided by the AWS IoT library */
        .message_id = id,

        /* Quality of Service level */
        .qos = MQTT_QOS_0_AT_MOST_ONCE,

        /* "my-custom-topic/example" */
        .topic = pub_topics[MY_CUSTOM_TOPIC_1_IDX]
};

err = aws_iot_send(&msg);
if (err) {
        LOG_ERR("aws_iot_send, error: %d", err);
        return err;
}

Setting client ID at run-time 

The library supports passing in the client ID at runtime. To use this feature, set the client_id entry in the aws_iot_config structure that is passed in the aws_iot_connect() function when connecting. The client_id entry must be a null-terminated string.

Setting the AWS host name at runtime 

The library supports passing in the endpoint URL at runtime. To use this feature, set the host_name entry in the aws_iot_config structure that is passed in the aws_iot_connect() function when connecting. The client_id entry must be a null-terminated string.

Testing and debugging 

For general information about testing and debugging, see Testing and optimization.

Topic monitoring

To observe incoming messages, navigate to the AWS IoT console and click MQTT test client. Subscribe to the topic that you want to monitor, or use the wild card token # to monitor all topics.

Troubleshooting 

For issues related to the library and nRF Connect SDK in general, refer to Known issues.

If you are experiencing unexpected disconnects from AWS IoT, try decreasing the value of the CONFIG_MQTT_KEEPALIVE option or publishing data more frequently. AWS IoT specifies a maximum allowed keepalive of 1200 seconds (20 minutes), however in certain LTE networks, the Network Address Translation (NAT) timeout can be considerably lower. As a recommendation to prevent the likelihood of unexpected disconnects, set the option CONFIG_MQTT_KEEPALIVE to the highest value of the network NAT and maximum allowed MQTT keepalive.
If publishing larger payloads fails, you might need to increase the value of the CONFIG_MQTT_HELPER_RX_TX_BUFFER_SIZE option.
For nRF91 Series devices, the size of incoming messages cannot exceed approximately 2 kB. This is due to a limitation of the modem’s internal TLS buffers. Messages that exceed this limitation will be dropped.

AWS FOTA 

The library supports FOTA using the AWS FOTA library. This library can be enabled by setting the CONFIG_AWS_FOTA Kconfig option. To create a FOTA job, refer to the AWS FOTA documentation.

API documentation 

Header file: include/net/aws_iot.h

Source files: subsys/net/lib/aws_iot/src/

AWS IoT library