If you haven't already done this, create a folder under the Harmony installation to place this series of labs.
Navigate to the <Any directory of your choice>/apps folder and create the following folder structure: training/solutions/audio_player. The audio_player folder contains the source files and solutions for all the labs in this exercise.
Download all solution ZIP files using below links and extract all the ZIP files to the training/solutions/audio_player folder. A description of the files and folders found in these ZIP files can be found here.

• Lab1
• Lab2
• Lab3
• Lab4
• Lab5

Navigate to the <Any directory of your choice>/apps/training/solutions folder and create these new folders dev/audio_player. You will develop all your labs under this folder. MPLAB X IDE will create a sub-folder named audio_player_lab1 under the dev/audio_player folder.

Start MPLAB X IDE and create a new project by selecting File > New Project.

In the Categories pane of the New Project dialog, select Microchip Embedded.

In the Projects pane, select 32-bit MPLAB Harmony 3 Project and then click Next >.

Specify the following in the New Project dialog screens:

• Project Location: <Any directory of your choice> indicates the path to the root folder of the new project. All project files will be placed inside this folder. The project location can be any valid path, for example, C:\microchip\harmony3\apps\training\middleware\dev\audio_player\audio_player_lab1
• Enter Folder Name: "audio_player_lab1"
• Enter Project Name: "audio_player_lab1"
• Configuration Name: default
• Target Device: PIC32MZ2048EFH144

After clicking the Finish button, the project will be created and opened. The MHC tool will launch and you will be prompted to select the packages to include for the current project.

The required packages for this series of labs are displayed above. Click the Launch button to continue.

Click on the Project Graph tab to view the Harmony 3 configuration display.

Select PIC32MZ EF Starter Kit BSP from the Available Components window.

Click on the System block in the Project Graph window to view the System Device & Project Configuration options.

Expand the Device & Project Configuration and PIC32MZ2048EFH144 Device Configuration selection tree to view the PIC32 core configuration selections.

The BSP you selected has properly configured these selections for you. This step shows you how to make changes to these selections if needed.

• DEVCFG3 and DEVCFG2: No change required.
• DEVCFG1: Verify Watchdog Timer Enable (FWDTEN) is OFF.
• DEVCFG0: Verify Debugger Communication Channel (ICESEL) is set to ICS_PGx2.

Also, be sure to set the Use Cache Maintenance block under MIPS Configuration > CACHE.

In the same system configuration window, expand the DMA (DMAC) tree options. Enable Channel 0 (for SPI1_TX) and Channel 1 (for SPI_RX).

Select the Clock Diagram tab to display the Clock Configurator window.

• Verify the BSP has correctly configured the following clock parameters for you:
  • POSCMOD set to EC.
  • FNOSC set to SPLL.
  • FPLLIDIV set to DIV_2.
  • FPLLMULT set to MUL_33.
  • FPLLODIV set to DIV_2.
  • FPLLRNG set to 8-16 Mhz.

Experiment with other clock settings. Did you notice how some selections produce red values? These indicate a bad clock configuration. If you hover over them, a pop-up window will explain the problem.

When you change the configured clocks away from the default values on the graphical interface, the corresponding selections in the Options tab highlight these changes with a light green background. Any dependency changes made by the system will be highlighted with a light purple background. All selections made under the Clock Diagram tab are reflected under the Options tab. The reverse is also true. You can configure the clocks using the tree selections, but it is much easier to do that graphically.

For custom boards without a BSP, you can use the Phase-Locked Loop's (PLL’s) Auto Calculate feature to determine and set the PLL to multiply and divide values (FPLLIDIV, FPLLMULT, and FPLLODIV). You can see how this works by going back to the Clock Configurator window (Clock Diagram tab).

Change the PIC32 clock frequency to 198 MHz.

This development board can run at a maximum frequency of 200 MHz (selected by default by the BSP). You are using the audio codec on the board, so you need to configure the system frequency to 198 MHz. This change will be explained when you configure the reference clock to provide the MCKI to the audio codec.

• In the MHC Clock Diagram tab, find the System PLL block and select Auto Calculate.
• Change the Desired System Frequency from 200 MHz to 198 MHz.
• Select Apply.

Open the Graphical Pin Manager by clicking on the Pin Settings tab and select to order by Ports.

Some of the LED and SWITCH pins have already been defined by the BSP. However, you will need to define some additional pins required by this lab. It is important to name the pins exactly as they are listed in the following table. Many of the drivers are referencing these pins using a specific name. The following table is a list of the pins required by all the labs in this series (in port order).

You can also display the pin configuration by selecting the Pin Diagram tab. This gives a quick view of which pins are being used by the device.

Select the MHC Project Graph tab. Remember, if you ever lose the MHC Tool, you can find it here: Tools > Embedded > MPLAB Harmony 3 Configurator.

Add a Codec Driver into your project from the Available Components window.

Expand the tree, Audio > Drivers > Codec and select the AK4953 driver.

If you can select an AK4953 driver, skip to the next step.

Restart MHC.

Configure the AK4953 driver component.

The AK4953 component block will be displayed in the Project Graph window as seen in the image below.

Highlight the component block by clicking on it. The available configuration setting will display in the Configuration Options window. For this project, keep the default settings.

Attach an I²C driver to the AK4953 component block.

Right click on the yellow diamond next to DRV_I2C to bring up a list of Satisfiers that can be used to attach to this component. Select the I²C driver component by clicking on it.

At this point, you will be asked to auto activate some components required by the system. Select Yes for the core component and No for the FreeRTOS component.

Your Project Graph should now resemble the screen shown below.

Configure the Core options by clicking on the Core component block. The will bring up the Core option selections in the Configuration Options window. Ensure that the blocks for Enable System Ports and Enable System DMA are checked.

Attach an I²C peripheral (PLIB) to your I²C driver.

Right click on the diamond for the I2C Instance 0. From the Satisfiers list, select I2C2. This matches the hardware I²C peripheral that is routed to the AK4953 controller on the MEB-II Expansion Card.

Your Project Graph should now resemble the screen shown below.

Click on the I2C2 peripheral to display the Configuration Options available for this component. Check the option to "Ignore NACK from Slave". This option is required because of the way the AK4953 controller has implemented the I²C protocol.

Attach an I²S driver to the AK4953 component block.

Similar to the I²C, right click on the yellow diamond next to DRV_I2S to bring up a list of Satisfiers that can be used to attach to this component. Select the I²S driver component by clicking on it. The resulting screen is shown.

Attach an I²S peripheral (PLIB) to your I²S driver.

Right click on the diamond for the I2S Instance 0. From the Satisfiers list, select I2S1. This matches the hardware I²S peripheral that is routed to the AK4953 controller on the MEB-II Expansion Card. The resulting screen is shown.

Click on the I2S1 peripheral to display the Configuration Options available for this component. Change the Frame Select Pin to F12 (which is used by the MEB-II hardware).

Add the Time system service component.

Expand the Available Components window for Harmony > System Services and select the TIME component.

Your Project Graph should now resemble the screen shown below.

Attach the CORE TIMER to the Time system service.

Right click on the TMR diamond in the Time system service block. Select CORE TIMER from the Satisfiers list.

Your Project Graph should now resemble the screen shown below.

Save the MHC configuration by clicking the save button.

Expand the source file folders in the Projects pane. Notice how there are no source files at all, just an empty project with the correct Harmony structure.

Click on the Generate Code button as shown in the following figure. Notice the Merging Strategy option.

Check for Harmony 3 issues in previously released versions.

In the source file drv_i2s.c make sure the buffer size is not getting divided down into a word count. Search for all "/= 2" occurrences and comment them out (refer to code below). This occurs five different times in the following functions; _DRV_I2S_BufferQueueTask (occurs twice), DRV_I2S_WriteBufferAdd, DRV_I2S_WriteReadBufferAdd, and DRV_I2S_ReadBufferAdd.

If you do need to modify these lines, the next time you generate code, you will see the following merge screens displayed. Just press the Close button.

Copy source files:
app_tone_lookup_table.c
app_tone_lookup_table.h
from this folder:
apps/training/solutions/audio_player/audio_player_lab1/dev_files
to this one:
apps/training/solutions/dev/audio_player/audio_player_lab1/firmware/src

Add the copied source files to your project.

• Add app_tone_lookup_table.c to Source Files/app by right clicking and selecting Add Existing Item…

Add app_tone_lookup_table.h to Header Files/app by right clicking and selecting Add Existing Item…

Open the app.c file (in the MPLAB X IDE Projects pane under the Source Files > app folder) and add prototype routines as shown below.

Add code to the APP_Initialize function as shown below.

Add code to the APP_Tasks function as shown below.

Save the file before closing.

Open file app_tone_lookup_table.h. This file defines application states, data, and APIs.

Application states corresponding to the state machine, described in the "Overview" section above, are shown in the following image:

Observe the application data structure shown in the following image. Notice the variable state. The variable codec is for the data type corresponding to the AK4953 codec.

Observe the CODEC data structure in the following image.

• handle refers to the instance of the opened AK4953 codec driver.
• Buffered Harmony driver APIs (e.g., DRV_I2S_BufferAddWrite) returns a handle for each data buffer submitted for processing (transmission/reception). writeBufHandle holds the buffer handle for the audio data buffers submitted for transmission using the codec API DRV_CODEC_BufferAddWrite.
• The application can register an event handler to notify when the submitted transmission/reception request is completed. bufferHandler holds the address of the function which is called when the audio data buffer has been transferred by the codec driver.
• context holds an application-specific value passed to the driver.
• txbufferObject holds the address of the audio data that needs to be transferred to the codec. In this example, it will hold the address of a sine tone lookup table.
• bufferSize holds the size of the audio data buffer.

Application APIs for initialization, task state machine, and buffer completion events are declared.

Before you start the debugger, set a breakpoint in the application file in app_tone_lookup_table.c. Through this breakpoint, you can observe that the tone lookup table task is successfully able to open the codec driver.

Single-step (by pressing the F7 key) through the application state machine to see how each state is executed.

Put a breakpoint in the buffer event handler. Hitting the breakpoint in the event handler indicates that the last submitted buffer is transferred to the codec.

Remove all breakpoints, press the F5 key and allow the application to run.

Connect a headphone to the HP Out connector on the Multimedia Expansion Board II and you should hear a tone.
You are now an MPLAB Harmony developer!
Feel free to debug and step through the code to see how it works. As you continue stepping through the project, you will eventually arrive back at the super loop in the main function. Fundamentally, this is how polled state machines execute within an MPLAB Harmony system.