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 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.
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
Copy the directory of the project you wish to migrate and place it in the same ../apps sub-directory.
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:
- Right-click on the project name and select "Rename …" from the pop-up menu
- Enter the new name for the project
- Check the box "Also Rename Project Folder"
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).
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.
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.
- Verify the MCU being utilized. Modify if incorrect MCU is selected.
- Verify/modify the compiler and version.
- Ensure the proper programmer/debugger has been selected.
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**.
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.
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.