Functions
fsp_err_t	RM_AWSIOT_W_Open (awsiot_w_ctrl_t const p_ctrl, rm_awsiot_w_app_cfg_t const const p_cfg)

fsp_err_t	RM_AWSIOT_W_Close (awsiot_w_ctrl_t *const p_ctrl)

Detailed Description

Application stack for the AWSIOT_W on RAFW. This module implements the AWSIOT_W Application (rm_awsiot_w).

Overview

The AWSIOT_W platform reference application provides a demonstration of an use case such as a door lock using the AWSIOT_W services provided by Amazon. AWSIOT_W is implemented using the MQTT protocol and utilizes the platform provided by Amazon. MQTT (Message Queue Telemetry Transport) is an ISO standard (ISO/IEC PRF 20922) publish-subscribe-based messaging protocol. It works on top of the TCP/IP protocol. The publisher sends (PUBLISH) messages to the subscriber through the broker. The subscriber needs to keep the connection with the broker by TCP session while the publisher can disconnect the session with the broker after sending a message. Once the broker receives a message with a specific topic the message is sent to subscribers that already registered with the topic. A subscriber can register with more than one topic. There can be many or no subscribers which registered with a specific topic. The exchange of MQTT messages supports QoS (Quality of Service). Various applications can be implemented for the AWSIOT_W platform by following this reference applicaiton.

Features

The MQTT Port module has the following key features:

Publish message
Subscribe message
QoS

Configuration

Build Time Configurations for rm_awsiot_w

The following build time configurations are defined in fsp_cfg/rm_awsiot_w_cfg.h:

Configuration	Options	Default	Description
Sleep3(DPM) Support	Enabled Disabled	Enabled	Enable when using the Sleep3(DPM) Mode.
AWSIOT_W MQTT Receive No Connected Maximum Timeout (ms)	Timeout must be an integer greater than or equal to 2000 and less than 65535	2000	Timeout for the AWSIOT_W MQTT Receive function to check the buffer for incoming MQTT messages in milliseconds when not being connected.
AWSIOT_W MQTT Receive Connected Maximum Timeout (ms)	Timeout must be an integer greater than or equal to 120 and less than 65535	120	Timeout for the AWSIOT_W MQTT Receive function to check the buffer for incoming MQTT messages in milliseconds when being connected.
AWSIOT_W MQTT Receive Sleep Maximum Timeout (ms)	Timeout must be an integer greater than or equal to 20 and less than 65535	20	Timeout for the AWSIOT_W MQTT Receive function to check the buffer for incoming MQTT messages in milliseconds when going to sleep.
AWSIOT_W Clean Session	Enabled Disabled	Enabled	Enable when using the clean session.
AWSIOT_W Keep Alive (s)	Must be an integer greater than 10 and less than 65535	1800	MQTT ping period to check if connection is still active.
AWSIOT_W Thing Name	Manual Entry	RRQ61x00	Thing Name for AWSIOT_W Connection
AWSIOT_W Host Name	Manual Entry	a1kzdt4nun8bnh-ats.iot.ap-northeast-2.amazonaws.com	Host Name for AWSIOT_W Connection
AWSIOT_W ROOT CA Certificate	Manual Entry	-----BEGIN CERTIFICATE-----/jAo54vB4ikPmljZbyjANBgkqhkiG9w0BAQsF+6zf1tRn4SWiw3te5djgdYZ6k/oI2peVKVuRF4fn9tBb6dNqcmzU5L/qw+a/sRxmPUDgH3KKHOVj4utWp+UhnMJbulHheb4mjUcAwhmahRWa6/0egwLX0tdHA114gk957EWW67c4cX8jJGKLhD+rcdqsq08p8kDi1L/6pUCyziKrlA4b9v7LWIbxcceVOF34GfID5yHI9Y/QCB/IIDEgEw+OyQm/BAUwAwEB/zAOBgNVHQ8BAf8EBAMC/G/wkjUu0yKGX9rbxenDI/msv0tadQ1wUs+gDS63pYaACbvXy8MWy7Vu33PqUXHeeE6V/Uq2V8viTO96LXFvKWlJbYK8U90vv/ufQJVtMVT8QtPHRh8jrdkPSHCa2XV4cdFyQzR1bldZwgJcJmApzyMZFo6IQ6XU+yMRQ+hDKXJioaldXgjUkK642M4UwtBV8ob2xJNDd2ZhwLnoQdeXeGADbkpy -----END CERTIFICATE-----	AWS root CA Certificate
AWSIOT_W Client Certificate	Manual Entry	-----BEGIN CERTIFICATE-----/Qq2E9ZleQWN2Gk/iPw2GMA0GCSqGSIb3DQEB/AbN7xxXgAslyB14/MPUjrpgPSnrbHcLwhOpKILoHiLO6CTqfXv/pxcXyh0UCHpp1PF63m0vmYYuA+m09GLkqdxWGz2wgKokSa8pMO/otTA+uh8y/7q5fuASGywZR5WeutH8yjw4ui5Il+66S2yUifsCDrNgsmfTIZdta4cV+tv/dFnNzRT3DLm8FJH7RD60jHiYoZQFNHWuSH98cAg3RSyuRnHx9mmD+O8jKyZ6D/7NAgMBAAGjYDBeMB8GA1UdIwQYMBaAFL6HYMtZyM54cz3RAAzyR1zF7+1TMB0G/TBBMP6Cz/qU3ljAMBgNVHRMBAf8EAjAAMA4GA1Ud/wQEAwIHgDANBgkqhkiG9w0BAQsFAAOCAQEAp9tbJ4GOFoX11trWKc/HTfdb+2ZEmxDA0bN+WDdCppQHocYoNt8h6X+Mh0h2hnfB2hPQwDX+2B4XgPZutim++8J7DHQbfHAGZwiAFN/Owx0+iO2Be7w30+CO4wes8RH5pNIOK2QrKgr9NJkA== -----END CERTIFICATE-----	AWS client certificate
AWSIOT_W Client Private key	Manual Entry	-----BEGIN RSA PRIVATE KEY-----/6cXF8odFAh6adTxet5tL5mGLgLnkYFtt7Iyj10T8hpxT1Yxp7TYZRblw+6uX7gEhssGUeVnrrR/Mo8+1xxFbhTCKxOTdp317utgl+BjppqBeIh9MOhSDZldH9LEHC0u9/rbwkf3RZzc0U9wy5vBSR+0Q+tIx4mKGUB/fHAIN0UsrkZx8fZpg/jvIysmeg6/+zQIDAQABAoIBADfE6fy/4xFj2fZF/ZpSlg0xnG8pYz0BP/5bhfSg/J32rjmWD+rmBB7xWFY1FsRiGBSL/07H9c0Tz+TksWLy6pf981zbZQxIdY5Bfg+YGtmtXJ+8SQi3FSRwDdbpyoLokUf1YaH/fAxF5F1/mD0tgUSkUptRXu879mpA5+uYD+Q/29Kq+tUNtmBdzY8gcmWr2h859x3R6wpybbYJt5KWK4NT/7yOGf8y2QJLfjW08qBAATnYZuZySrV7rNK5kxenGueZl2t52NCa/7n+cbkQbkSBmcJph8x0949c/HJ2U6xcMmwR8G4Jnlwe+w3expwKnNlpNXaZ+mm2BeXvyPJCgN/BMkDhU1xyDQBscCYrD9q41IU318CTmH6iExoUwv6NNuyOsFd+MeHpgAdfvGf1HNd77ZOgZdQI6k0w9HuMnctnO2U58z+1P0VJL6sJaP0actt58g2U4C4m73A+lEZbxVCFZNyetXQIsjTMKJ8g5PesyR8+Q/Af4fBldkcZtHIxK9uqkCgYAaqpmQwac7Bx4Xdb9NSm/wI3MUFmdg7ZM2gqJ1/9Oa4ghAiZeplYYz0sNZVWjrF68/FVNypzpfjxj5X0X+4S5UNwxGHw4cZJwAvOkkeApV3WlBSZFbbGzIxrVy79O+2HZZVSXtgsCS/fzsFjMWYpeNRX3+9wtFfGCfxoygGW0JvOyY/m7JdyOcWdbf54nhzcEqjRv1DhCA== -----END RSA PRIVATE KEY-----	AWS client's private key
AWSIOT_W MQTT Port	Must be an integer greater than 0 and less than 65535	443	AWSIOT_W HUB endpoint port
SSL MAX Content Length	Must be an integer greater than 0 and less than 65535	8192	Incoming and outgoing TLS buffer size
AWSIOT_W OTA RTOS NAME	Manual Entry	rm_awsiot_w_wifi_test_app.img	RTOS Name for AWSIOT_W OTA

Configurations for Networking > AWS IoT port layer (rm_awsiot_w)

This module can be added to the Stacks tab via New Stack > Networking > AWS IoT port layer (rm_awsiot_w).

Configuration	Options	Default	Description
General
Name	Name must be a valid C symbol	g_awsiot_w0	Module name

Clock Configuration

This module has no required clock configurations.

Pin Configuration

This module does not use I/O pins.

Usage Notes

Refer to WIFI (rm_wifi).

This module is not a standalone module - ensure that the WiFi module APIs are invoked first to configure the RAFW module and connect to an Access Point before using the MQTT module where the default buffer size for incoming TLS is 8KB and outgoing TLS is 8KB.
When the user intends to use secure TLS in their application, they need to provide certificates (root certificate authority, client certificate, and private key) in a header file
The user must provide certificate macro names in the FSP Configurator properties, as well as the name of the header file (to link the module, certificates, and header together)
If the user provides these credentials in the Configurator, they must create a new header file in their /src/ folder with the same name as they provided in the Configurator properties. When the code is generated, a build error will occur if the header file is not created

Limitations

Refer to WIFI (rm_wifi).

The thing name must be set for AWSIOT_W connection.
For publish/subscribe topics, a separate QoS level cannot be set per topic - only one QoS level can be set which applies to all messages
Currently the module only supports secure MQTT/TLS with certificates (root CA, client certificate, and private key).

Examples

Basic Example

This is a basic example of minimal use of the AWSIOT_W application.

void rm_awsiot_w_example(void) { 
    rm_wifi_open(&g_wifi_cfg);
    vTaskDelay(portCONVERT_MS_2_TICKS(200)); 
    RM_AWSIOT_W_Open(&g_rm_awsiot_w_app_ctrl, &g_rm_awsiot_w_app_cfg);
    while (1)
    {
        vTaskDelay(portCONVERT_MS_2_TICKS(100)); 
    }
}

Data Structures
struct	rm_awsiot_w_app_instance_ctrl_t

Data Structure Documentation

◆ rm_awsiot_w_app_instance_ctrl_t

struct rm_awsiot_w_app_instance_ctrl_t

AWSIOT_W control structure. DO NOT INITIALIZE.

Data Fields
rm_awsiot_w_app_cfg_t const *	p_cfg	Pointer to initial configurations.
uint32_t	open	Indicates whether the open() API has been successfully called.
void const *	p_context	Placeholder for user data.

Function Documentation

◆ RM_AWSIOT_W_Open()

fsp_err_t RM_AWSIOT_W_Open	(	awsiot_w_ctrl_t *const	p_ctrl,
		rm_awsiot_w_app_cfg_t const *const	p_cfg
	)

Initialize the AWSIOT_W service.

Parameters

[in]	p_ctrl	Pointer to AWSIOT_W instance control structure.
[in]	p_cfg	Pointer to AWSIOT_W configuration structure.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ALREADY_OPEN	AWSIOT_W instance is already opened.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	The p_cfg instance is NULL.
FSP_ERR_OUT_OF_MEMORY	Heap is too small or NULL to create a AWSIOT_W task.

◆ RM_AWSIOT_W_Close()

fsp_err_t RM_AWSIOT_W_Close ( awsiot_w_ctrl_t *const p_ctrl )

Close the AWSIOT_W service.