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.
Setting up a connection to AWS IoT¶
Setting up a secure MQTT connection to the AWS IoT message broker consists of the following steps:
Creating a thing in AWS IoT and generating certificates for the TLS connection.
Programming the certificates to the on-board modem of the nRF9160-based kit.
Configuring the required library options.
Configuring the optional library options.
Note
The default thing name used in the AWS IoT library is my-thing
.
Programming the certificates to the on-board modem of the nRF9160-based kit¶
To program the certificates, complete the following steps:
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 nRF9160 DK cellular modem.
Build and program the nRF9160: AT Client sample to the nRF9160-based kit 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 the AWS IoT console into the respective entries (
CA certificate
,Client certificate
,Private key
).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.
Configuring the required library options¶
To establish a connection to the AWS IoT message broker, set the following options:
To configure the required 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 the
Rest API Endpoint
and set the configurable optionCONFIG_AWS_IOT_BROKER_HOST_NAME
to this address string.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 kit.
Configuring 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:
Specify the number of additional topics that needs to be subscribed to, by setting the
CONFIG_AWS_IOT_APP_SUBSCRIPTION_LIST_COUNT
optionPass a list containing application specific topics in the
aws_iot_subscription_topics_add()
function, after theaws_iot_init()
function call and before theaws_iot_connect()
function call
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 following 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.
Note
The AWS IoT library is compatible with the Cloud API, a generic API that enables multiple cloud backends to be interchanged, statically and at run time.
To enable the use of the cloud, API set the configurable option CONFIG_CLOUD_API
, in addition to the other selected library options.
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 that the connection attempt can fail due to any number of external network related reasons.
So, it is recommended to 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¶
include/net/aws_iot.h
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
evt – [in] 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
¶ Unknown device shadow topic.
-
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.
-
enumerator
-
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
¶
-
enumerator
-
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
¶
-
enumerator
-
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_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.
-
enumerator
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.
- 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_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.
-
enum aws_iot_topic_type
-
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 mqtt_topic
-
struct
aws_iot_data
¶ - #include <aws_iot.h>
AWS IoT transmission data.
-
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.
-
enum aws_iot_evt_type
-
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.
-
int
-
typedef void (*