AWS IoT¶

Setting up a connection to AWS IoT
- Programming the certificates to the on-board modem of the nRF9160 based board
- Configuring library options
Initializing
Connecting
Polling on MQTT socket
Configuration
API documentation

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

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

Note

For more information regarding AWS FOTA, see the documentation on AWS FOTA library and nRF9160: AWS FOTA sample. This library and the AWS FOTA library share common steps related to AWS IoT console management.

Setting up a connection to AWS IoT ¶

Setting up a secure MQTTS connection to the AWS IoT message broker consists of the following steps:

Creating a Thing
Generating a CA certificate.
Programming the certificates to the on-board modem of the nRF9160 based board.
Configuring the library options.

For more information on creating a thing in AWS IoT and generating the certificate, see Creating a thing in AWS IoT.

Note

The default name used for the thing by the AWS IoT library is my-thing.

Programming the certificates to the on-board modem of the nRF9160 based board ¶

Download nRF Connect for Desktop
Update the modem firmware on the on-board modem of the nRF9160 based board to the latest version by following the steps in Updating the nRF9160 DK cellular modem.
Build and program the nRF9160: AT Client sample to the nRF9160 based board as explained in Building and programming a sample application.
Launch the LTE Link Monitor application, which is implemented as part of nRF Connect for Desktop.
Click Certificate manager located at the top right corner.
Copy and paste the certificates, downloaded earlier from AWS IoT, into the respective entries (CA certificate, Client certificate, Private key).
Select a desired security tag and click Update certificates.

Note

The default security tag 16842753 is reserved for the nRF Cloud.

Configuring library options ¶

To configure the library options, complete the following steps:

In the AWS IoT console, navigate to IoT core -> Manage -> things and click on the entry for the thing, created during the steps of Creating a thing in AWS IoT.
Navigate to interact, find Rest API Endpoint and set the configurable option CONFIG_AWS_IOT_BROKER_HOST_NAME to this address.
Set the option CONFIG_AWS_IOT_CLIENT_ID_STATIC to the name of the thing created during the aforementioned steps.
Set the security tag configuration CONFIG_AWS_IOT_SEC_TAG to the security tag, chosen while Programming the certificates to the on-board modem of the nRF9160 based board.

Initializing ¶

The module is initialized by calling the aws_iot_init() function. If this API fails, the application must not use any APIs of the module.

Connecting ¶

Note

The API requires that a configuration structure aws_iot_config is declared in the application and passed into the aws_iot_init() and aws_iot_connect() functions. This exposes the application to the MQTT socket used for the connection, which is polled on, in the application. It also enables the application to pass in a client id (thingname) at runtime.

After initialization, the aws_iot_connect() function must be called, to connect to the AWS IoT broker. If the API fails, the application must retry the connection. During an attempt to connect to the AWS Iot broker, the library tries to establish a connection using a TLS handshake. This can take some time, usually in the span of seconds. For the duration of the TLS handshake, the API blocks.

After a successful connection, the API subscribes to AWS IoT Shadow topics and application specific topics, depending on the configuration of the library.

Polling on MQTT socket ¶

After a successful return of aws_iot_connect() function, the MQTT socket must be polled on, in addition to the periodic calls to aws_iot_ping() (to keep the connection to the AWS IoT broker alive) and aws_iot_input() (to get the data from the AWS IoT broker).

The code section below demonstrates how socket polling can be done in the main application after the aws_iot_init() function has been called. Connection polling can also be enabled in the AWS IoT backend by setting the configurable option CONFIG_AWS_IOT_CONNECTION_POLL_THREAD. Note that if this option is enabled, you need not include the following section of code in main.c

connect:
   err = aws_iot_connect(&config);
   if (err) {
      printk("aws_iot_connect failed: %d\n", err);
   }

   struct pollfd fds[] = {
      {
         .fd = config.socket,
         .events = POLLIN
      }
   };

   while (true) {
      err = poll(fds, ARRAY_SIZE(fds),
         K_SECONDS(CONFIG_MQTT_KEEPALIVE / 3));

      if (err < 0) {
         printk("poll() returned an error: %d\n", err);
         continue;
      }

      if (err == 0) {
         aws_iot_ping();
         continue;
      }

      if ((fds[0].revents & POLLIN) == POLLIN) {
         aws_iot_input();
      }

      if ((fds[0].revents & POLLNVAL) == POLLNVAL) {
         printk("Socket error: POLLNVAL\n");
         printk("The AWS IoT socket was unexpectedly closed.\n");
         return;
      }

      if ((fds[0].revents & POLLHUP) == POLLHUP) {
         printk("Socket error: POLLHUP\n");
         printk("Connection was closed by the AWS IoT broker.\n");
         return;
      }

      if ((fds[0].revents & POLLERR) == POLLERR) {
         printk("Socket error: POLLERR\n");
         printk("AWS IoT broker connection was unexpectedly closed.\n");
         return;
      }
}

Configuration ¶

To subscribe to AWS shadow topics, set the following options:

To subscribe to non AWS specific topics, specify the number of additional topics that needs to be subscribed to, by setting the following option:

CONFIG_AWS_IOT_APP_SUBSCRIPTION_LIST_COUNT

Note

The aws_iot_subscription_topics_add() function must be called with a list containing application topics, after calling aws_iot_init() and before calling aws_iot_connect() .

To connect to the AWS IoT broker, set the following mandatory options (specified in the Configuring library options section):

To enable the application to optionally pass a client id at runtime, set the client_id entry in the aws_iot_config structure passed in the aws_iot_init() function and set the following option:

CONFIG_AWS_IOT_CLIENT_ID_APP

Note

By default, the library uses the static configurable option CONFIG_AWS_IOT_CLIENT_ID_STATIC for the client id.

Note

The AWS IoT library is compatible with the generic cloud_api library, a generic API that supports interchangeable cloud backends, statically and at runtime.

API documentation ¶

Header file: include/net/aws_iot.h

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

group aws_iot

Library to connect the device to the AWS IoT message broker.

Typedefs

typedef void (*aws_iot_evt_handler_t)(const struct aws_iot_evt *evt)¶

AWS IoT library asynchronous event handler.

Parameters

[in] evt: The event and any associated parameters.

Enums

enum aws_iot_topic_type¶

AWS IoT shadow topics, used in messages to specify which shadow topic that will be published to.

Values:

enumerator AWS_IOT_SHADOW_TOPIC_UNKNOWN¶

enumerator AWS_IOT_SHADOW_TOPIC_GET¶

enumerator AWS_IOT_SHADOW_TOPIC_UPDATE¶

enumerator AWS_IOT_SHADOW_TOPIC_DELETE¶

enum aws_disconnect_result¶

@ AWS broker disconnect results.

Values:

enumerator AWS_IOT_DISCONNECT_USER_REQUEST¶

enumerator AWS_IOT_DISCONNECT_CLOSED_BY_REMOTE¶

enumerator AWS_IOT_DISCONNECT_INVALID_REQUEST¶

enumerator AWS_IOT_DISCONNECT_MISC¶

enumerator AWS_IOT_DISCONNECT_COUNT¶

enum aws_connect_result¶

AWS broker connect results.

Values:

enumerator AWS_IOT_CONNECT_RES_SUCCESS¶

enumerator AWS_IOT_CONNECT_RES_ERR_NOT_INITD¶

enumerator AWS_IOT_CONNECT_RES_ERR_INVALID_PARAM¶

enumerator AWS_IOT_CONNECT_RES_ERR_NETWORK¶

enumerator AWS_IOT_CONNECT_RES_ERR_BACKEND¶

enumerator AWS_IOT_CONNECT_RES_ERR_MISC¶

enumerator AWS_IOT_CONNECT_RES_ERR_NO_MEM¶

enumerator AWS_IOT_CONNECT_RES_ERR_PRV_KEY¶

enumerator AWS_IOT_CONNECT_RES_ERR_CERT¶

enumerator AWS_IOT_CONNECT_RES_ERR_CERT_MISC¶

enumerator AWS_IOT_CONNECT_RES_ERR_TIMEOUT_NO_DATA¶

enumerator AWS_IOT_CONNECT_RES_ERR_ALREADY_CONNECTED¶

enum aws_iot_evt_type¶

AWS IoT notification event types, used to signal the application.

Values:

enumerator AWS_IOT_EVT_CONNECTING¶: Connecting to AWS IoT broker.

enumerator AWS_IOT_EVT_CONNECTED¶: Connected to AWS IoT broker.

enumerator AWS_IOT_EVT_READY¶: AWS IoT library has subscribed to all configured topics.

enumerator AWS_IOT_EVT_DISCONNECTED¶: Disconnected to AWS IoT broker.

enumerator AWS_IOT_EVT_DATA_RECEIVED¶: Data received from AWS message broker.

enumerator AWS_IOT_EVT_FOTA_START¶: FOTA update start.

enumerator AWS_IOT_EVT_FOTA_DONE¶: FOTA update done, request to reboot.

enumerator AWS_IOT_EVT_FOTA_ERASE_PENDING¶: FOTA erase pending.

enumerator AWS_IOT_EVT_FOTA_ERASE_DONE¶: FOTA erase done.

enumerator AWS_IOT_EVT_FOTA_DL_PROGRESS¶: FOTA progress notification.

enumerator AWS_IOT_EVT_ERROR¶: AWS IoT library error.

Functions

int aws_iot_init(const struct aws_iot_config *const config, aws_iot_evt_handler_t event_handler)¶

Initialize the module.

Warning

This API must be called exactly once, and it must return successfully.

Return

0 If successful. Otherwise, a (negative) error code is returned.

Parameters

[in] config: Pointer to struct containing connection parameters.
[in] event_handler: Pointer to event handler to receive AWS IoT module events.

int aws_iot_connect(struct aws_iot_config *const config)¶

Connect to the AWS IoT broker.

This function exposes the MQTT socket to main so that it can be polled on.

Return

0 If successful. Otherwise, a (negative) error code is returned.

Parameters

[out] config: Pointer to struct containing connection parameters, the MQTT connection socket number will be copied to the socket entry of the struct.

int aws_iot_disconnect(void)¶

Disconnect from the AWS IoT broker.

Return: 0 If successful. Otherwise, a (negative) error code is returned.

int aws_iot_send(const struct aws_iot_data *const tx_data)¶

Send data to AWS IoT broker.

Return

0 If successful. Otherwise, a (negative) error code is returned.

Parameters

[in] tx_data: Pointer to struct containing data to be transmitted to the AWS IoT broker.

int aws_iot_input(void)¶

Get data from AWS IoT broker.

Return: 0 If successful. Otherwise, a (negative) error code is returned.

int aws_iot_ping(void)¶

Ping AWS IoT broker. Must be called periodically to keep connection to broker alive.

Return: 0 If successful. Otherwise, a (negative) error code is returned.

int aws_iot_subscription_topics_add(const struct aws_iot_topic_data *const topic_list, size_t list_count)¶

Add a list of application specific topics that will be subscribed to upon connection to AWS IoT broker.

Return

0 If successful. Otherwise, a (negative) error code is returned.

Parameters

[in] topic_list: Pointer to list of topics.
[in] list_count: Number of entries in the list.

struct aws_iot_topic_data¶

#include <aws_iot.h>

AWS IoT topic data.

Public Members

enum aws_iot_topic_type type¶: Type of shadow topic that will be published to.

const char *str¶: Pointer to string of application specific topic.

size_t len¶: Length of application specific topic.

struct aws_iot_app_topic_data¶

#include <aws_iot.h>

Structure used to declare a list of application specific topics passed in by the application.

Public Members

struct mqtt_topic list[CONFIG_AWS_IOT_APP_SUBSCRIPTION_LIST_COUNT]¶: List of application specific topics.

size_t list_count¶: Number of entries in topic list.

struct aws_iot_data¶

#include <aws_iot.h>

AWS IoT transmission data.

Public Members

struct aws_iot_topic_data topic¶: Topic data is sent/received on.

char *ptr¶: Pointer to data sent/received from the AWS IoT broker.

size_t len¶: Length of data.

enum mqtt_qos qos¶: Quality of Service of the message.

struct aws_iot_evt¶

#include <aws_iot.h>

Struct with data received from AWS IoT broker.

Public Members

enum aws_iot_evt_type type¶: Type of event.

int fota_progress¶: FOTA progress in percentage.

struct aws_iot_config¶

#include <aws_iot.h>

Structure for AWS IoT broker connection parameters.

Public Members

int socket¶: Socket for AWS IoT broker connection

char *client_id¶: Client id for AWS IoT broker connection, used when CONFIG_AWS_IOT_CLIENT_ID_APP is set. If not set an internal configurable static client id is used.

size_t client_id_len¶: Length of client_id string.