Amazon FreeRTOS
User Guide

Getting Started with the Nordic nRF52840-DK

Amazon FreeRTOS support for the Nordic nRF52840-DK is in public beta release. BLE demos are subject to change.

This tutorial provides instructions for getting started with the Nordic nRF52840-DK. If you do not have the Nordic nRF52840-DK, visit the AWS Partner Device Catalog to purchase one from our partner.

Before you begin, you need to Set Up AWS IoT and Amazon Cognito for Amazon FreeRTOS BLE.

To run the Amazon FreeRTOS BLE demo, you also need an iOS or Android mobile device with Bluetooth and Wi-Fi capabilities.

Note

If you are using an iOS device, you need Xcode to build the demo mobile application. If you are using an Android device, you can use Android Studio to build the demo mobile application.

Overview

This tutorial contains instructions for the following getting started steps:

  • Connecting your board to a host machine.

  • Installing software on the host machine that you use to develop and debug embedded applications for your microcontroller board.

  • Cross-compiling an Amazon FreeRTOS demo application to a binary image.

  • Loading the application binary image to your board, and then running the application.

  • Interacting with the application running on your board across a serial connection, for monitoring and debugging purposes.

Set Up the Nordic Hardware

Connect your host computer to the USB port labaled J2, located directly above the coin cell battery holder on your Nordic nRF52840 board.

For more information about setting up the Nordic nRF52840-DK, see the nRF52840 Development Kit User Guide.

Set Up Your Development Environment

Download and Install Segger Embedded Studio

Amazon FreeRTOS supports Segger Embedded Studio as a development environment for the Nordic nRF52840-DK.

To set up your environment, you need to download and install Segger Embedded Studio on your host computer.

To download and install Segger Embedded Studio

  1. Go to the Segger Embedded Studio Downloads page, and choose the Embedded Studio for ARM option for your operating system.

  2. Run the installer and follow the prompts to completion.

Set Up the Amazon FreeRTOS BLE Mobile SDK Demo Application

To run the Amazon FreeRTOS demo project across BLE, you need to run the Amazon FreeRTOS BLE Mobile SDK Demo Application on your mobile device.

To set up the the Amazon FreeRTOS BLE Mobile SDK Demo Application

  1. Follow the instructions in Mobile SDKs for Amazon FreeRTOS Bluetooth Devices to download and install the SDK for your mobile platform on your host computer.

  2. Follow the instructions in Amazon FreeRTOS BLE Mobile SDK Demo Application to set up the demo mobile application on your mobile device.

Establish a Serial Connection

Segger Embedded Studio includes a terminal emulator that you can use to receive log messages across a serial connection to your board.

To establish a serial connection with Segger Embedded Studio

  1. Open Segger Embedded Studio.

  2. From the top menu, choose Target, Connect J-Link.

  3. From the top menu, choose Tools, Terminal Emulator, Properties, and set the properties as instructed in Installing a Terminal Emulator.

  4. From the top menu, choose Tools, Terminal Emulator, Connect port (115200,N,8,1).

Note

You can also establish a serial connection with a terminal tool of your choice, like PuTTy, Tera Term, or GNU Screen. Configure the terminal to connect to your board by a serial connection as instructed in Installing a Terminal Emulator.

Download and Configure Amazon FreeRTOS

After you set up your hardware and environment, you can download Amazon FreeRTOS.

Download Amazon FreeRTOS

To download Amazon FreeRTOS for the Nordic nRF52840-DK, go to the Amazon FreeRTOS GitHub page and clone the repository. The Amazon FreeRTOS BLE library is still in public beta, so you need to switch branches to access the code for the Nordic nRF52840-DK board. Check out the branch named feature/ble-beta.

Note

The maximum length of a file path on Microsoft Windows is 260 characters. Lengthy Amazon FreeRTOS download directory paths can cause build failures.

In this tutorial, the path to the amazon-freertos directory is referred to as <amazon-freertos>.

Configure Your Project

To run the demo, you need to configure your project to work with AWS IoT. To configure your project to work with AWS IoT, your device must be registered as an AWS IoT thing. You should have registered your device when you Set Up AWS IoT and Amazon Cognito for Amazon FreeRTOS BLE.

To configure your AWS IoT endpoint

  1. Browse to the AWS IoT console.

  2. In the navigation pane, choose Settings.

    Your AWS IoT endpoint appears in the Endpoint text box. It should look like <1234567890123>-ats.iot.<us-east-1>.amazonaws.com. Make a note of this endpoint.

  3. In the navigation pane, choose Manage, and then choose Things. Make a note of the AWS IoT thing name for your device.

  4. With your AWS IoT endpoint and your AWS IoT thing name on hand, open <BASE_FOLDER>/demos/common/include/aws_clientcredential.h in your IDE, and specify values for the following #define constants:

    • clientcredentialMQTT_BROKER_ENDPOINT Your AWS IoT endpoint

    • clientcredentialIOT_THING_NAME Your board's AWS IoT thing name

To enable the demo

  1. Check that the BLE GATT Demo is enabled. Go to <BASE_FOLDER>/demos/nordic/nrf52840-dk/common/config_files/iot_ble_config.h, and add #define bleconfigENABLE_GATT_DEMO ( 1 ) to the list of define statements.

  2. Open <BASE_FOLDER>/demos/common/include/iot_demo_runner.h, comment out #define democonfigMQTTDemo_ENABLED, and uncomment #define democonfigBLE_MQTT_ECHO_DEMO_ENABLED.

Build and Run the Amazon FreeRTOS Demo Project

After you download Amazon FreeRTOS and configure your demo project, you are ready to build and run the demo project on your board.

To build and run the Amazon FreeRTOS BLE demo from Segger Embedded Studio

  1. Open Segger Embedded Studio. From the top menu, choose File, choose Open Solution, and then navigate to the project file <BASE_FOLDER>/demos/nordic/nrf52840-dk/ses/aws_demos_ble.emProject

  2. If you are using the Segger Embedded Studio terminal emulator, choose Tools from the top menu, and then choose Terminal Emulator, Terminal Emulator to display information from your serial connection.

    If you are using another terminal tool, you can monitor that tool for output from your serial connection.

  3. Right-click the aws_ble_demos demo project in the Project Explorer, and choose Build.

    Note

    If this is your first time using Segger Embedded Studio, you might see you a warning "No license for commercial use". Segger Embedded Studio can be used free of charge for Nordic Semiconductor devices. Choose Activate Your Free License, and follow the instructions.

  4. Choose Debug, and then choose Go.

  5. Follow the instructions for the MQTT over BLE Demo Application to complete the demo with the Amazon FreeRTOS BLE Mobile SDK demo application as the mobile MQTT proxy.

Troubleshooting

For general troubleshooting information, see Troubleshooting Getting Started.