Amazon FreeRTOS
User Guide

Getting Started with the NXP LPC54018 IoT Module

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

Setting up Your Environment

Install IAR Embedded Workbench for Arm

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


    IAR Embedded Workbench for ARM requires Microsoft Windows.

  2. Unzip and run the installer, following the prompts.

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


If you encounter any installation issues, see NXP Support or NXP Developer Resources.

Connecting a JTAG Debugger

You will 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 Users’ Guide.


If you are using a Segger J-Link debugger, you will 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

Once you have your environment setup, 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, select 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 choose Download.

  6. Unzip the downloaded file to a folder, and remember the folder path. We will refer to this folder as BASE_FOLDER in this tutorial.


The maximum length of a file path on Microsoft Windows is 260 characters. In order to accommodate the files in the Amazon FreeRTOS projects, ensure the path to your BASE_FOLDER is less than [XYZ] characters long. For example, C:\Users\Username\Dev\AmazonFreeRTOS will work, but C:\Users\Username\Documents\Development\Projects\AmazonFreeRTOS will cause build failures.

Import the Amazon FreeRTOS Sample Code into IAR Embedded Workbench

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

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

  3. In the Project menu, select Rebuild All.

Configure your Project

Configure your WiFi Credentials

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

  2. Specify values for the following #define constants:

    • clientcredentialWIFI_SSID – your WiFi network’s Wi-Fi SSID.

    • clientcredentialWIFI_PASSWORD – your WiFi network's password.

    • clientcredentialWIFI_SECURITY – your WiFi network's security type, valid values are:

      • eWiFiSecurityOpen - Open, no security.

      • eWiFiSecurityWEP - WEP security.

      • eWiFiSecurityWPA - WPA security.

      • eWiFiSecurityWPA2 - WPA2 Security.

Configure your AWS IoT Endpoint

In order for the FreeRTOS sample code to connect to AWS IoT, you must specify your custom AWS IoT endpoint.

  1. Browse to the AWS IoT Console.

  2. In the left navigation pane, select Settings.

  3. Copy your custom AWS IoT endpoint from the Endpoint textbox (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.

Configure your AWS IoT Credentials

The certificate and private key need to be hard coded into the Amazon FreeRTOS simulator 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 select the <ID>-certificate.pem.crt you downloaded from the AWS IoT console.

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

  4. Select the Generate and save aws_clientcredential_keys.h and save the file in <BASE_FOLDER>\demos\common\include. This will overwrite the stub file that is in the directory already.

Run the FreeRTOS Samples

In order 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. Log into the AWS IoT Console.

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

  4. In the Subscription topic textbox, type freertos/demos/echo and click Subscribe to topic

  5. In IAR Embedded Workbench go to the Project menu and select 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 go to the Project menu and select Download and Debug.

  8. In IAR Embedded Workbench go to the Debug menu and select Start Debugging.

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

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


If a J-Link … Device Selection dialog box opens, click OK to continue. In the Target Device Settings dialog box, select Unspecified, Cortex-M4 and click OK. This will only need to be done once.


If no messages are received at the IOT console, try the following:

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

  2. Check that your network credentials are valid.