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 Microchip Curiosity PIC32MZ EF

This tutorial provides instructions for getting started with the Microchip Curiosity PIC32MZ EF. If you do not have the Microchip Curiosity PIC32MZ EF bundle, visit the AWS Partner Device Catalog to purchase one from our partner.

The bundle includes the following items:

You also need the following items for debugging:

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


This tutorial contains instructions for the following getting started steps:

  1. Connecting your board to a host machine.

  2. Installing software on the host machine for developing and debugging embedded applications for your microcontroller board.

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

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

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

Set Up the Microchip Curiosity PIC32MZ EF Hardware

  1. Connect the MikroElectronika USB UART click Board to the microBUS 1 connector on the Microchip Curiosity PIC32MZ EF.

  2. Connect the PIC32 LAN8720 PHY daughter board to the J18 header on the Microchip Curiosity PIC32MZ EF.

  3. Connect the MikroElectronika USB UART click Board to your computer using a USB A to USB mini-B cable.

  4. Connect the MikroElectronika WiFi 7 click Board to the microBUS 2 connector on the Microchip Curiosity PIC32MZ EF.

  5. If not done already, solder the angle connector to the ICSP header on the Microchip Curiosity PIC32MZ EF.

  6. Connect one end of the ICSP cable from the PICkit 3 Programming Cable Kit to the Microchip Curiosity PIC32MZ EF.

    If you don't have the PICkit 3 Programming Cable Kit, you can use M-F Dupont wire jumpers to wire the connection instead. Note that the white circle signifies the position of Pin 1.

  7. Connect the other end of the ICSP cable (or jumpers) to the MPLAB Snap Debugger. Pin 1 of the 8-pin SIL Programming Connector is marked by the black triangle on the bottom right of the board.

    Make sure that any cabling to Pin 1 on the Microchip Curiosity PIC32MZ EF, signified by the white circle, aligns with Pin 1 on the MPLAB Snap Debugger.

    For more information about the MPLAB Snap Debugger, see the MPLAB Snap In-Circuit Debugger Information Sheet.

  8. Connect one end of an Ethernet cable to the LAN8720 PHY daughter board. Connect the other end to your router or other internet port.

Set Up Your Development Environment


The Amazon FreeRTOS project for this device is based on MPLAB Harmony v2. To build the project, you need to use versions of the MPLAB tools that are compatible with Harmony v2, like v2.10 of the MPLAB XC32 Compiler and versions 2.X.X of the MPLAB Harmony Configurator (MHC).

  1. Install Python version 3.x or later.

  2. Install the MPLAB X IDE:

  3. Install the MPLAB XC32 Compiler:

  4. Start up a UART terminal emulator and open a connection with the following settings:

    • Baud rate: 115200

    • Data: 8 bit

    • Parity: None

    • Stop bits: 1

    • Flow control: None

Build and Run Amazon FreeRTOS Demo Project

Open the Amazon FreeRTOS Demo in the MPLAB IDE

  1. Open MPLAB IDE. If you have more than one version of the compiler installed, you need to select the compiler that you want to use from within the IDE.

  2. From the File menu, choose Open Project.

  3. Browse to and open projects/microchip/curiosity_pic32mzef/mplab/aws_demos.

  4. Choose Open project.


When you open the project for the first time, you might get an error message about the compiler. In the IDE, navigate to Tools, Options, Embedded, and then select the compiler that you are using for your project.

Run the Amazon FreeRTOS Demo Project

  1. Rebuild your project.

  2. On the Projects tab, right-click the aws_demos top-level folder, and then choose Debug.

  3. When the debugger stops at the breakpoint in main(), from the Run menu, choose Resume.

Build the Amazon FreeRTOS demo with CMake

If you prefer not to use an IDE for Amazon FreeRTOS development, you can alternatively use CMake to build and run the demo applications or applications that you have developed using third-party code editors and debugging tools.

To build the Amazon FreeRTOS demo with CMake

  1. Create a folder to contain the generated build files (BUILD_FOLDER).

  2. Use the following command to generate build files from source code:

    cmake -DVENDOR=microchip -DBOARD=curiosity_pic32mzef -DCOMPILER=xc32 -DMCHP_HEXMATE_PATH=path/microchip/mplabx/v5.10/mplab_platform/bin -DAFR_TOOLCHAIN_PATH=path/microchip/xc32/v2.15/bin -S <amazon-freertos> -B BUILD_FOLDER -DAFR_ENABLE_TESTS=1


    You must specify the correct paths to the Hexmate and toolchain binaries.

  3. Change directories to the build directory (BUILD_FOLDER), and run make from that directory.

For more information, see Using CMake with Amazon FreeRTOS.

Monitoring MQTT Messages on the Cloud

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 iotdemo/#, and then choose Subscribe to topic.


For general troubleshooting information about Getting Started with Amazon FreeRTOS, see Troubleshooting Getting Started.