Migrating a Harmony v2 Project to New Hardware Platform

These pages show how users can modify a Harmony project running on a Microchip supplied development board so the project can be run on a user-designed hardware platform.


The Harmony installation directory contains a number of sample projects in the apps directory (…Microchip/Harmony/vX_XX/apps). These projects include sample applications using Harmony middleware libraries (USB, TCP/IP, Bluetooth®, etc.) as well as some projects using various PIC32 MCU peripherals.

Each sample project is written to run on a variety of Microchip supplied hardware development boards. Users who wish to evaluate the suitability of a Harmony feature can obtain one of the supported development boards and run a sample project demonstrating the feature. Each sample project includes a simple demonstration code. Once the underlying Harmony capability has been verified, the user can begin to implement their application by modifying the supplied demonstration code.

It is expected that the user will eventually run the project on their own hardware design.

Copy Existing Project to a New Location

The project files and application source code for the sample Harmony projects reside in the ../apps directory. These projects also include links to Harmony framework source code located in the ../framework sub-directory.


In order to successfully copy a Harmony project, the relative path between the project files and the framework source code must be maintained.

The picture below illustrates how the sample project directory data_basic and data_temp_sens_rgb must be located in ../apps/bluetooth/data. The sample projects contain relative links to the framework source code ../framework.

Relative paths of a project

Copy the directory of the project you wish to migrate and place it in the same ../apps sub-directory.

Example of data_basic project being copied to MyCopy of data_basic

Rename New Project

From the IDE, open the copy of the new project. You will notice that the project in the copy directory has the same name as the original project. To rename the project:

  1. Right-click on the project name and select Rename … from the pop-up menu.
  2. Enter the new name for the project.
  3. Check the box Also Rename Project Folder.
Renaming a project

Adjust Project Configurations

Harmony utilizes the IDE's capacity to have multiple sets of build instructions for each project. These build-lists are called configurations. A dropdown menu on the top bar of the IDE contains a list of the configurations for the open project. The configurations inform the IDE which MCU to use, which version of the compiler to invoke, and what unique files need to be included in the project. A configuration also includes the paths for the files to be included in the project (for Harmony projects these are relative paths to multiple sub-folders under …/framework).


The sample projects have a configuration for each supported development board. To run a project on a demo board, the user selects the appropriate configuration from the dropdown menu before the project is built.

When a project is being migrated to a new hardware platform, it is likely that the project will need fewer configurations than the original example project. To avoid confusion, unused configurations should be deleted. The remaining configuration(s) should be appropriately renamed.

To modify the configurations, select Customize … from the bottom of the configuration dropdown menu.

The Project Properties box will appear. Select Manage Configurations. A window will appear, giving you the ability to duplicate, rename or delete any configuration.


When creating a new configuration, Duplicate a working configuration and then Rename it. Using New to create a new configuration is not advisable as you will be required to manually enter multiple, and lengthy, file include-paths.

Modify Project Properties

Once the unwanted configurations have been removed, the remaining configuration(s) settings need to be verified. Open the Project Properties window to begin the verification process.

  1. Verify the MCU being utilized and modify if the incorrect MCU is selected.
  2. Verify/modify the compiler and compiler version.
  3. Select the proper programmer/debugger.

From the Project Properties window:

  • Click on xc32-gcc.
  • Select Preprocessing and messages from the Options categories: dropdown menu.
  • Change the Preprocessor macros text to match the configurations name.

Early versions of Harmony used preprocessor macros as a method of informing the application about active configuration. The preprocessor macro contained a text string which designated the project configuration being used. The program would conditionally compile code based on an #if define directive to test an active configuration.

Current versions of Harmony sample projects seldom use preprocessor macros for conditional compilation. However, occasionally conditional compilation may be present in the project you are migrating. Before renaming the preprocessor macro text, you should verify that no conditional compilation is performed on this macro. Press Ctrl + Shift + F to search the entire project for occurrences of the macro's text to determine if any code is conditionally compiled into the project, based upon the active configuration.

Create Board Support Package Files ( If Needed)

In addition to …/apps and …/framework, Harmony installation directories continue a Board Support Package (BSP) sub-directory, …/bsp. Inside of the …/bsp are sub-directories for each supported development board.


BSPs provide programming interfaces that allow the example Harmony applications to run without modification on different development boards. This hardware abstraction is achieved by implementing the specifics of the hardware configuration within the software functions contained in the BSP packages.

Each BSP supplied with Harmony contains one source and one header file that provides APIs called by the sample application code. The active configuration informs the IDE which single BSP should be included in the project build.

In modifying the sample code to implement your application, you may have eliminated all calls to the BSPs. If the BSPs are not called, they can be removed from the project.

You can implement a level of hardware abstraction by either modifying the existing BSPs or by creating your own hardware abstraction mechanism. If you modify an existing BSP, be aware that BSPs are shared by all Harmony applications. Changing the code in one development board's BSP may change the operation of all the Harmony applications running on the development board.

After completing these steps, the project will be ready to run on a new platform.

© 2024 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.