Getting started with the Microchip Curiosity PIC32MZ EF

Important

This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you start here when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the Amazon-FreeRTOS Github Repository Migration Guide.

Note

In agreement with Microchip, we are removing the Curiosity PIC32MZEF (DM320104) from the FreeRTOS Reference Integration repository main branch and will no longer carry it in new releases. Microchip has issued an official notice that the PIC32MZEF (DM320104) is no longer recommended for new designs. The PIC32MZEF projects and source code can still be accessed through the previous release tags. Microchip recommends that customers use the Curiosity PIC32MZ-EF-2.0 Development board (DM320209) for new designs. The PIC32MZv1 platform can still be found in v202012.00 of the FreeRTOS Reference Integration repository. However, the platform is no longer supported by v202107.00 of the FreeRTOS Reference.

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:

• Curiosity PIC32MZ EF Development Board

• MikroElectronika USB UART click Board

• MikroElectronika WiFi 7 click Board

• PIC32 LAN8720 PHY daughter board

You also need the following items for debugging:

• MPLAB Snap In-Circuit Debugger

• (Optional) PICkit 3 Programming Cable Kit

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See First steps for instructions.

Important

• In this topic, the path to the FreeRTOS download directory is referred to as freertos.

• Space characters in the freertos path can cause build failures. When you clone or copy the repository, make sure the path that you create doesn't contain space characters.

• The maximum length of a file path on Microsoft Windows is 260 characters. Long FreeRTOS download directory paths can cause build failures.

• Because the source code may contain symbolic links, if you're using Windows to extract the archive, you may have to:

  • Enable Developer Mode or,

  • Use a console that is elevated as administrator.

  In this way, Windows can properly create symbolic links when it extracts the archive. Otherwise, symbolic links will be written as normal files that contain the paths of the symbolic links as text or are empty. For more information, see the blog entry Symlinks in Windows 10!.

  If you use Git under Windows, you must enable Developer Mode or you must:

  • Set core.symlinks to true with the following command:

    git config --global core.symlinks true

  • Use a console that is elevated as administrator whenever you use a git command that writes to the system (for example, git pull, git clone, and git submodule update --init --recursive).

Overview

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 a 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. To connect your board to the internet, use one of the following options:

   • To use Wi-Fi, connect the MikroElectronika Wi-Fi 7 click Board to the microBUS 2 connector on the Microchip Curiosity PIC32MZ EF. See Configuring the FreeRTOS demos.

   • To use Ethernet to connect the Microchip Curiosity PIC32MZ EF Board to the internet, connect the PIC32 LAN8720 PHY daughter board to the J18 header on the Microchip Curiosity PIC32MZ EF. Connect one end of an Ethernet cable to the LAN8720 PHY daughter board. Connect the other end to your router or other internet port. You must also define the preprocessor macro PIC32_USE_ETHERNET.

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.

Set up the Microchip Curiosity PIC32MZ EF hardware using PICkit On Board (PKOB)

We recommend that you follow the setup procedure in the previous section. However, you can evaluate and run FreeRTOS demos with basic debugging using the integrated PICkit On Board (PKOB) programmer/debugger by following these steps.

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

2. To connect your board to the internet, do one of the following:

   • To use Wi-Fi, connect the MikroElectronika Wi-Fi 7 click Board to the microBUS 2 connector on the Microchip Curiosity PIC32MZ EF. (Follow the steps "To configure your Wi-Fi" in Configuring the FreeRTOS demos.

   • To use Ethernet to connect the Microchip Curiosity PIC32MZ EF Board to the internet, connect the PIC32 LAN8720 PHY daughter board to the J18 header on the Microchip Curiosity PIC32MZ EF. Connect one end of an Ethernet cable to the LAN8720 PHY daughter board. Connect the other end to your router or other internet port. You must also define the preprocessor macro PIC32_USE_ETHERNET.

3. Connect the USB micro-B port named "USB DEBUG" on the Microchip Curiosity PIC32MZ EF Board to your computer using a USB type A to USB micro-B cable.

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

Set up your development environment

Note

The 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:

   Note

   FreeRTOS AWS Reference Integrations v202007.00 is currently supported on MPLabv5.35 only. Prior versions of FreeRTOS AWS Reference Integrations are supported on MPLabv5.40.

   MPLabv5.35 downloads

   • MPLAB X Integrated Development Environment for Windows

   • MPLAB X Integrated Development Environment for macOS

   • MPLAB X Integrated Development Environment for Linux

   Latest MPLab downloads (MPLabv5.40)

   • MPLAB X Integrated Development Environment for Windows

   • MPLAB X Integrated Development Environment for macOS

   • MPLAB X Integrated Development Environment for Linux

3. Install the MPLAB XC32 Compiler:

   • MPLAB XC32/32++ Compiler for Windows

   • MPLAB XC32/32++ Compiler for macOS

   • MPLAB XC32/32++ Compiler for Linux

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

Monitoring MQTT messages in the cloud

Before you run the FreeRTOS demo project, you can set up 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, then choose MQTT test client to open the MQTT client.

3. In Subscription topic, enter your-thing-name/example/topic, and then choose Subscribe to topic.

When the demo project successfully runs on your device you see "Hello World!" sent multiple times to the topic that you subscribed to.

Build and run the FreeRTOS demo project

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

Note

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.

To use Ethernet to connect, you must define the preprocessor macro PIC32_USE_ETHERNET.

To use Ethernet to connect using the MPLAB IDE

1. In the MPLAB IDE, right-click the project and choose Properties.

2. In the Project Properties dialog box, choose compiler-name (Global Options) to expand it, and then select compiler-name-gcc.

3. For Options categories, choose Preprocessing and messages, and then add the PIC32_USE_ETHERNET string to Preprocessor macros.

Run the 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 FreeRTOS demo with CMake

If you prefer not to use an IDE for 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 FreeRTOS demo with CMake

1. Create a directory to contain the generated build files, such as build-directory.

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/version/mplab_platform/bin  -DAFR_TOOLCHAIN_PATH=path/microchip/xc32/version/bin -S freertos -B build-folder

   Note

   You must specify the correct paths to the Hexmate and toolchain binaries, such as the C:\Program Files (x86)\Microchip\MPLABX\v5.35\mplab_platform\bin and C:\Program Files\Microchip\xc32\v2.40\bin paths.

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

For more information, see Using CMake with FreeRTOS.

To use Ethernet to connect, you must define the preprocessor macro PIC32_USE_ETHERNET.

Troubleshooting

For troubleshooting information, see Troubleshooting getting started.