Amazon FreeRTOS
User Guide

Getting Started with the NXP LPC54018 IoT Module

Before you begin, see Prerequisites.

If you do not have an NXP LPC54018 IoT Module, you can order one from NXP. Use a USB cable to connect your NXP LPC54018 IoT Module to your computer.

Setting Up Your Environment

Install IAR Embedded Workbench for Arm

  1. Browse to Software for NXP Kits and choose Download Software to install IAR Embedded Workbench for Arm.


    IAR Embedded Workbench for ARM requires Microsoft Windows.

  2. Unzip and run the installer. Follow the prompts.

  3. In the License Wizard, choose Register with IAR Systems to get an evaluation license.


If you experience issues during installation, see NXP Support or NXP Developer Resources.

Connecting a JTAG Debugger

You need a JTAG debugger to launch and debug your code running on the NXP LPC54018 board. Amazon FreeRTOS was tested using a Segger J-Link probe. For more information about supported debuggers, see the NXP LPC54018 User Guide.


If you are using a Segger J-Link debugger, you need a converter cable to connect the 20-pin connector from the debugger to the 10-pin connector on the NXP IoT module.

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. Browse to the Amazon FreeRTOS page in the AWS IoT console.

  2. In the left navigation pane, choose Software.

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

  4. Choose Download FreeRTOS Software.

  5. In the Software Configurations, find Connect to AWS IoT- NXP, 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 IAR Embedded Workbench

  1. Open IAR Embedded Workbench, and from the File menu, choose Open Workspace.

  2. In the search-directory text box, type <BASE_FOLDER>\AmazonFreeRTOS\demos\nxp\lpc54018_iot_module\iar, and choose aws_demos.eww.

  3. In the Project menu, choose Rebuild All.

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

To run the Amazon FreeRTOS demos on the NXP LPC54018 IoT Module board, connect the USB port on the NXP IoT Module to your host computer, open a terminal program, and connect to the port identified as "USB Serial Device."

  1. Rebuild your project.

  2. Sign in to the AWS IoT console.

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

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

  5. In IAR Embedded Workbench, from the Project menu, choose Build.

  6. Connect both the NXP IoT Module and the Segger J-Link Debugger to the USB ports on your computer using mini-USB to USB cables.

  7. In IAR Embedded Workbench, from the Project menu, choose Download and Debug.

  8. From the Debug menu, choose Start Debugging.

  9. When the debugger stops at the breakpoint in main(), go to the Debug menu, and choose Go.

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


If a J-Link Device Selection dialog box opens, choose OK to continue. In the Target Device Settings dialog box, choose Unspecified, choose Cortex-M4, and then choose OK. You only need to be do this once.


If no messages appear in the AWS IoT console, try the following:

  1. Open a terminal window to view the logging output of the sample. This can help you determine what is going wrong.

  2. Check that your network credentials are valid.