AWS IoT

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)

For more information regarding AWS FOTA, see the documentation for the AWS FOTA library and the nRF9160: AWS FOTA sample.

Note

The AWS IoT library and the AWS FOTA library share common steps related to AWS IoT console management.

Requirements

The nRF9160: AWS IoT sample available for the nRF9160 DK showcases the use of this library. As part of building the sample, you create a thing in AWS IoT and generate certificates for the TLS connection.

Configuration

After meeting the Requirements, complete the following configuration procedures to set up a secure MQTT connection to the AWS IoT message broker:

  • Program the certificates to the on-board modem of the nRF9160-based kit

  • Configure the required library options

  • Configure the optional library options

See the following sections for detailed information.

Note

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

Program the certificates to the on-board modem of the nRF9160-based kit

To program the certificates, complete the following steps:

  1. Download nRF Connect for Desktop.

  2. Update the modem firmware on the on-board modem of the nRF9160-based kit to the latest version by following the steps in Updating the modem firmware.

  3. Build and program the nRF9160: AT Client sample to the nRF9160-based kit as explained in Building and programming an application.

  4. Launch the LTE Link Monitor application, which is implemented as part of nRF Connect for Desktop.

  5. Click Certificate manager located at the top right corner.

  6. Copy and paste the certificates downloaded earlier from the AWS IoT console into the respective entries (CA certificate, Client certificate, Private key).

  7. Select a desired security tag and click on Update certificates.

Note

The default security tag set by the Certificate manager 16842753 is reserved for communications with nRF Cloud.

Configure the required library options

Complete the following steps:

  1. Set the following options to establish a connection to the AWS IoT message broker:

  2. Complete the following steps to set the required library options:

    1. In the AWS IoT console, navigate to IoT core > Settings.

    2. Find the Endpoint address and set CONFIG_AWS_IOT_BROKER_HOST_NAME to this address string.

    3. Set the option CONFIG_AWS_IOT_CLIENT_ID_STATIC to the name of the thing created earlier in the process.

    4. Set the security tag configuration CONFIG_AWS_IOT_SEC_TAG to the security tag, chosen while you Program the certificates to the on-board modem of the nRF9160-based kit.

Configure the optional library options

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

To subscribe to non-AWS specific topics, complete the following steps:

The AWS IoT library also supports passing in the client ID at run time. To enable this feature, set the client_id entry in the aws_iot_config structure that is passed in the aws_iot_init() function when initializing the library, and set the CONFIG_AWS_IOT_CLIENT_ID_APP Kconfig option.

Note

If you are using a longer device ID that is either set by the option CONFIG_AWS_IOT_CLIENT_ID_STATIC or passed in during initialization, it might be required to increase the value of the option CONFIG_AWS_IOT_CLIENT_ID_MAX_LEN for proper initialization of the library.

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 message 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 a number of reasons related to external network. Implement a reconnection 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_READY event to signify that the library is ready to be used.

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.

Param evt

[in] The event and any associated parameters.

Enums

enum aws_iot_shadow_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_NONE

Unused default value.

enumerator AWS_IOT_SHADOW_TOPIC_GET

This topic type corresponds to $aws/things/<thing-name>/shadow/get, publishing an empty message to this topic requests the device shadow document.

enumerator AWS_IOT_SHADOW_TOPIC_UPDATE

This topic type corresponds to $aws/things/<thing-name>/shadow/update, publishing data to this topic updates the device shadow document.

enumerator AWS_IOT_SHADOW_TOPIC_DELETE

This topic type corresponds to $aws/things/<thing-name>/shadow/delete, publishing an empty message to this topic deletes the device Shadow document.

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_PUBACK

Acknowledgment for data sent to AWS IoT.

enumerator AWS_IOT_EVT_PINGRESP

Acknowledgment for pings sent to AWS IoT.

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_FOTA_ERROR

FOTA error. Used to propagate FOTA-related errors to the application. This is to distinguish between AWS_IOT irrecoverable errors and FOTA errors, so they can be handled differently.

enumerator AWS_IOT_EVT_ERROR

AWS IoT library irrecoverable error.

Functions

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

Initialize the module.

Note

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

Parameters
  • config[in] Pointer to struct containing connection parameters.

  • event_handler[in] Pointer to event handler to receive AWS IoT module events.

Returns

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

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.

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

Returns

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

int aws_iot_disconnect(void)

Disconnect from the AWS IoT broker.

Returns

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.

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

Returns

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

int aws_iot_input(void)

Get data from AWS IoT broker.

Returns

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.

Returns

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.

Parameters
  • topic_list[in] Pointer to list of topics.

  • list_count[in] Number of entries in the list.

Returns

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

struct aws_iot_topic_data
#include <aws_iot.h>

AWS IoT topic data.

Public Members

enum aws_iot_shadow_topic_type type

Optional: type of shadow topic that will be published to. When publishing to a shadow topic this can be set instead of the application specific topic below.

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.

uint16_t message_id

Message id, used to match acknowledgments.

uint8_t dup_flag

Duplicate flag. 1 indicates the message is a retransmission, Usually triggered by missing publication acknowledgment.

uint8_t retain_flag

Retain flag. 1 indicates to AWS IoT that the message should be stored persistently.

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.