MPLAB® Harmony v3 is now configurable through MPLAB Code Configurator (MCC). Although the instructions in this tutorial are for the MHC, the flow and experience of creating a project, configuring peripherals, and generating code using MCC are similar. Refer to the below links for specific instructions to use MPLAB Harmony v3 with MCC.
Objective
MPLAB® Harmony provides the capability to quickly develop complex embedded systems that utilize multiple middleware stacks running at the same time in a Real-Time Operating System (RTOS) or non-RTOS system.
The rapid prototyping ability of MPLAB Harmony is due to the availability of software modules (Drivers, System Services, and Middleware Libraries) and tools (MPLAB Harmony 3 Configurator (MHC) and MPLAB Harmony Graphics Composer (MHGC)) that are designed to allow maximum reuse of code and rapid development.
The following exercises demonstrate the quick prototyping capability of MPLAB Harmony. These exercises should be completed sequentially to understand how the following exercise enhances and adds new functionality to the earlier exercise.
Two Ways to Use This Tutorial:
- Create the projects from scratch.
- Use the provided source files and step-by-step instructions for each lab
- Use the solution project as an example.
- Build the solution project (found in the lab's firmware folder) and download it to the Multimedia Expansion Board II (MEB II) board to observe the expected behavior
Lab Objectives:
- Create an MPLAB X IDE Harmony project for a PIC32 microcontroller from scratch
- Use MHC to configure and generate Harmony code
- Create new application states and variables for Harmony projects
- Identify the proper place to add your application code to the Harmony project
- Demonstrate the use of Harmony peripheral libraries and drivers to control PIC32 peripherals (SPI, I²C, Timers, etc.)
- Demonstrate the use of Harmony middleware libraries (USB, FS, and Graphics, etc.)
Materials
Hardware Tools
Tool | About | Purchase |
---|---|---|
| | |
| | |
| |
It is not necessary to have an MPLAB Real ICE™ to program/debug the code. The PIC32MZ EF Starter Kit includes a PICkit™ on-board (PKOB) debugger. The PKOB debugger can be connected to a host PC through the USB Mini-B connector on the PIC32MZ EF Starter Kit for programming/debugging (see the red cable in the hardware setup).
Apart from the hardware tools listed above, the following items are required to play audio from an SD card and to load audio files into the SD card over a USB interface from the PC:
- Wired stereo headphone
- Micro SD card containing audio files in waveform audio format (WAV)
- USB Type-A male to Micro-B male cable for SD card reader functionality
- USB Type-A male to Mini-B male cable for programming/debugging with PKOB
Software Tools
This project has been verified to work with the following versions of software tools:
MPLAB X IDE v5.25
MPLAB XC32 Compiler v2.30
MPLAB Harmony MHC v3.3.2
DEV_PACKS v3.5.0
CORE v3.5.0
CSP v3.5.0
BSP v3.5.0
AUDIO v3.4.0
GFX v3.4.0
TOUCH v3.4.0
USB v3.3.0
Because we regularly update our tools, occasionally you may discover an issue while using newer versions. If you suspect that to be the case, we recommend that you double-check using the same versions that the project was tested with.
Archived versions of our tools can be found on the following Microchip websites:
MPLAB Harmony (see Archived Downloads tab)
MPLAB X IDE and XC32 Compiler (see Downloads Archive tab)
Note: Multiple versions of all these tools can co-exist on the same computer.
Tool | About | Installers |
Installation
Instructions |
||
---|---|---|---|---|---|
Windows | Linux | Mac OSX | |||
MPLAB® X
Integrated Development Environment |
| | | | |
MPLAB® XC32
C/C++ Compiler |
| | | | |
MPLAB® Harmony 3.xx
Integrated Software Framework |
| |
Use the following menu selection in MPLAB to download the Harmony 3 modules:
Tools > Embedded > MPLAB Harmony 3 Framework Downloader
(For more information, click the link for Harmony 3 "Installation Instructions" above).
Each module can also be downloaded directly from GitHub. The following is the list of modules required by this series of labs:
- DEV_PACKS v3.5.0
- MHC v3.3.2
- CORE v3.5.0
- CSP v3.5.0
- BSP v3.5.0
- AUDIO v3.4.0
- GFX v3.4.0
- TOUCH v3.4.0
- USB v3.3.0
Harmony SD Card Audio Player/Reader Labs
The associated ZIP file contains the completed solution of these five labs. The completed solution is not needed to develop the labs from scratch; it can be used as an example and requires no modifications. To gain a deeper understanding of how to use the MPLAB Harmony framework for Quick Audio Prototyping, and creating an SD card Audio Player/Reader, we recommend you follow the step-by-step procedures detailed in the "Procedure" section below.
- Lab 1: Audio-Tone Generation Using a Lookup Table
- Lab 2: Audio-Tone Generation Using Text File Stored in SD Card
- Lab 3: SD Card Reader Support to Load Audio Files
- Lab 4: Play WAV Audio File from SD Card
- Lab 5: Display Graphics Support to Select and Play an Audio File
Lab Source Files and Solutions
These ZIP files contains the completed solution projects for all the labs associated with this SD card audio player tutorial. It also contains the source files needed to perform the labs per the following step-by-step instructions (see the "Procedure" section on this page).
Unzip the contents of this ZIP file to a working folder of your choice. The following lab examples in this series use the directory below:
<Any directory of your choice>/apps/training/solutions/audio_player/
(Example Directory = C:/microchip/harmony3/)
Note: The project location of a Harmony v3 project is independent of the location of the Harmony Framework path (i.e., you do not need to create or place a Harmony v3 project in a relative path under the Harmony v3 framework folder). The project can be created or placed in any directory of your choice.
The point above is true because when created, a Harmony v3 project generates all the referred source/header files and libraries (if any) under the project folder.
Both points above contrast with Harmony v2 project location. In Harmony v2, the project was supposed to be created in a location under the Harmony framework.
Download the ZIP file for each of these labs
Extracting the ZIP file will create the following folders:
- audio_player_labx (where x = 1 through 5) contains five lab folders (in the firmware folders) and source files (in the dev_files folders).
- dev_files contains application source files and other support files (if any) required to perform each lab (see "Procedure" section below).
- firmware contains the completed lab solution project. It can be directly built and downloaded on the hardware to observe expected behavior.
Procedure
The exercise is split into five labs. Each lab progressively moves towards achieving the final goal of creating a complete audio solution using Harmony:
- Lab 1: Audio-Tone Generation Using a Lookup Table
- Lab 2: Audio-Tone Generation Using Text File Stored in SD Card
- Lab 3: SD Card Reader Support to Load Audio Files
- Lab 4: Play WAV Audio File from SD Card
- Lab 5: Display Graphics Support to Select and Play Audio File
Results
You will observe the following at the end of each lab:
- Lab 1: You should be able to hear a sine tone output through the headphone jack on the MEB II
- Lab 2: As in Lab 1, you should be able to hear a sine tone output through the headphone jack on the MEB II
- Lab 3: You should be able to load audio files to the SD card by connecting the MEB II to a PC over the USB interface. The MEB II will act as a USB Mass Storage Device
For Lab 3, you will be able to play audio data saved in a tone.txt file by loading it through the USB interface. For subsequent labs, you will be able to play WAV files by loading them to the SD card using the USB interface.
- Lab 4: You should be able to play, and hear audio tracks (WAV files) played on your headphones connected to the MEB II
- Lab 5: You should see a graphical user interface on the MEB II display, populated with a list of audio tracks (WAV files) read from the SD card, along with volume and mute control. The user interface should respond to touch events and you should be able to select random tracks for playback, adjust the volume level and mute/unmute the audio output
Problems with the results of each lab could occur if you don't carefully follow the detailed steps provided. Also, note that each lab is an extension of the previous lab; successful completion of earlier labs is essential for the following labs to work.
Analysis
In this exercise series, we have successfully developed an audio solution right from the basic tone playback to an SD card audio player. We added graphics display support and also added support for an SD card reader. Using MHC we configured the hardware modules including Clock, CODEC driver, Reference clock for the CODEC, I²S driver, SPI driver, SD card driver, GFX library, and USB Library. Each of the lab applications was developed in a state-based, loosely coupled implementation. The state-based implementation and lose coupling enabled easily enhancing subsequent labs.
Conclusions
By the end of this lab series, you will have successfully developed a fairly complex audio solution in a fairly short time. By now you should appreciate the real power of MPLAB Harmony, particularly the power of MHC and the ease with which it allows you to add/remove software modules to an existing developed application. With this lab series completed, you are now in the position to create complex applications using PIC32 microcontrollers. MPLAB harmony provides all the necessary software tools that will enable you to quickly develop your application. If you want to expand on this exercise series, try adding more software components such as the TCP/IP stack, or add application support for audio recording.