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

Amazon FreeRTOS supports two IDEs for the NXP LPC54018 IoT Module: IAR Embedded Workbench and MCUXpresso. Before you begin, install one of the two IDEs:

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

To install MCUXpresso from NXP

  1. Download and run the MCUXpresso installer from NXP.

  2. Browse to MCUXpresso SDK and choose Build your SDK.

  3. Choose Select Development Board.

  4. Under Select Development Board, type LPC54018-IoT-Module in the Search by Name text box.

  5. Under Boards choose LPC54018-IoT-Module.

  6. On the right-hand side of the page, verify the hardware details and choose Build MCUXepresso SDK.

  7. The SDK for Windows using the MCUXpresso IDE is already built. Choose Download SDK. If you are using another operating system, under Host OS, choose your operating system and then choose Download SDK.

  8. Start the MCUXpresso IDE. In the bottom of the MCUXpresso IDE screen, choose the Installed SDKs tab.

  9. Drag and drop the downloaded sdk archive file into the Installed SDKs window.


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. If you are using IAR Workbench:

    1. In the Software Configurations, find Connect to AWS IoT- NXP and choose Download.

  6. If you are using MCUXpresso:

    1. In the Software Configurations, find Connect to AWS IoT- NXP. Select the Connect to AWS IoT- NXP text, do not choose Download.

    2. Under Hardware Platform choose Edit.

    3. Under Integrated Development Environment (IDE), choose MCUXpresso

    4. Under Compiler, choose GCC.

    5. At the bottom of the page, choose Create and Download.

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

To import the Amazon FreeRTOS sample code into the IAR Embedded Workbench IDE

  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.

To import the Amazon FreeRTOS sample code into the MCUXpresso IDE

  1. Open MCUXpresso and from the File menu, choose Open Projects From File System...

  2. In the Directory text box, type <BASE_FOLDER>\AmazonFreeRTOS\demos\nxp\lpc54018_iot_module\mcuxpresso and choose Finish

  3. In the Project menu, choose Build 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 your IDE, 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

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 your IDE, 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. If you are using IAR Embedded Workbench:

    1. From the Project menu, choose Download and Debug.

    2. From the Debug menu, choose Start Debugging.

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


    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.

  8. If you are using MCUXpresso:

    1. If this is your first time debugging, select the aws_demos project and from the Debug toolbar, choose the blue debug button (Start debugging the project with the selected build configuration).

    2. A window is displayed with any detected debug probes, choose the probe you want to use and click OK to start debugging.


    When the debugger stops at the breakpoint in main(), press the debug restart button once to reset the debugging session. (This is due to an ongoing bug with MCUXpresso debugger for NXP54018-IoT-Module).

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