Migrating a Harmony 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.

Overview

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 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 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 locates in the ../framework sub-directory.

file-overview.png

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

file-path.png
**Relative paths of a project

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

file-copy.png
**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"
rename.png
**Renaming a Project
renamed.png

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 pull-down menu on the top bar of the IDE contains a list of the configurations for the open project. The configurations informs 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).

config-list.png

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 pull-down 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 renamed to an application appropriate name.

To modify the configurations select "Customize …" from the bottom of the configuration pull-down 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.

configuration-modify.png

When creating a new configuration Duplicate a working configuration then Rename it. Creating a New 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. Modify if incorrect MCU is selected.
  2. Verify/modify the compiler and version.
  3. Ensure the proper programmer/debugger has been selected.
properties-modify.png

From the Project Properties window:

  • Click on xc32-gcc
  • Select "Preprocessing and messages" from the Options catagory pull-down menu.
  • Change the Preprocessor macro text to match the configurations name**.
preprocessor-macro.png

Early versions of Harmony used preprocessor macros as a method of informing the application which configuration was active. 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 which configuration is active.

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. ctrl+shift+F will let you 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 ../bsp are sub-directories for each supported development board.

bsp-directory.png
bsp-list.png

BSPs provide programming interfaces which 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 which provide 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 should be ready to run on a new platform.

20th Annual
Microchip MASTERs Conference 2016
Register now - Deadline: July 29

JW Marriott Desert Ridge Resort-Phoenix, AZ

© 2016 Microchip Technology, Inc.
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.