Amazon FreeRTOS
User Guide

Getting Started with the STMicroelectronics STM32L4 Discovery Kit IoT Node

Before you begin, see Prerequisites.

If you do not already have the STMicroelectronics STM32L4 Discovery Kit IoT Node, you can purchase one from STMicroelectronics.

Make sure you have installed the latest Wi-Fi firmware. To download the latest Wi-Fi firmware go to STM32L4 Discovery kit IoT node, low-power wireless, BLE, NFC, SubGHz, Wi-Fi, scroll down to the Binary Resources section, and choose the download link for Inventek ISM 43362 Wi-Fi module firmware update (read the readme file for instructions) .

Setting Up Your Environment

Install System Workbench for STM32

  1. Browse to

  2. Register on the OpenSTM32 webpage. You need to sign in to download System Workbench.

  3. Browse to the System Workbench for STM32 installer to download and install System Workbench.

If you experience issues during installation, see the FAQs on the System Workbench website.

Download and Build Amazon FreeRTOS

After your environment is set up, you can download Amazon FreeRTOS and run the sample code.

Download Amazon FreeRTOS

  1. In the AWS IoT console, browse to the Amazon FreeRTOS page.

  2. In the left navigation pane, choose Software.

  3. Under Amazon FreeRTOS Device Software, choose Configure download.

  4. Choose Download FreeRTOS Software.

  5. Under Software Configurations, find Connect to AWS IoT- ST, and then choose Download.

  6. Unzip the downloaded file to a folder, and make a note of the folder path. In this tutorial, this folder is referred to as BASE_FOLDER.


The maximum length of a file path on Microsoft Windows is 260 characters. The longest path in the Amazon FreeRTOS download is 122 characters. To accommodate the files in the Amazon FreeRTOS projects, make sure the path to the AmazonFreeRTOS directory is fewer than 98 characters long. For example, C:\Users\Username\Dev\AmazonFreeRTOS works, but C:\Users\Username\Documents\Development\Projects\AmazonFreeRTOS causes build failures.

Import the Amazon FreeRTOS Sample Code into the STM32 System Workbench

  1. Open the STM32 System Workbench and type a name for a new workspace.

  2. From the File menu, choose Import. Expand General, choose Existing Projects into Workspace, and then choose Next.

  3. In the Select Root Directory text box, type <BASE_FOLDER>\AmazonFreeRTOS\demos\st\stm32l475_discovery\ac6.

  4. The project aws_demos should be found and selected by default.

  5. Choose Finish to import the project into STM32 System Workbench.

  6. From the Project menu, choose Build All and make sure it compiles without any errors or warnings.

Configure Your Project

To configure your project, you need to know your AWS IoT endpoint.

To find your AWS IoT endpoint

  1. Browse to the AWS IoT console.

  2. In the left navigation pane, choose Settings.

  3. Copy your AWS IoT endpoint from the Endpoint text box. It should look like <1234567890123>.iot.<us-east-1>

  4. Open aws_demos/application_code/common_demos/include/aws_clientcredential.h and set clientcredentialMQTT_BROKER_ENDPOINT to your AWS IoT endpoint. Save your changes.

You also need to know your Wi-FI network SSID, password, and security type and the name of the AWS IoT thing that represents your device. Valid security types are:

  • eWiFiSecurityOpen: Open, no security.

  • eWiFiSecurityWEP: WEP security.

  • eWiFiSecurityWPA: WPA security.

  • eWiFiSecurityWPA2: WPA2 security.

In the Project Explorer window, open aws_demos\application_code\common_demos\include\aws_clientcredential.h.

Specify values for the following #define constants:

  • clientcredentialMQTT_BROKER_ENDPOINT: Your AWS IoT endpoint.

  • clientcredentialIOT_THING_NAME: The AWS IoT thing for your board.

  • clientcredentialWIFI_SSID: The SSID for your Wi-Fi network.

  • clientcredentialWIFI_PASSWORD: The password for your Wi-Fi network.

  • clientcredentialWIFI_SECURITY: The security type for your Wi-Fi network.

Make sure to save your changes.

Configure Your AWS IoT Credentials

The certificate and private key must be hard-coded into the Amazon FreeRTOS demo code. This is for demo purposes only. Production level applications should store these files in a secure location. Amazon FreeRTOS is a C language project, and the certificate and private key must be specially formatted to be added to the project.

To format your certificate and private key

  1. In a browser window, open <BASE_FOLDER>\demos\common\devmode_key_provisioning\CertificateConfigurationTool\CertificateConfigurator.html.

  2. Under Certificate PEM file, choose the <ID>-certificate.pem.crt you downloaded from the AWS IoT console.

  3. Under Private Key PEM file, choose the <ID>-private.pem.key you downloaded from the AWS IoT console.

  4. Choose Generate and save aws_clientcredential_keys.h, and then save the file in <BASE_FOLDER>\demos\common\include. This overwrites the stub file in the directory.

Run the FreeRTOS Samples

  1. Use a USB cable to connect your STMicroelectronics STM32L4 Discovery Kit IoT Node to your computer.

  2. Rebuild your project.

  3. Sign in to the AWS IoT console.

  4. In the left navigation pane, choose Test to open the MQTT client.

  5. In the Subscription topic text box, type freertos/demos/echo, and then choose Subscribe to topic.

  6. From the Project Explorer, right-click aws_demos, choose Debug As, and then choose Ac6 STM32 C/C++ Application.

    If a debug error occurs the first time a debug session is launched, follow these steps:

    1. In STM32 System Workbench, from the Run menu, choose Debug Configurations.

    2. In list box on the left, choose aws_demos Debug. (You might need to expand Ac6 STM32 Debugging.)

    3. Choose the Debugger tab.

    4. In Configuration Script, choose Show Generator Options.

    5. In Mode Setup, set Reset Mode to Software System Reset. Choose Apply, and then choose Debug.

  7. When the debugger stops at the breakpoint in main(), from the Run menu, choose Resume.

In the MQTT client in AWS IoT, you should see the MQTT messages sent by your device.