STMicroelectronics X-CUBE-AWS, STM32Cube User Manual

UM2178

User manual

Getting started with X-CUBE-AWS STM32Cube Expansion Package

for Amazon Web Services® IoT

Introduction

This user manual describes the content of the X-CUBE-AWS STM32Cube Expansion Package for AWS (Amazon Web Services®) IoT (Internet of Things) Core.

The X-CUBE-AWS STM32Cube Expansion Package for AWS IoT Core

•

provides a qualified port of FreeRTOS™ to the supported boards (refer to the User Guide and FreeRTOS Qualification Guide sections on the AWS website at docs.aws.amazon.com/freertos for details)

• offloads – wherever available – the security-critical operations to the on-board STSAFE-A110 Secure Element during

– the MCU boot process

–

the TLS device authentication towards the AWS IoT Core™ server

– the verification of the over-the-air (OTA) update firmware image integrity and authenticity.

It leverages the Secure Element provisioned certificate with the AWS IoT Core Multi-Account Registration feature

™

Refer to Section 1 General information for a presentation of AWS IoT Core™ and FreeRTOS™.

This user manual focuses on X-CUBE-AWS v2.x, which follows the v1.x versions, connecting to the same AWS IoT Core services and therefore compatible with the same cloud services.

X-CUBE-AWS v2.x is a different solution from X-CUBE-AWS v1.x. It is based on the complete FreeRTOS™ software distribution, which coexists with the STM32Cube environment, and not on the AWS IoT Device SDK for Embedded C single middleware library anymore.

Both the aws_demos and aws_tests FreeRTOS™ reference applications are provided:

• aws_demos is configured to illustrate the usage of the FreeRTOS™OTA Update Manager service.

• aws_tests is the test application of the AWS Qualification Program for FreeRTOS™. It is provided as a possible comparison point for the users who plan to get their product go through the qualification process. Its usage is beyond the scope of the present document.

X-CUBE-AWS version v2.0.0 is available for the B-L4S5I-IOT01A Discovery kit.

™

UM2178 - Rev 4 - September 2020 For further information contact your local STMicroelectronics sales office.

www.st.com

1 General information

The X-CUBE-AWS Expansion Package is dedicated to FreeRTOS™ projects running on STM32 32-bit microcontrollers based on the Arm® Cortex®-M processor. The descriptions in the current revision of the user

manual are based on X-CUBE-AWS v2.0.0.

Note: Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

UM2178

General information

1.1

1.2

1.3

What is AWS IoT Core™?

As described on the AWS website at docs.aws.amazon.com/iot,

AWS IoT Core is a managed cloud service that lets connected devices securely interact with cloud applications and other devices. AWS IoT Core also makes it easy to use AWS and Amazon services like AWS Lambda, Amazon Kinesis, Amazon S3, Amazon SageMaker, Amazon DynamoDB, Amazon CloudWatch, AWS CloudTrail, Amazon QuickSight, and Alexa Voice Service to build IoT applications that gather, process, analyze and act on data generated by connected devices.

What is FreeRTOS™?

As described on the AWS website at docs.aws.amazon.com/freertos,

FreeRTOS is an open source, real-time operating system for microcontrollers that makes small, low-power edge devices easy to program, deploy, secure, connect, and manage. FreeRTOS includes a kernel and a growing set of software libraries suitable for use across industry sectors and applications. This includes securely connecting small, low-power devices to AWS cloud services like AWS IoT Core.

What is STM32Cube?

STM32Cube is an STMicroelectronics original initiative to significantly improve designer's productivity by reducing

development effort, time and cost. STM32Cube covers the whole STM32 portfolio.

UM2178 - Rev 4

page 2/31

UM2178

How does X-CUBE-AWS complement STM32Cube?

STM32Cube includes:

• A set of user-friendly software development tools to cover project development from the conception to the realization, among which are:

– STM32CubeMX, a graphical software configuration tool that allows the automatic generation of C

initialization code using graphical wizards

– STM32CubeIDE, an all-in-one development tool with peripheral configuration, code generation, code

compilation, and debug features

– STM32CubeProgrammer (STM32CubeProg), a programming tool available in graphical and command-

line versions

– STM32CubeMonitor (STM32CubeMonitor, STM32CubeMonPwr, STM32CubeMonRF,

STM32CubeMonUCPD) powerful monitoring tools to fine-tune the behavior and performance of STM32

applications in real-time

• STM32Cube MCU and MPU Packages, comprehensive embedded-software platforms specific to each microcontroller and microprocessor series (such as STM32CubeL4 for the STM32L4 Series), which include:

– STM32Cube hardware abstraction layer (HAL), ensuring maximized portability across the STM32

portfolio

– STM32Cube low-layer APIs, ensuring the best performance and footprints with a high degree of user

control over the HW

– A consistent set of middleware components such as FAT file system, RTOS, USB Host and Device,

TCP/IP, Touch library, and Graphics

– All embedded software utilities with full sets of peripheral and applicative examples

• STM32Cube Expansion Packages, which contain embedded software components that complement the functionalities of the STM32Cube MCU and MPU Packages with:

– Middleware extensions and applicative layers

– Examples running on some specific STMicroelectronics development boards

1.4

How does X-CUBE-AWS complement STM32Cube?

X-CUBE-AWS extends STM32CubeL4 by providing a qualified port of FreeRTOS™ to the B-L4S5I-IOT01A board,

with a pre-integrated secure bootloader derived from the X-CUBE-SBSFU Expansion Package and adapted to offload the most sensitive cryptographic operations to the embedded STSAFE-A110 Secure Element.

By exception to the STM32Cube physical architecture, the whole FreeRTOS™ source tree, with its own dependencies and third party libraries, is installed as a whole, as a third-party middleware in the STM32Cube source tree.

UM2178 - Rev 4

page 3/31

UM2178

Amazon Web Services® IoT Core

Figure 1. Amazon Web Services® IoT Core ecosystem

2.1 Online documentation

The user application presented in this document relies on FreeRTOS™ and AWS (mostly the AWS IoT Core services).

General documentation, user guide, developer guide, porting guide, OTA Firwmare Update guide, and others are available on the AWS website.

Most of the documentation of the OTA demo application on the FreeRTOS™ web site (documentation of the OTA library, Basic OTA Demo (with Code Signing) page) is also relevant – with differences in the Configuring the Demo Project section, due to the usage of the multi-account device registration method on the B-L4S5I-IOT01A board.

While Section 5.2.2 User application configuration provides a quick guide on how to get and authorize AWS credentials, the information presented in this document cannot substitute for the Amazon™ information, which is

the reference.

2.2 Account configuration, device registration, device provisioning

The included B-L4S5I-IOT01A user applications use the Multi-Account Registration feature of the AWS IoT Core service.

A unique immutable X.509 device certificate is stored in the physical device at production time, in the STSAFE-

A110 Secure Element. This certificate must be extracted from the physical device to be registered at AWS when

the logical device (called thing in AWS terminology) is created by the user.

The instructions of the present section must be followed through before proceeding to the operations in

Section 5.2.2 User application configuration and launch.

™

UM2178 - Rev 4

page 4/31

Step 1. Extract the device certificate.

This is done in two steps (refer to Section 4.3 Programming a firmware image to the STM32 board and Section 4.2 Virtual terminal setup)

a. Program and run the image Projects/<board_name>/Applications/BootLoader_STSAF

E/STSAFE_Provisioning/Binary/Provisioning.bin so that the STSAFE-A110 Secure Element and the MCU bootloader are paired and may communicate securely with each other.

b. Build, program and run the image Projects\<board_name>\Applications\Cloud\aws_d

emos\<toolchain>\PostBuild\SBSFU_<board_name>_aws_demos.bin.(no need to configure in the source code at this stage). Copy the PEM format certificate displayed on the virtual terminal to a text file. It is referred to it as “my_extracted_cert.pem” in the next steps.

The .bin file above is automatically produced by the post-build stage of the aws_demos application build project. Refer to Section 5.1.3 Building the whole firmware image for information on the SBSFU build system.

Important: The .pem file must exactly contain the text block starting with (and including) -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----.

= [SBOOT] System Security Check successfully passed. Starting... = [FWIMG] Slot #0 @: 8105000 / Slot #1 @: 8036000 / Swap @: 81d5000 ====================================================================== = (C) COPYRIGHT 2017 STMicroelectronics = = = = Secure Boot and Secure Firmware Update = ====================================================================== = [SBOOT] STATE: WARNING: SECURE ENGINE INITIALIZATION WITH FACTORY DEFAULT VALUES! = [SBOOT] STATE: CHECK STATUS ON RESET INFO: A Reboot has been triggered by a Software reset! Consecutive Boot on error counter = 0 INFO: Last execution detected error was:No error. Success. = [SBOOT] STATE: CHECK NEW FIRMWARE TO DOWNLOAD = [SBOOT] STATE: CHECK KMS BLOB TO INSTALL = [SBOOT] STATE: CHECK USER FW STATUS = [SBOOT] LOADING CERTS FROM SECURE ENGINEOK = [SBOOT] Verifying the Certificate chain... OK = [SBOOT] Verify Header Signature... OK A valid FW is installed in the active slot

- version: 1 = [SBOOT] STATE: VERIFY USER FW SIGNATURE = [SBOOT] CHECKING IMAGE STATE = SFU_IMG_CheckImageState Image State = 1 = [SBOOT] IMAGE STATE OK = [SBOOT] STATE: EXECUTE USER FIRMWARE0 524 [Tmr Svc] WiFi module initialized. 1 532 [Tmr Svc] Device Certificate (DER), size = 402 2 537 [Tmr Svc] Device Certificate (PEM), size = 600

-----BEGIN CERTIFICATE----MIIBjjCCATSgAwIBAgILAglQvgEhzCJbATkwCgYIKoZIzj0EAwIwTzELMAkGA1UE BhMCTkwxHjAcBgNVBAoMFVNUTWljcm9lbGVjdHJvbmljcyBudjEgMB4GA1UEAwwX U1RNIFNUU0FGRS1BIFBST0QgQ0EgMDEwIBcNMjAwMjI2MDAwMDAwWhgPMjA1MDAy MjYwMDAwMDBaMEYxCzAJBgNVBAYTAkZSMRswGQYDVQQKDBJTVE1pY3JvZWxlY3Ry b25pY3MxGjAYBgNVBAMMEVNUU0FGRS1BMTEwIEVWQUwyMFkwEwYHKoZIzj0CAQYI KoZIzj0DAQcDQgAEv/XwIjVwhq0S9R1fCeQj8QXr6y3AcXMJIFOtV2GpGhxAkseK QeIe2tMoAkzwwmDdixmFwT/pJuHYvZu6IY6n4TAKBggqhkjOPQQDAgNIADBFAiBq 1p9SL6sAXB1zKsgX9Pr68tKDjKbb2ZZTPcSQ5cU9oAIhAIWMVkv4wIL02v8JXzRN HSRb1zUmb840Eo6c2rJKPG6a

-----END CERTIFICATE----3 595 [Tmr Svc] WiFi Firmware Version C3.5.2.5.STM.

UM2178

Account configuration, device registration, device provisioning

UM2178 - Rev 4

Step 2. Sign-in to or create an AWS account.

Set the required user, access rights and policies for the multi-account registration mechanism. Note that the multi-account registration relieves from creating and provisioning the IoT device credentials. For this specific point, refer to step 5. below. Possible references are:

– The Setting up your AWS account and permissions section of the FreeRTOS™ User Guide on

Amazon™ website

– The Getting started with AWS IoT Core section of the AWS IoT Developer Guide

page 5/31

Step 3. Create an IoT thing policy.

This policy is called “my_iot_policy” in the next steps. Users having used AWS IoT Core™ in the past (for instance with X-CUBE-AWS v1.x) can reuse their thing policy.

Step 4. Install and setup the AWS CLI.

In addition to the default section, set the profile adminuser section in ~/.aws/credentials with

– region

– aws_access_key_id

– aws_secret_access_key

Users with personal AWS accounts given the required access rights may simply copy the [default] settings to the [profile adminuser] section.

Step 5. Register the device.

– Register the X.509 certificate copied from the device console:

aws iot register-certificate-without-ca --certificate-pem file:// my_extracted_cert.pem --status ACTIVE

Note the contents of the certificateArn field that is returned by the command, called

“my_device_cert_arn” in the next steps. Its format is:

arn:aws:iot:<my_region>:<my_account_id>:cert/<my_extracted_cert_id>

– Create the thing:

aws iot create-thing --thing-name my_thing_name

– Empower the thing by granting its certificate with the access rights defined in the thing policy:

aws iot attach-policy --policy-name "my_iot_policy" --target "my_device_cert_arn"

aws iot attach-thing-principal --thing-name my_thing_name --principal my_device_cert_arn

– Retrieve the address of the IoT Core endpoint:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

It is called “my_endpoint_name” in the next steps in the User application configuration section. Its format is:

<account-specific_prefix>-ats.iot.<my_region>.amazonaws.com.

UM2178

Account configuration, device registration, device provisioning

UM2178 - Rev 4

page 6/31

3 Package description

3.1 Logical software architecture

The top-level architecture of the X-CUBE-AWS Expansion Package is shown in Figure 2.

Figure 2. X-CUBE-AWS software architecture

Custom user application

Secure bootloader

Applications

FreeRTOS™

Demos

Platform abstraction port

Tests

UM2178

Package description

software

Key management services

STSAFE-A

Middleware

Drivers

STM32 Wi-Fi

Hardware components

Development boards

Secure Engine

Libraries such as mbedTLS, tinycbor and others

STSAFE-A110

B-L4S5I-IOT01A

FreeRTOS™

Hardware abstraction layer (HAL)Board support package (BSP)

module

IoT SDKFreeRTOS kernel

Utilities

CMSIS

Sensors

The Expansion Package provides a FreeRTOS™ software distribution for STM32Cube. It is composed of:

• FreeRTOS™ standard user applications (aws_demos and aws_tests) and their platform abstraction port to the B-L4S5I-IOT01A board by means of the STM32L4 Series HAL and ISM43362 eS-WiFi driver.

• FreeRTOS™ and its internal dependencies.

• STM32Cube HAL: this driver layer provides a generic multi-instance simple set of APIs (application programming interfaces) to interact with upper layers (application, libraries and stacks). It is composed of generic and extension APIs. It is directly built around a generic architecture and allows the layers that are built upon, such as the middleware layer, to implement their functionalities without dependencies on the specific hardware configuration for a given microcontroller unit (MCU). This structure improves the library code reusability and guarantees an easy portability onto other devices. It includes:

– STM32L4 Series HAL

• Board support package (BSP) layer: the software package must support the peripherals on the STM32 boards apart from the MCU. This software is included in the board support package. This is a limited set of APIs, which provides a programming interface for certain board-specific peripherals such as the LED and user button. It includes:

– Low-layer driver for the Inventek ISM43362 eS-WiFi module

– Sensor drivers for the B-L4S5I-IOT01A board (not used by the applications provided)

UM2178 - Rev 4

page 7/31

• Secure bootloader, key management and image state management application derived from the X-

CUBE-SBSFU Expansion Package, relying on its companion middleware components and on-board STSAFE-A110 component.

The software is provided as a .zip archive containing source-code.

The following integrated development environments are supported:

• IAR Systems - IAR Embedded Workbench® (EWARM), version 8.32.3 or higher

• STMicroelectronics - STM32CubeIDE, version 1.3.0 or higher

3.2 Folder structure

3.2.1 STM32Cube view

Figure 3 presents the top folder structure of the X-CUBE-AWS Expansion Package. Figure 4, Figure 5, and Figure 6 further detail the top folder contents.

UM2178

Folder structure

Figure 3. Top folders

Figure 4. Drivers folder

BSPv1 drivers for the bootloader applications.

BSPv2 drivers for the user applications.

Board component drivers, for instance, the sensors of B-L475E-IOT01A / B-L4S5I-IOT01A.

UM2178 - Rev 4

page 8/31

Figure 5. Middlewares folder

Wrapper to the mbed-crypto library

PKCS#11 implementation of the FreeRTOS™ PAL

Components of the secure bootloader applications

Software interface to the STSAFE-A110 secure element

UM2178

Folder structure

FreeRTOS™ software distribution, with its embedded set of middleware components, demos and tests applications

Cryptographic and TLS libraries used by the bootloader applications

UM2178 - Rev 4

page 9/31

Figure 6. Projects and Utilities folders

Bootloader and Secure Firmware Update application, relying on the soldered STSAFE-A110 secure element

UM2178

Folder structure

FreeRTOS™ demo application, set up for the over-the-air firmware update use case

FreeRTOS™ configuration files

IDE project folders: 2 toolchains support

FreeRTOS™ platform abstractions implementation

UM2178 - Rev 4

page 10/31

+ 21 hidden pages