Purpose:
After completing this lab, you will have an understanding of the fundamental elements, layout and execution model of an MPLAB® Harmony project. You will also learn how to add features and functionality to your MPLAB Harmony project by using the MPLAB Harmony Configurator (MHC).
Overview:
In this lab you will create a simple MPLAB Harmony project from scratch. You will use MHC to configure the CODEC on the PIC32 Multimedia Expansion Board II. The application streams an audio tone (stored in the form of a lookup table in memory) over the I2S interface which gets played on the audio CODEC. The lab demonstrates basic system initialization and polled state machine design.
| APP_TONE_LOOKUP_TABLE_Tasks() |
Lab Source Files and Solutions:
If you haven't already downloaded all source files for the SD card Audio Player labs:
Download the lab source files and solutions >
This project has been verified to work with the following versions of software tools:
MPLAB X IDE v3.26, MPLAB XC32 Compiler v1.40, MPLAB Harmony v1.08
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 that multiple versions of all these tools can co-exist on the same computer.
Procedure:
All steps must be completed before you will be ready to build, download and run the application.
Part 1: Create project and configure the PIC32MZ
Part 2: Add Application Code
Step 1: Create an MPLAB Harmony project in the MPLAB X IDE
If you haven't already done this, create a folder under the Harmony installation to place this series of labs.
Navigate to the <Harmony install path>/apps folder and create folder structure training/middleware/audio_player. The folder audio_player contains the source files and solutions for all the labs in this exercise.
Extract the file audio_player.zip > to the training/middleware/ folder. A description of the files and folders found in this ZIP file can be found here.
Navigate to the <Harmony install path>/apps/training/middleware 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 Project, and then click Next >.
Specify the following in the "New Project" dialog:
- Harmony Path: <Harmony install path>
- Project Location: <Harmony install path>/apps/training/middleware/dev/audio_player
- Enter Project Name: audio_player_lab1
- Configuration Name: pic32mz_ef_sk_meb2 (this is optional)
- Target Device: PIC32MZ2048EFH144
After clicking the Finish button, the project will be created and opened. You will see the MPLAB Harmony Configurator (MHC) window along with the integrated Harmony Help file.
If you close the MHC window, you can re-open it again by clicking on Tools > Embedded > MPLAB Harmony Configurator
Step 2: With MHC, Select the Board Support Package (BSP)
Click on the "Options" tab in MHC to configure the MPLAB Harmony Framework in a graphical, tree-based format.
Expand the "BSP Configuration" tree (BSP = Board Support Package), and select Use BSP?. Then select the PIC32MZ EF Starter Kit w\ Multimedia Expansion Board (MEB) II development board.
If a Board Support Package (BSP) exists for your development board, you will want to use it. Choosing a BSP lets MHC know about the hardware you will use for the project. With this knowledge, MHC can automatically control the following settings for you:
- PIC32 core configuration (watchdog timer, debugger channel)
- PIC32 oscillator configuration (including external clock/crystal)
- PIC32 I/O Port pin connections to LEDs and switches
In addition to configuring hardware options for you, the BSP comes with a small group of library functions that allow you to more easily interface with LEDs, switches, and other board specific hardware. In this lab, you will observe the selections the BSP makes for you. This will show you how to make these selections manually in case a BSP does not exist for the board you want to use.
Step 3: With MHC, Verify Configuration Bits are correct
Click on the MHC "Options" tab, to view the MPLAB Harmony & Application Configuration tree selections.
Expand the "Device & Project Configuration" and "PIC32MZ2048EFH144 Device Configuration" selection trees to view the PIC32 core configuration selections.
The Board Support Package 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
- DEVCFG1: Verify Watchdog Timer Enable (FWDTEN)…… OFF
- DEVCFG0: No Change
In case you are wondering where these cryptic selection names come from, they correspond to the PIC32 core configuration registers and bit names.
Before moving to Step 4, you may want to collapse the "Device & Project Configuration tree".
Step 4: Verify and Change Oscillator Settings
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_3
- FPLLMULT set to MUL_50
- FPLLODIV set to DIV_2
Experiment with other clock settings. Did you notice how some selections produce red values? These indicate a bad clock configuration. If you mouse over them, a pop-up window will tell you what the problem is.
The PIC32 is connected to a 24MHz external clock input. You are not using the internal PIC32 oscillator.
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 purple background. Since the BSP selected the default values, there should be no shading. 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 graphically!
For custom boards without a BSP, you can use the PLL’s “Auto Calculate” feature to determine and set the PLL 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 master clock (MCKI) input 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"
Verify the output to the PLL is now set to 198 MHz.
When you click on a selection in the MHC "Options" tab, the MHC Help window will show information describing that specific device configuration setting. You may also reference information about the device’s configuration settings in the compiler’s user guide and in the device’s data sheet. If your hardware and debugger connections are correct and you are unable to program, debug, or run code on the device, it is very likely that one of these key device configuration settings is incorrect. You must ensure that these settings are correct before continuing.
Step 5: With MHC, Verify I/O pins using the Graphical Pin Manager
Open the Graphical Pin Manager by clicking on the “Pin Diagram” tab.
Verify the Board Support Package (BSP) (selected in a previous step above) has properly configured the PIC32 pins based on the external devices connected to them. You will be using the Audio CODEC AK4953, LCD Display, LEDs and Switches. Select the “Pin table” tab in the MHC output pane (see the following screen-shot).
If this window is minimized, it can be found on the bottom left part of the MPLAB IDE. Click on it to maximize it.
- Notice pins 43, 44, 45, 67 and 84 have LED selected on it.
- Notice pins 59, 60, 61 and 22 have Switch selected on it.
- Notice pin 46 has Power down enable/disable for the CODEC AK4953 selected on it.
- Notice that the PINs 26, 35, 39, 57, 117 and 133 are selected to interface with the Graphics LCD.
Step 6: With MHC, Configure Audio CODEC AK4953, I2C driver and I2S driver
Select the MHC "Options" tab. Remember, if you ever “lose” the MHC Tool, you can find it here: “Tools > Embedded > MPLAB Harmony Configurator".
Expand the Harmony Framework Configuration > Drivers > CODEC tree.
Check the "Use Codec AK 4953?" Box
A default value for Volume is specified. You can change the value depending on your requirement.
Do not check "Specify MCLK value". A default value of 256 for MCLK is selected under the I2S driver configuration (MCLK Sampling rate Multiplier).
You need to use only one client of the CODEC driver, therefore retain the "Number of AK4953 Driver Clients" value as 1.
The AK4953 Driver supports only one instance of AK4953 CODEC module. AK4953 driver is a single instance driver. Therefore default instance of "Codec AK4953 Driver Instance 0" is selected.
Select the "I2S driver (used for data interface) instance" as DRV_I2S_INDEX_0. The AK4953 driver uses an I2S interface for the audio data transfer to/from the PIC32 microcontroller. The PIC32MZ2048EFH144 device supports multiple instances of I2S modules. Select an instance (Instance 0) for audio data communication.
Select the "Dynamic I2C driver (used for control interface) instance" as DRV_I2C_INDEX_0 or 0. The AK4953 driver uses the I2C interface for the audio control transfers to/from the PIC32 microcontroller. The control transfers exchange commands to/from the AK4953 CODEC to configure and/or read the initialized/existing configuration. The PIC32MZ2048EFH144 device supports multiple instances of I2C modules. Select an instance (Instance 0) for audio control communication.
CODEC devices need a fine clock source to generate accurate audio sampling rates. The clock source (MCLK from the CODEC device’s perspective) can be generated internally by the CODEC device.
PIC32 devices have a flexible reference clock output. The reference clock output module (REFCLKO) can be used to generate the fractional clock that can be used by audio CODEC/DACs to accommodate various sample rates.
The MCLK value represents the multiplier to the sampling frequency (LRCK) which produces the value for the master/reference clock (MCLK/REFCLOCK) to the CODEC. This value should be one of the fs values supported by the CODEC for various sampling rates.
For Example: For 256fs, The MCLK value of ‘256’ for a sampling rate 48000Hz would generate a MCLK/REFCLOCK of 12288000Hz.
By default MCLK value of 256 is selected. This is also shown in the default I2S driver configuration options "MCLK Sampling rate Multiplier".
If you intend to select a different MCLK value, check "Specify MCLK value". It shows the following selectable options 128, 192, 256, 384, 512, 768, and 1152.
Expand the "Harmony Framework Configuration > Drivers > I2C tree. In the AK4953 CODEC driver configurations, you had selected I2C as the control interface. You need to configure this I2C interface driver.
The "Use I2C Driver?" is checked by default. This is done since the AK4953 CODEC driver uses the I2C driver.
Select "Dynamic" for the "Driver Implementation". A "Dynamic" I2C driver implementation is selected because you will need a second I2C instance in Lab5. The I2C in Lab5 is used to interface to the touch panel.
Check the "Interrupt mode" option. Interrupt mode option is selected so that the I2C data completion events can be detected asynchronously without the need for polling for the transfer to complete. This is necessary because by the end of Lab5, the application will add a number of Harmony drivers, system services and middleware. All these Harmony modules have to cooperatively run without blocking the processor so that the functionality of other module(s) does not get affected.
Retain default value of 1 set for "Number of I2C Driver Clients" and "Number of I2C Driver Instances". At this point, I2C is used only to interface with the AK4953 CODEC. These values will be changed later in one of the following labs when more instances of I2C modules are used.
Check "Include Force Write I2C Function". This will include an API that sends data to slave even if the slave NACKs data. This is needed by the AK4953 CODEC since it NACKs I2C data during the initialization sequence.
Under "I2C Driver Instance 0", retain "Use Bit Bang I2C Implementation?" unchecked. Since you are using the hardware I2C instances, you will use the driver for the real hardware instead of a bit banged driver implementation.
Select I2C_ID_2 as "I2C Module ID".
"I2C_ID_2" refers to the PIC32 I2C2 peripheral (using pins SCL2 & SDA2). These pins are connected to the AK4953 audio CODEC on the MEB II board.
Retain default value DRV_I2C_MODE_MASTER as "Operation Mode". The PIC32 I2C module 2 will act as master and the AK4953 CODEC module control interface (I2C) will act as a slave.
Retain default values for "Master Interrupt Priority" and "Master Interrupt Sub-priority" as "INT_PRIORITY_LEVEL1" and "INT_SUBPRIORITY_LEVEL0" respectively. You will want CODEC I2C events to be signaled at higher priority.
Retain default value for "Error Interrupt Priority" and "Error Interrupt Sub-priority" as "INT_PRIORITY_LEVEL1" and "INT_SUBPRIORITY_LEVEL0" respectively.
"Baud Rate generator clock" is configured to 99 MHz; this is derived from the Peripheral bus 2 clock frequency generated from 198 MHz system clock.
Retain default value of 50 KHz for "I2C CLOCK FREQUENCY". The AK4953 CODEC supports fast I2C control interface (up to 400 KHz).
Retain "Slew Rate Control" unchecked. This function enables the I2C module to use high frequency signalling, allowing it to use the 400 kHz and 1 MHz signalling rates.
Retain default value of "SYS_MODULE_POWER_RUN_FULL" for "Power State". You will want to run the I2C module in normal power mode.
Verify/Set the I/O Pins used by I2C module using the Graphical Pin Manager.
Select MHC's "Pin Diagram" sub-tab. Also select the “Pin table” tab in the MHC output pane (bottom of IDE window).
The I2C2 has dedicated pins for SCL2 and SDA2 signals. These pins are hard-coded and configured by the I2C driver.
Expand the "Harmony Framework Configuration > Drivers > I2S" tree.
In the AK4953 CODEC driver configurations you had selected "I2S" as the Audio data interface medium. Next you need to configure the I2S interface driver.
The "Use I2S Driver?" is checked by default. This is done since the AK4953 CODEC driver uses the I2S driver.
Expand the "Use I2S Driver?" Option.
The "Dynamic" "Driver Implementation" is selected by default and is greyed out. The I2S driver does not support static implementation yet.
Check the "DMA Mode" of operation. Under DMA Mode check, "Transmit DMA Support". The "Enable DMA Channel Interrupts?" option is checked by default.
Transmit DMA Support is enabled to use DMA channels to transfer audio data from memory to I2S buffers. The DMA channel is interrupt enabled to allow DMA transfer completion notification.
Retain "Stop in Idle Mode" as it is.
Retain default "Sampling Rate" as 48000. This is the initial value of sampling rate.
Retain default value of 256 for "MCLK Sampling rate Multiplier". The AK4953 CODEC supports 256fs with 48000 Hz sampling rate for generating the REFCLOCK.
Retain default value of 4 for "Master Clock/Bit Clock" ratio.
For sampling Rate 48000 Hz, and MCLK Sampling rate Multiplier value of 256, The Mater Clock (MCLK) or Reference clock (REFCLOCK) = 256 * 48000 = 12288000 Hz. The common Bit Clock that can be generated for the given combination of MCLK and Sampling rate would be REFCLOCK/1, REFCLOCK/2, REFCLOCK/4 or REFCLOCK/8.
For Example: AK4953 CODEC supports bit clock (BCLK) value as either 32fs or 64fs. For 48000 Hz sampling rate, the Bit clock (BCLK) would be 64 * 48000 = 3072000 Hz. Therefore the MCLK/BCLK ratio is 12288000/3072000 = 4.
Retain default value of 1 set for "Number of I2S Driver Clients" and "Number of I2S Driver Instances". You are using the I2S interface only for audio playback, therefore one instance of I2S driver and its client is sufficient.
Under "I2S Driver Instance 0", Retain "SPI_ID_1" as "I2S Module ID". I2S module instance 1 is interfaced to the AK4953 CODEC’s data lines.
Retain default value of "Usage Mode" as "DRV_I2S_MODE_MASTER". It indicates whether the I2S instance would act as a Master or Slave. In Master mode, the PIC32 generates the BCLK to the Slave. In Slave mode the PIC32 receives BCLK from the I2S Master. In the interface to AK4953 CODEC, the PIC32 I2S will act as a Master, and hence generates the BCLK (Bit Clock).
Retain default value of "Baud Clock" as "SPI_BAUD_RATE_MCLK_CLOCK". This Indicates that the system clock of 198MHz is used to generate the baud rate.
Retain default value of "Clock Mode" as "DRV_I2S_CLOCK_MODE_IDLE_HIGH_EDGE_FALL". This is the default polarity for the I2S protocol.
Change "Audio Communication Width" to "SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_32CHANNEL". In the scope of these labs, you are supporting CD quality audio playback, therefore setting 16 bit audio data per channel, 32 bit channel width.
Retain default value of "Audio Mode" as "SPI_AUDIO_TRANSMIT_STEREO". The labs support stereo audio playback.
Retain default value of "Input Sample Phase Selection" as "SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE". This is the default phase for the I2S protocol.
Retain default value of "Audio Protocol Mode" as "DRV_I2S_AUDIO_I2S". You chose the I2S protocol interface mode supported by the AK4953 CODEC.
Retain "Queue Size Transmit" to 3. You will queue up to 3 Audio buffer objects at a time.
Set "Queue Size Receive" to 1. The receive path is not used. Set a minimal value of 1 buffer object.
Retain "Transmit DMA Channel Instance" to 0. You are using DMA Channel Instance 0 for audio data transfer.
Retain default value of "SYS_MODULE_POWER_RUN_FULL" for "Power State". You will want to run the I2S module in normal power mode.
Configure the CODEC External Master Clock input (MCKI) (PIC32 Reference clock output (REFCLOCK))
The PIC32 acts as I2S Master to the AK4953 CODEC. It needs to give the reference clock (REFCLOCK) or External Master Clock input (MCKI) to the CODEC in addition to the Bit clock (BCLK).
Expand the "MPLAB Harmony Configurator > Options > System Services > Clock" selection tree.
Expand "Use Clock System Service?"
Click the "Execute" button beside "Launch Clock Configurator".
Locate the "Reference Clock" block. By default the "Reference Clock #1" tab is selected. Reference Clock #1 enables configuring the reference clock to SPI/I2S, PPS.
Check the "ON" box as shown in the following image. This enables the reference clock circuitry.
Select SPLL as "ROSEL1". The System PLL is used as the source clock for generating the reference clock.
Click the "Auto-Calculate" button to generate the Reference Clock #1. This will open up the "Reference Clock Divider and Trim Auto Calculator" window.
Verify that the "Reference Clock Divisor" and "Trim Auto Calculator" show the desired Reference Clock and Sampling values to be generated. The values are generated from the MCLK multiplier and sampling rate specified in CODEC/I2S driver configuration.
Select the radio button "Target I2S Input Frequency" then click the "Apply" button. The Target I2S Input Frequency is the reference clock input to the AK4953 CODEC.
Note that if Target I2S Input Frequency is shown as 0, it means some I2S configuration is not done properly. Deselect and re-configure the I2S driver as explained above and come back to this step.
Check the "OE" box to enable the Reference Clock #1 output.
It is important to note that a reference clock of 12288000 Hz cannot be accurately generated from a system clock of 200 MHz. It is for this reason that you configured the system clock to 198 MHz, during the oscillator settings step.**
Configure and Verify the DMA System Service for the PIC32 to CODEC DMA channel
The I2S driver has been configured to use a DMA channel for transferring audio data to the CODEC.
Expand the "MPLAB Harmony Configurator > Options > System Services > DMA" selection tree.
Expand the "Use DMA System Service?" tree.
Retain "Select Service Mode" as "Dynamic". You will need a dynamic driver for the following labs when more DMA channels are used.
Retain the "Number of DMA Channel Instances" to 1. One DMA channel instance is used by I2S.
Expand "DMA Channel Instance 0". This is the instance set by I2S driver for transferring audio data.
Under "DMA Channel", Select "DMA_CHANNEL_2". You will use DMA Channel 2 for I2S data transfer.
Retain "Interrupt Priority" and "Interrupt Sub-Priority" as "INT_PRIORITY_LEVEL1" and "INT_SUBPRIORITY_LEVEL0" respectively. You will want I2S data transfer events (DMA) to have a higher priority.
Verify/Set the I/O Pins used by the I2S module using the Graphical Pin Manager.
Select the MHC "Pin Diagram" sub-tab, and in the MHC output pane (bottom of IDE), select the “Pin Table” tab.
Map the REFCLOCK1 signal to pin RD15 as shown in the following image. (For schematic, refer to the Multimedia Expansion Board II (MEB II) User’s Guide)
The I2S1 has a dedicated pin for SCK1 signal. This pin is hardcoded and configured by the I2S driver.
Map I2S1 signals SDI1, SDO1 and SS1(out) signals to pins RD14, RB10 and RF12 as shown in the following image. (For schematic, refer to the Multimedia Expansion Board II (MEB II) User’s Guide)
Save the MHC configuration by clicking the save button.
Step 7: Generate Harmony code and build project
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 added in Harmony v1.08.
Let’s examine what was done after Generating Code:
The app folder contains files related to your specific application. In the following steps, you will add your own code to the existing app.c and app.h files You will also add other application specific source files.
The framework folder under the app folder contains customized Harmony Framework files. These files have been generated by MHC in response to your specific MHC selections.
Also note the framework folder under the Source Files folder contains standard Harmony Framework files that have been added to your project by MHC (based on your MHC selections). To be clear, unlike the framework files found under the app folder, these files have not been modified by MHC. They are some of the standard Harmony Framework files included in the Harmony Framework download.
Save all files and build the code. To do this, click on the "Clean and Build" icon
and verify the project builds successfully.
At this point, you should be able to debug and step through the application. Effectively, you have a running MPLAB Harmony system. However, it is not yet ready to do anything. Next, you will develop your application state machine logic, and make sure the system does what you want it to do. You’re ready to start implementing the application now.
Step 8: Include application specific source files and add required code
Copy source files into your project's source files folder:
app_tone_lookup_table.c
app_tone_lookup_table.h
Copy them from this folder:
apps/training/middleware/audio_player/audio_player_lab1/dev_files
to this one:
apps/training/middleware/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 Items…
Add app_tone_lookup_table.h to Header Files/app by right clicking and selecting ‘Add Existing Items…’
Open the file app.c (in the MPLAB X IDE "Projects" pane under the Source Files > app folder) and add code in function APP_Initialize as shown below.
Add code in function APP_Tasks as shown below.
Save the file before closing.
Open the file system_config.h (in the MPLAB X IDE "Projects" pane under the Header Files > app > system config > pic32mz_ef_sk_meb2 folder), and add code in section Middleware & Other Library Configuration as shown below.
Save the file before closing.
Step 9: Review the application code
C LANGUAGE REFRESHER: enumerated types and structures
In case you need it, here is a refresher on enum and struct types.
Application File: app_tone_lookup_table.h
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 CODEC AK4953.
Observe the CODEC data structure in the following image.
- handle refers to the instance of the opened CODEC AK4953 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.
Application File: app_tone_lookup_table.c
Open file app_tone_lookup_table.c. This file defines the tone lookup table and implements the APIs.
The implementation of function APP_TONE_LOOKUP_TABLE_Initialize sets up the default state of tone lookup table task and initializes the variables for the CODEC driver.
The function APP_TONE_LOOKUP_TABLE_Tasks implements the task’s state machine as shown in the figure in section "Overview" above. It starts in the APP_TONE_LOOKUP_TABLE_STATE_CODEC_OPEN state and remains in it until it opens the CODEC driver and gets a valid driver handle.
In state APP_TONE_LOOKUP_TABLE_STATE_CODEC_ADD_BUFFER, The application submits audio data buffers to the driver queue and enters into a waiting state (APP_TONE_LOOKUP_TABLE_STATE_CODEC_WAIT_FOR_BUFFER_COMPLETE) for the last submitted buffer to complete. The number of buffers queued is equal to "queue size - 1" (i.e., 2 buffers).
The DMA transfers the last buffer, and the CODEC calls the event handler when the buffer transmission is completed. In the event handler APP_TONE_LOOKUP_TABLE_BufferEventHandler, the state of the task is changed from waiting to complete .
A new buffer is submitted from the state
APP_TONE_LOOKUP_TABLE_STATE_CODEC_BUFFER_COMPLETE and the state machine goes to the waiting state again.
The cycle of waiting / complete state continues.
System Configuration File: system_config.h
Define the appliation specific configuration macros in system_config.h. The macro
APP_TONE_LOOKUP_TABLE_CODEC_WRITE_QUEUE_SIZE has the size of the CODEC driver buffer queue.
#define APP_TONE_LOOKUP_TABLE_CODEC_WRITE_QUEUE_SIZE QUEUE_SIZE_TX_IDX0
Step 10: Debug your new application
Congratulations! You’re done: I assure you, the hard part is over! You are now able to build, program, and DEBUG
your first application!
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.
Debug your first application! Click the “Debug Main Project” icon.
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 break points, press the "F5" key, and allow the application to run.
Connect a headphone to the ‘HP Out’ connecter 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.
Don’t be surprised if you cannot step into the PLIB function calls. They are implemented as inline functions and source code is provided in the MPLAB Harmony installation. It is possible to rebuild the PLIB, converting them to actual function calls (without optimizations and with debug symbols enabled) so that you can step through them. PLIBs are generally very simple functions that provide access to peripheral Special Function Registers (SFRs) through an abstracted C-language function call interface that remains the same on all parts on which they are supported.
Time permitting: explore the audio_player_lab1 project files and folders. Observe that the project consists of several “logical” folders within MPLAB X IDE and several physical folders on the disk. This organization is used consistently by MPLAB Harmony applications to keep the files well organized. MPLAB X IDE separates header (.h) files from source (.c) files, so the logical folder structure mirrors (with some small differences) the physical folder structure on disk under both the Header Files and Source Files top-level logical folders. In most cases, the folders on disk correspond directly to the logical folders in MPLAB X IDE, but the header files and source files are not separated on disk as they are in the MPLAB X IDE logical folder tree. Also, the app logical folder corresponds to the src folder on disk.
The application’s src folder contains the main.c file as well as the app.c and app.h along with other application specific files like app_tone_lookup_table.c and app_tone_lookup_table.h that implement the application (by convention, main.c is identical for all MPLAB Harmony applications). The system_config folder normally holds one or more configuration-specific folders (system_config/ pic32mz_ef_sk_meb2 in this case) that each contain a complete set of configuration files for an MPLAB Harmony application.
Results
You should be able to hear a sine tone output through the headphone jack on the Multimedia Expansion Board II. If you did not configure the CODEC driver, I2S driver or REFCLOCK properly, you may not hear the audio at all or may hear distorted audio coming out with clicks and pops in the stream.
Analysis
In this lab you have successfully played a sine tone on the PIC32 microcontroller and heard the audio through the headphone on the development board. The sine tone produced is 16-bit, at a 48000 sampling rate. The tone as such was produced statically and stored in the form of a lookup table in an array. MHC (MPLAB Harmony Composer) was used to configure the hardware modules. The application was developed in a state based implementation. In the application, audio buffer management was done by using the buffer queuing support provided by the CODEC driver.
Conclusions
In this lab you have successfully developed a full fledged MPLAB Harmony Application. This gives you a fair idea of how MPLAB harmony eases application development. If you need to add audio support to any of your existing applications this lab can be used as a reference. This can also be a starting point for your applications which are audio intensive.
