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, see STM32L4 Discovery kit IoT node, low-power wireless, BLE, NFC, SubGHz, Wi-Fi. Under Binary Resources, choose 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 OpenSTM32.org.

  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 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.

Note

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 that 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 enter 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 Select Root Directory, enter <BASE_FOLDER>\AmazonFreeRTOS\demos\st\stm32l475_discovery\ac6.

  4. The project aws_demos should be selected by default.

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

  6. From the Project menu, choose Build All. Confirm the project compiles without any errors or warnings.

Configure Your Project

To run the demo, you must configure your project to work with AWS IoT and a Wi-Fi network.

Configure your AWS IoT endpoint

  1. Browse to the AWS IoT console.

  2. In the navigation pane, choose Settings.

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

  4. Open aws_demos\application_code\common_demos\include\aws_clientcredential.h in your IDE.

  5. Set clientcredentialMQTT_BROKER_ENDPOINT to your AWS IoT endpoint.

Configure your Wi-Fi

  1. Open the same aws_clientcredential.h file.

  2. 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 of your Wi-Fi network.

    Valid security types are:

    • eWiFiSecurityOpen (Open, no security)

    • eWiFiSecurityWEP (WEP security)

    • eWiFiSecurityWPA (WPA security)

    • eWiFiSecurityWPA2 (WPA2 security)

Configure your AWS IoT credentials

Amazon FreeRTOS is a C language project, and the certificate and private key must be specially formatted to be added to the project. You need to format the certificate and private key for your device.

  1. In a browser window, open tools\certificate_configuration\CertificateConfigurator.html.

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

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

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

    Note

    The certificate and private key should be hard-coded for demonstration purposes only. Production-level applications should store these files in a secure location.

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 navigation pane, choose Test to open the MQTT client.

  5. In Subscription topic, enter freertos/demos/echo, and then choose Subscribe to topic.

  6. From 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. 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.

You should see MQTT messages sent by your device in the MQTT client in the AWS IoT console.

Troubleshooting

If you see the following in the UART output from the demo application, you need to update the Wi-Fi module’s firmware:

[Tmr Svc] WiFi firmware version is: xxxxxxxxxxxxx [Tmr Svc] [WARN] WiFi firmware needs to be updated.

To download the latest Wi-Fi firmware, see STM32L4 Discovery kit IoT node, low-power wireless, BLE, NFC, SubGHz, Wi-Fi. In Binary Resources, choose the download link for Inventek ISM 43362 Wi-Fi module firmware update.