AWS IoT Device Shadow#

Introduction#

This application demonstrates how to securely connect a Silicon Labs RS911x Wi-Fi device to AWS IoT Core to send and receive data. To successfully use this application, developers should be familiar with the operation of AWS IoT Core and the AWS IoT Device Shadow Service. If you are new to AWS IoT Core, we recommend running through the AWS IoT Core Tutorial before proceeding. In the following text, 'AWS IoT Core' is referred to as 'AWS' for brevity.

AWS refer to a 'Device Shadow' as a persistent, virtual representation of a device that can be accessed even if the physical device is offline. The device state is captured in its 'shadow' and is represented as a JSON document. The physical device can send commands using the MQTT protocol to get, update and delete the state of the shadow as well as receive notifications via MQTT about changes in the state pf the shadow.

The AWS IoT Device Shadow application publishes temperature and window open/close status on the topic $aws/things/thingname/shadow/update. The room temperature and the window open/close status is available on the AWS cloud.

Additionally, the application subscribes to the shadow update topics:

  $aws/things/thingName/shadow/name/shadowName/update/accepted
  $aws/things/thingName/shadow/name/shadowName/update/rejected
  $aws/things/thingName/shadow/name/shadowName/update/delta

Overview of AWS SDK#

AWS IoT Core is a cloud platform that connects devices across AWS cloud services. AWS IoT provides an interface that allows devices to communicate securely and reliably in bi-directional ways to AWS touch-points, even when devices are offline.

The AWS IoT Device SDK allow applications to securely connect to the AWS IoT platform.

Figure: Setup Diagram for Device Shadow Example

Setting Up#

To use this application, the following hardware, software and project setup is required.

Hardware Requirements#

Windows PC with Host interface (UART / SPI/ SDIO).
Silicon Labs RS9116 Wi-Fi Evaluation Kit
Host MCU Eval Kit. This example has been tested with:
- Silicon Labs WSTK + EFR32MG21
- Silicon Labs WSTK + EFM32GG11
- STM32F411 Nucleo
Wi-Fi Access point with a connection to the internet

Figure: Setup Diagram for Device Shadow Example

Software Requirements#

Amazon AWS account
WiSeConnect SDK
Python 3 installation
Embedded Development Environment
- For STM32, use licensed Keil IDEFor Silicon Labs EFx32, use the latest version of Simplicity Studio

Cloud Setup#

This example requires your RS911x Wi-Fi device to be provisioned on AWS; you will need the device certificate and private key. For brief provisioning instructions, see AWS IoT Setup.

Project Setup#

Silicon Labs EFx32 Host. Follow the the Getting Started with EFx32 to setup the example to work with EFx32 and Simplicity Studio.
STM32F411 Host. Follow the the Getting Started with STM32 to setup the example to work with STM32 and Keil.

Configuring the Application#

The application can be configured to suit your requirements and development environment. Read through the following sections and make any changes needed.

Host Interface#

By default, the application is configured to use the SPI bus for interfacing between Host platforms(STM32F411 Nucleo / EFR32MG21) and the RS9116W EVK.
This application is also configured to use the SDIO bus for interfacing between Host platforms(EFM32GG11) and the RS9116W EVK.

Bare Metal/RTOS Support#

To select a bare metal configuration, see Selecting bare metal.

Wi-Fi & Cloud Configuration#

Configure the following parameters in rsi_aws_device_shadow.c to enable your Silicon Labs Wi-Fi device to connect to your Wi-Fi network.

#define SSID           "SILABS_AP"      // Wi-Fi Network Name
#define PSK            "1234567890"     // Wi-Fi Password
#define SECURITY_TYPE  RSI_WPA2         // Wi-Fi Security Type: RSI_OPEN / RSI_WPA / RSI_WPA2

RTOS Configuration#

The following parameters are configured if OS is used. Application task should be of low priority

#define RSI_APPLICATION_TASK_PRIORITY                   1

Driver task should have the highest priority among all threads

#define RSI_DRIVER_TASK_PRIORITY                 2

WLAN Task stack size is configured by this macro

#define RSI_APPLICATION_TASK_STACK_SIZE           512 * 4

Driver Task stack size is configured by this macro

#define RSI_DRIVER_TASK_STACK_SIZE         512 * 2

Configure AWS_IOT_MQTT_HOST in the file aws_iot_config.h to match the endpoint for your device in AWS.

#define AWS_IOT_MQTT_HOST "xxxxxxxxxxxxx-ats.iot.us-east-2.amazonaws.com"

Power Save Configuration#

Configure below parameter in rsi_wlan_config.h to enable power save mode

#define ENABLE_POWER_SAVE 1

Setting up Security Certificates#

To authenticate and securely connect with AWS, your Wi-Fi device requires a unique x.509 security certificate and private key, as well as a CA certificate which is used to verify the AWS server. Security credentials need to be converted into a C-array rather than PEM format provided by AWS; they also need to be added to your project.

The WiSeConnect SDK provides a conversion script (written in Python 3) to make the conversion straightforward. The script is provided in the SDK 'resources' directory and is called certificate_to_array.py.

To convert the device certificate and private key to C arrays, open a system command prompt and use the script as indicated in the following examples.

$> python3 certificate_to_array.py <input filename> <output arrayname>

For example:
$> python3 certificate_to_array.py d8f3a44d3f.cert.pem    aws_client_certificate
$> python3 certificate_to_array.py d8f3a44d3f.private.key aws_client_private_certificate

After running the script on the certificate and private key, two new files are created.

aws_client_certificate.pem.crt.h
aws_client_private_key.pem.key.h

Before proceeding, copy both of the new files to the WiSeConnect directory: <SDK>/resources/certificates
Go ahead and overwrite any existing files with the same name in that directory, the originals are not needed.

The Root CA certificate used by your Wi-Fi device to verify the AWS server is already included in the WiSeConnect SDK; no additional setup is required. For reference, Amazon uses Starfield Technologies to secure the AWS website, the WiSeConnect SDK includes the Starfield CA Certificate.

Testing the Application#

After making any custom configuration changes, and updating the device certificate and private key, build, download and run the application as described in the EFx32 Getting Started or STM32 Getting Started.

After successful execution, device updates written to AWS can be observed in the AWS thing shadow. Figure: Shadow Update Activity

The following debug prints are displayed when the application runs successfully. Figure: Debug Prints

AWS IoT Setup#

Create an AWS Thing#

Create a thing in the AWS IoT registry to represent your IoT Device.

In the AWS IoT console, in the navigation pane, choose Manage, and then choose Things.

Figure: AWS console

If a dialog box "You don't have any things yet" appears, choose Register a thing. Otherwise, choose Create.

Figure: AWS Thing

On the Creating AWS IoT things page, choose Create a single thing.

Figure: AWS thing creation

On the Add your device to the device registry page, enter a name for your IoT thing (for example, Test_IoT), and then choose Next. You can't change the name of a thing after you create it. To change a thing's name, you must create a new thing, give it the new name, and then delete the old thing.

Figure: Add Device

On the Add a certificate for your thing page, choose Create certificate.

Figure: Figure: Add certificate

Choose the Download links to download the certificate, private key, and root CA certificate. > Warning: This is the only instance you can download your certificate and private key. Make sure to save them safely.

Choose Activate.

Choose Attach a policy. Figure: Attach Policy

Choose the Policy created and then choose Register Thing.

Note! If you don't have any policy created, follow the steps in Create Policy section in the below and then choose the created Policy

View list of devices as shown Figure: Register Thing

Create Policy#

Navigate to AWS IoT console
Choose Policies under Secure
Click on Create.
Give the Name to your Policy, Fill Action and Resource ARN as shown in below image, Click on Allow under Effect and click Create

Selecting Bare Metal#

The application has been designed to work with FreeRTOS and Bare Metal configurations. By default, the application project files (Keil and Simplicity studio) are configured with FreeRTOS enabled. The following steps demonstrate how to configure Simplicity Studio and Keil to test the application in a Bare Metal environment.

Bare Metal with Simplicity Studio#

Open the project in Simplicity Studio
Right click on the project and choose 'Properties'
Go to 'C/C++ Build' | 'Settings' | 'GNU ARM C Compiler' | 'Symbols' and remove macro 'RSI_WITH_OS=1'
Select 'Apply' and 'OK' to save the settings

Figure: project settings in Simplicity Studio

Bare Metal with Keil#

Open the project in Keil and select 'Options for Target'
Go to the 'C/C++' tab and remove 'RSI_WITH_OS' macro present under Preprocessor Symbols
Select 'OK' to save the settings

Figure: project settings in Keil IDE

Compressed Debug Logging#

To enable the compressed debug logging feature please refer to Logging User Guide