MPLAB® Harmony 3 User’s Guide

This document describes what MPLAB Harmony 3 is, explains its key architectural concepts, and provides instructions for its use.

What is MPLAB Harmony 3?

Microchip MPLAB Harmony


MPLAB Harmony 3 Wiki


MHC User’s Guide Wiki


Create Your First Peripheral Library Project


Get Started with Harmony 3 on the SAMA5D2

MPLAB® Harmony 3 is an extension of the MPLAB® ecosystem for developing embedded software solutions for Microchip 32-bit devices.  It is comprised of a set of tools, libraries, and example applications that extend the MPLAB® ecosystem to simplify development of embedded software for Microchip® 32-bit SAM and PIC microcontroller and microprocessor devices.  MPLAB Harmony 3 provides the MPLAB® Harmony Configurator (MHC) tool, a set of modular device and middleware libraries, and numerous example applications, all of which are designed to help developers to quickly and easily develop powerful and efficient embedded software for Microchip 32-bit SAM and PIC devices.


MPLAB Harmony 3 Provides

·      Example Applications

·      Modular Libraries

o   Peripheral Libraries

o   Drivers & Services

o   Middleware

·      Graphical Developer Tools for

downloading, configuring, and generating the libraries.


The MHC is an easy to use development tool with a Graphical User Interface (GUI) that simplifies device setup, library selection and configuration, and application development.  The MHC is available as a plugin that directly integrates with the MPLAB® X IDE and as a separate Java executable for standalone use with other development environments.  The included MHC downloader reads an online catalog of library packages and facilitates selection and downloading of any libraries in which the developer is interested.  The configurator provides convenient and powerful development tools for choosing library components from downloaded packages and configuring them for the developer’s application.  And, the built-in code generator produces library and application starter code (usually in source form), based on the options chosen by the developer.


The library packages provided by MPLAB Harmony 3 are distributed in separate GIT repositories containing C-language source-code (and/or templates for generating it) for components that are normally used together or that are parts of a “stack" of related library components.  The Chip Support Package (CSP) contains device startup code and independent low-level Peripheral Libraries (PLIBs) that consist of simple functions to initialize and control peripherals and basic device features. The Core package provides device driver and system service libraries that use PLIBs and that abstract hardware and Real Time Operating System (RTOS) details away from middleware and applications. Middleware libraries use drivers and system services for device independence in order to provide reusable implementations of each module.  Middleware modules are available that support displaying graphics, networking capabilities, USB connectivity, audio playback and recording, Bluetooth connectivity, cryptography, and other powerful capabilities often required by today’s embedded devices.  By default, Core and middleware libraries utilize FreeRTOS through an Operating System Abstraction Layer (OSAL).  But, the OSAL can easily support nearly any RTOS or even systems with no RTOS at all.


Numerous example applications are available for MPLAB Harmony 3 that demonstrate each supported technology and that show common usage models for targeted markets.  The following images show just a few examples.


·      Audio

·      Bluetooth

·      Bootloader

·      Safety

·      Crypto

·      File System

·      Graphics

·      Motor Control

·      TCP/IP

·      USB


Refer to the apps folder in each library repository or to the dedicated apps*repositories provided.


The MPLAB Ecosystem

MPLAB Harmony 3 is designed for use with Microchip 32-bit microcontroller (MCU) and microprocessor (MPU) devices and it works best with Microchip MPLAB tools.  Information about Microchip’s 32-bit MCU and MPU devices, MPLAB X Integrated Development Environment (IDE), XC32 compiler suite, development boards, debugger interfaces, and other development tools is available on the Microchip website.  The MPLAB Harmony Configurator (MHC) is available from the MPLAB X IDE plugin server, accessible from within the IDE.  More information is available from the following Microchip websites.


Getting Started

To get started developing embedded software solutions for Microchip 32-bit devices using MPLAB Harmony 3, you should first obtain a development board and any necessary debugger interface for the device family in which you are interested.  Install the MPLAB X IDE and XC32 compiler suite.  Then install the MPLAB X IDE plugin for the MPLAB Harmony 3 Configurator (MHC). 


Follow the directions and tutorial links provided on the following MPLAB Harmony 3 Wiki site.

·      MPLAB Harmony 3 Wiki


Using Example Applications

MPLAB Harmony 3 examples demonstrate supported technologies and show common usage models for targeted applications.  Applications may be provided in the apps folder of related library repositories or in separate repositories for larger or more numerous sets of applications.  Before using one of these applications, it is best to copy it to a new working directory so that you can modify it without “dirtying” your local copy (clone) of the associated library repository and so that you can maintain it in your own Software Configuration Management (SCM) system.



It is best to use your computer’s operating system (not the MPLAB X IDE, the MHC, or a GIT fork) to copy the source and project files (without the repository history) to a new local folder on your development workstation.  Copy the top-level folder that is named for the application (for example, audio_tone).  It is the folder that includes the firmware and src (source) folders, as shown in the following image.



Next, you may want to delete any configurations in which you are not interested.  A configuration consists of a “.X” (MPLAB X IDE) project folder and the associated MPLAB Harmony <application-name>/src/config/<configuration-name> folder (and all contents of both of folders). 


Referring to the audio_tone example, if you had a SAM V71 Xplained Ultra board and were not interested in the SAM E70 configurations, you would only need to keep the sam_v71_xult configuration, as shown in the image at the Right.




MPLAB Harmony 3 example applications are complete MPLAB X IDE projects.  All source files required to build the project are contained within the <application-name>/src folder.  This is a change from MPLAB Harmony 2, in which projects often referenced files in the MPLAB Harmony installation folder.  Once you have copied the project to a new working directory, you are free to modify it directly using the MPLAB X IDE’s editor.


If you want to use the MHC to reconfigure the options of the MPLAB Harmony libraries used by the application, you can do so just as if it were a project that you created from scratch, and then regenerate the project’s source files.  With the project open in the MPLAB X IDE, launch the MHC (from the Tools > Embedded > MPLAB Harmony 3 Configurator menu).  Ensure that the MPLAB Harmony Framework path is correct for the folder that contains the downloaded MPLAB Harmony 3, as shown in the following example figure.



Then, open the saved configuration XML file from the application’s MPLAB Harmony configuration folder (<application-name>/firmware/src/config/<configuration-name>/<configuration-name>.xml) when prompted.  After that, you may edit the application’s configuration as you normally would when using the MHC.  For additional information on MHC usage, refer to the MHC Wiki at the following link.

·      MPLAB Harmony 3 Configurator Wiki


Creating New Projects

For directions on how to create new projects, refer to the MHC Wiki or the tutorials that are available through the following links.

·      MPLAB Harmony 3 Configurator Wiki

·      Creating Your First Peripheral Library (PLIB) Project


Firmware Development and Reference Models

MPLAB Harmony 3 natively supports applications ranging from simple device-configuration and peripheral-library based projects to complex middleware and RTOS-based applications.  Throughout the entire range of applications, advanced capabilities are built upon fundamental support and developers can scale projects up or down in complexity and capability without needing to extensively rewrite existing code, as often happens in an embedded environment.  This approach of utilizing cumulative capabilities provides the freedom to choose the development model that best serves the application’s needs, as represented in the following figure.

The MPLAB Harmony 3 Chip Support Package (CSP) supports simple device initialization and PLIB-based applications, relying only on the appropriate Device Family Pack (DFP), standard C libraries, and XC32 compiler suite. PLIBs have no dependencies on other MPLAB Harmony components.


Advanced projects that require additional software capabilities can use the MPLAB Harmony 3 core package, which itself relies on the CSP.  Additional capabilities may be provided by Harmony 3 middleware packages (i.e. repositories), which normally rely on the core package for hardware abstraction.  These models are shown in the following diagrams and discussed further in the following sections.


CSP Device-Configuration Projects

The MPLAB Harmony 3 Chip Support Package (CSP) supports configuration of Microchip 32-bit microcontroller and microprocessor devices.  This support can be used to initialize basic functionality necessary in order to use the device.  When using the MHC to only generate minimal device configuration code, the application developer must create all additional logic.  This includes any further peripheral control logic and potentially complex middleware.  All additional code effectively becomes part of the application, as shown by the block in the following image.

While this model places most of the responsibility on the application, it is useful for developers who already have their own application framework and/or operating system and who just need to configure and initialize the device.  This method allows developers to otherwise work in the ecosystems in which they are most familiar.


CSP Peripheral Library Projects

In addition to minimal device initialization, many developers prefer simple and direct control over peripherals with minimal overhead.  To support this model, a developer can use the MHC to add additional peripheral libraries (PLIBs) to a project and the MHC will generate device-specific code to initialize and control the selected peripherals.  This model is represented by the block diagram in the following image.


Again, the application must developer must implement the majority of the logic, but the PLIBs generated by the MHC encapsulate much of the details of controlling the device’s peripherals.  This approach provides small code and data sizes as well as low execution overhead, without undue concern for portability and interoperability.  It is best for creating for simple, optimized applications.


Core Driver & Services Projects

When buffer queuing, peripheral and resource sharing, seamless portability, or interoperability are required, the Harmony 3 core package provides drivers and services that have advanced capabilities and a higher level of abstraction that gives better hardware independence.  Use of core libraries does not preclude the direct use of PLIBs by application code as long as the application does not attempt to share one instance of a PLIB (and its associated peripheral) with Harmony 3 drivers or services.  The following image illustrates this concept.


MPLAB Harmony drivers and services provide abstracted interfaces that do not change from device to device.  PLIB interfaces, while providing lower overhead and more direct control, give no such guarantee.  Applications written using driver and service APIs do not usually need to be modified if the device configuration is changed or even if a new Microchip MCU or MPU device is selected.  Applications written using PLIB APIs will likely require modifications to reconfigure them to use a different configuration, to use a different instance of a peripheral, or to move them to a new device.  Isolated peripherals can still be used directly via PLIBs if desired, as long as portability of the code that uses them is not necessary.  Otherwise, it is best to use drivers to access those peripherals.


Middleware Projects

Harmony 3 middleware packages provide sophisticated software libraries supporting key technologies such as industry-leading graphics, TCP/IP networking with broad protocol support, USB Host and Device capabilities for the most commonly used device classes, cryptographic capabilities, and much more.  Middleware libraries are built upon Harmony 3 drivers and services, so that they are isolated from hardware details, allowing the same great middleware to work with all supported Microchip 32-bit devices.  This concept is shown in the following diagram.


Just like MPLAB Harmony 3 drivers and services, middleware provides abstracted interfaces that are device independent and that allow resource sharing.  Thus, applications using middleware are easily portable to different devices


Real-Time OS Projects

By default, when Harmony 3 core or middleware libraries are used, the MHC automatically includes FreeRTOS in order to provide more efficient use of the CPU.  (RTOS use can still be disabled manually.)  An RTOS supplies multi-threading capabilities and simplifies development of complex applications.  MPLAB Harmony 3 core and middleware libraries interact with the RTOS through an Operating System Abstraction Layer (OSAL), allowing easy portability to support other RTOS’s.  Implementations of the OSAL are available for several popular RTOS’s as well as a bare-metal implementation (without an RTOS), making RTOS usage optional.  The following block diagram illusterates such a system.


MPLAB Harmony 3 drivers, services, and middleware utilize OSAL functions and as state-machine driven design regardless of whether or not an RTOS is used in the system.  The implementation of the OSAL is generated differently, depending on which RTOS is selected (or if no RTOS is selected).  This allows them to be interoperable in all situations.  PLIBs are unaware of RTOS concerns and direct use of them in an RTOS environment will need to be managed by the application code to avoid potential conflicts. 


Your applications are under no obligation to utilize the OSAL or to follow the state-machine-based development model used by the libraries (unless you are using a bare-metal/no-RTOS configuration).  MPLAB Harmony 3 comprehends that embedded applications developers often have a substantial investment in an RTOS ecosystem.  That is why the libraries are made RTOS-portable using by an OSAL and by limiting the RTOS features that they use.  But, application developers are encouraged to use all the features they love from the RTOS of their choice.  MPLAB Harmony libraries will only use what they need and will port easily using the OSAL.


The MPLAB Harmony 3 Firmware Reference Model

The MPLAB Harmony 3 firmware model consists of the accumulation the all of the previously described approaches, as shown in the following diagram.



Do not be concerned that your embedded application must utilize all of the supported development models.  Any given project may contain a number of different modules.  But, no project will include all of the items provided by MPLAB Harmony 3.  Only the over-all MPLAB Harmony embedded software model must comprehend the superset in order provide a scalable and interoperable solution.


Microchip Technology