Amazon FreeRTOS
User Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Getting Started with the Nuvoton NuMaker-IoT-M487

This tutorial provides instructions for getting started with the Nuvoton NuMaker-IoT-M487 development board. The Nuvoton NuMaker-IoT-M487 development board is embedded with the NuMicro M487 series microcontroller, and includes built-in RJ45 Ethernet and Wi-Fi modules. If you don't have the Nuvoton NuMaker-IoT-M487, visit the AWS Partner Device Catalog to purchase one from our partner.

Before you begin, you must configure AWS IoT and your Amazon FreeRTOS software to connect your development board to the AWS Cloud. For instructions, see First Steps. In this tutorial, the path to the Amazon FreeRTOS download directory is referred to as <amazon-freertos>.

Overview

This tutorial guides you through the following steps:

  1. Install software on your host machine for developing and debugging embedded applications for your microcontroller board.

  2. Cross-compile an Amazon FreeRTOS demo application to a binary image.

  3. Load the application binary image to your board, and then run the application.

Set Up Your Development Environment

The Keil MDK Nuvoton edition is designed for developing and debugging applications for Nuvoton M487 boards. The Keil MDK v5 Essential, Plus, or Pro version should also work for the Nuvoton M487 (Cortex-M4 core) MCU. You can download the Keil MDK Nuvoton edition with a price discount for the Nuvoton Cortex-M4 series MCUs. The Keil MDK is only supported on Windows.

To install the development tool for the NuMaker-IoT-M487

  1. Download the Keil MDK Nuvoton Edition from the Keil MDK website.

  2. Install the Keil MDK on your host machine using your license. The Keil MDK includes the Keil µVision IDE, a C/C++ compilation toolchain, and the µVision debugger.

    If you experience issues during installation, contact Nuvoton for assistance.

  3. Install the Nu-Link_Keil_Driver_V3.00.6909 (or latest version), which is on the Nuvoton Development Tool page.

Build and Run the Amazon FreeRTOS Demo Project

To Build the Amazon FreeRTOS Demo Project

  1. Open the Keil µVision IDE.

  2. On the File menu, choose Open. In the Open file dialog box, make sure the file type selector is set to Project Files.

  3. To open the Wi-Fi demo project, choose the target project aws_demos_wifi.uvproj in the folder <amazon-freertos>\projects\nuvoton\numaker_iot_m487_wifi\uvision\aws_demos.

  4. To make sure your settings are correct to flash the board, right-click the aws_demo project in the IDE, and then choose Options. (See Troubleshooting for more details.)

  5. On the Utilities tab, verify that Use Target Driver for Flash Programming is selected, and that Nuvoton Nu-Link Debugger is set as the target driver.

  6. On the Debug tab, next to Nuvoton Nu-Link Debugger, choose Settings.

  7. Verify that the Chip Type is set to M480.

  8. In the Keil µVision IDE Project navigation pane, choose the aws_demos project. On the Project menu, choose Build Target.

You can use the MQTT client in the AWS IoT console to monitor the messages that your device sends to the AWS Cloud.

To subscribe to the MQTT topic with the AWS IoT MQTT client

  1. Sign in to the AWS IoT console.

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

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

To run the Amazon FreeRTOS demo project

  1. Connect your Numaker-IoT-M487 board to your host machine (computer).

  2. Rebuild the project.

  3. In the Keil µVision IDE, on the Flash menu, choose Download.

  4. On the Debug menu, choose Start/Stop Debug Session.

  5. When the debugger stops at the breakpoint in main(), open the Run menu, and then choose Run (F5).

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

Using CMake with Amazon FreeRTOS

You can also use CMake to build and run the Amazon FreeRTOS demo applications or applications you have developed using third-party code editors and debugging tools.

Make sure you have installed the CMake build system. Follow the instructions in Using CMake with Amazon FreeRTOS, and then follow the steps in this section.

Note

Be sure the path to the location of the compiler (Keil) is in your Path system variable, for example, C:\Keil_v5\ARM\ARMCC\bin.

You can also use the MQTT client in the AWS IoT console to monitor the messages that your device sends to the AWS Cloud.

To subscribe to the MQTT topic with the AWS IoT MQTT client

  1. Sign in to the AWS IoT console.

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

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

To generate build files from source files and run the demo project

  1. On your host machine, open the command prompt and navigate to the <amazon-freertos> folder.

  2. Create a folder to contain the generated build file. We will refer to this folder as the <BUILD_FOLDER>.

  3. Navigate to the folder containing the source files for the Amazon FreeRTOS demo project. Then generate the build files by running the following.

    cmake -DVENDOR=nuvoton -DBOARD=numaker_iot_m487_wifi -DCOMPILER=arm-keil -S . -B build -G Ninja
  4. Generate the binary to flash onto the M487 by running the following.

    cmake --build <BUILD_FOLDER>

    At this point, the binary file aws_demos.bin should be in the <BUILD_FOLDER>/vendors/Nuvoton/boards/numaker_iot_m487_wifi folder.

  5. To configure the board for flashing mode, make sure the MSG switch (No.4 of ISW1 on ICE) is switched ON. When you plug in the board, a window (and drive) will be assigned. (See Troubleshooting.)

  6. Open a terminal emulator to view the messages over UART. Follow the instructions at Installing a Terminal Emulator.

  7. Run the demo project by copying the generated binary onto the device.

    If you subscribed to the MQTT topic with the AWS IoT MQTT client, you should see MQTT messages sent by your device in the AWS IoT console.

Troubleshooting

  • If your windows can’t recognize the device VCOM, install the NuMaker windows serial port driver from https://goo.gl/4VGca6.

  • If you connect your device to the Keil MDK (IDE) through Nu-Link, make sure the MSG switch (No.4 of ISW1 on ICE) is OFF, as shown.

If you experience issues setting up your development environment or connecting to your board, contact Nuvoton.

Debugging Amazon FreeRTOS Projects in Keil μVision

To start a debug session in Keil μVision

  1. Open Keil μVision.

  2. Follow the steps to build the Amazon FreeRTOS demo project in Build and Run the Amazon FreeRTOS Demo Project.

  3. On the Debug menu, choose Start/Stop Debug Session.

    The Call Stack + Locals window appears when you start a debug session. μVision flashes the demo to the board, runs the demo, and stops at the beginning of the main() function.

  4. Set breakpoints in your project's source code, and then run the code. The project should look something like the following.

Troubleshooting μVision Debug Settings

If you encounter problems while debugging an application, check that your debug settings are set correctly in Keil μVision.

To verify that the μVision debug settings are correct

  1. Open Keil μVision.

  2. Right-click the aws_demo project in the IDE, and then choose Options.

  3. On the Utilities tab, verify that Use Target Driver for Flash Programming is selected, and that Nuvoton Nu-Link Debugger is set as the target driver.

  4. On the Debug tab, next to Nuvoton Nu-Link Debugger, choose Settings.

  5. Verify that the Chip Type is set to M480.