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 the 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 I²S interface which gets played on the audio CODEC. The lab demonstrates basic system initialization and polled state machine design.
App_Tasks()
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
As the tools are regularly updated, there may be occasional issues while using newer versions. If that is the case, we recommend using the same version as specified in the project.
The archived versions of our tools can be found below:
MPLAB Harmony
MPLAB X IDE and XC32 Compiler
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 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
Click on the Options tab in the MHC to configure the MPLAB Harmony Framework in a graphical, tree-based format.
Expand the BSP Configuration tree, Board Support Package, and select Use BSP?. Then select the PIC32MZ EF Starter Kit w\ Multimedia Expansion Board (MEB) II development board.
If a BSP exists for your development board, you will want to use it. Choosing a BSP lets the MHC know about the hardware you will use for the project. With this knowledge, the 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 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
- 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 hover over them, a pop-up window will tell you what the problem is.
The PIC32 is connected to a 24 MHz 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 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.
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 datasheet. 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 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 at the bottom-left 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 pins 26, 35, 39, 57, 117, and 133 are selected to interface with the Graphics LCD.
Step 6: With MHC, Configure Audio CODEC AK4953, I²C driver and I²S 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 I²S 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 I²S driver (used for data interface) instance as DRV_I2S_INDEX_0. The AK4953 driver uses an I²S interface for the audio data transfer to/from the PIC32 microcontroller. The PIC32MZ2048EFH144 device supports multiple instances of I²S modules. Select an instance (instance 0) for audio data communication.
Select the Dynamic I²C driver (used for control interface) instance as DRV_I2C_INDEX_0 or 0. The AK4953 driver uses the I²C 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 I²C 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 (REFCLKO). The REFCLKO module 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 (Left and Right Clock (LRCK)), which produces the value for the 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 256 fs, the MCLK value of 256 for a sampling rate of 48000 Hz would generate an MCLK/REFCLOCK of 12288000 Hz.
By default, the MCLK value of 256 is selected. This is also shown in the default I²S 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 > I²C tree. In the AK4953 CODEC driver configurations, you had selected I²C as the control interface. You need to configure this I²C interface driver.
The Use I²C Driver? is checked by default. This is done since the AK4953 CODEC driver uses the I²C driver.
Select Dynamic for the Driver Implementation. A dynamic I²C driver implementation is selected because you will need a second I²C instance in Lab5. The I²C in Lab5 is used to interface to the touch panel.
Check the Interrupt mode option. The Interrupt mode option is selected so that the I²C 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 modules does not get affected.
Retain default value of 1 set for Number of I²C Driver Clients and Number of I²C Driver Instances. At this point, I²C 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 I²C modules are used.
Check Include Force Write I²C Function. This will include an Application Programming Interface (API) that sends data to Slave even if the Slave NACKs data. This is needed by the AK4953 CODEC since it NACKs I²C data during the initialization sequence.
Under I²C Driver Instance 0, retain Use Bit Bang I²C Implementation? unchecked. Since you are using the hardware I²C instances, you will use the driver for the real hardware instead of a bit banged driver implementation.
Select I2C_ID_2 as I²C Module ID.
I2C_ID_2 refers to the PIC32 I²C2 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 I²C module 2 will act as Master and the AK4953 CODEC module control interface (I²C) 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 I²C 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 I²C CLOCK FREQUENCY. The AK4953 CODEC supports fast I²C control interface (up to 400 KHz).
Retain Slew Rate Control unchecked. This function enables the I²C module to use high-frequency signaling, allowing it to use the 400 kHz and 1 MHz signaling rates.
Retain default value of SYS_MODULE_POWER_RUN_FULL for Power State. You will want to run the I²C module in Normal Power mode.
Verify/set the I/O Pins used by I²C 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 I²C2 has dedicated pins for SCL2 and SDA2 signals. These pins are hard-coded and configured by the I²C driver.
Expand the Harmony Framework Configuration > Drivers > I²S tree.
In the AK4953 CODEC driver configurations, you had selected I²S as the audio data interface medium. Next, you need to configure the I²S interface driver.
The Use I²S Driver? is checked by default. This is done since the AK4953 CODEC driver uses the I²S driver.
Expand the Use I²S Driver? option.
The Dynamic Driver Implementation is selected by default and is greyed out. The I²S driver does not support static implementation yet.
Check the DMA Mode of operation. Under Direct Memory Access (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 I²S 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 256 fs 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 MCLK or REFCLOCK = 256 * 48000 = 12288000 Hz. The common Bit Clock (BCLK) 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 BCLK value as either 32 fs or 64 fs. For 48000 Hz sampling rate, the 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 I²S Driver Clients and Number of I²S Driver Instances. You are using the I²S interface only for audio playback, therefore one instance of I²S driver and its client is sufficient.
Under I²S Driver Instance 0, retain SPI_ID_1 as I²S Module ID. I²S 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 I²S 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 I²S Master. In the interface to AK4953 CODEC, the PIC32 I²S will act as a Master and hence, generates the BCLK.
Retain default value of Baud Clock as SPI_BAUD_RATE_MCLK_CLOCK. This Indicates that the system clock of 198 MHz 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 I²S 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 I²S protocol.
Retain default value of Audio Protocol Mode as DRV_I2S_AUDIO_I2S. You chose the I²S protocol interface mode supported by the AK4953 CODEC.
Retain Queue Size Transmit to 3. You will queue up to three 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 I²S module in normal power mode.
Configure the CODEC External MCKI (PIC32 REFCLOCK)
The PIC32 acts as I²S Master to the AK4953 CODEC. It needs to give the REFCLOCK or external MCKI to the CODEC in addition to the 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 Serial Peripheral Interface (SPI)/I²S, Peripheral Pin Select (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/I²S driver configuration.
Select the radio button Target I²S Input Frequency then click the Apply button. The Target I²S Input Frequency is the reference clock input to the AK4953 CODEC.
Note that if Target I²S Input Frequency is shown as 0, it means some I²S configuration is not done properly. Deselect and re-configure the I²S 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 I²S 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 I²S.
Expand DMA Channel Instance 0. This is the instance set by I²S driver for transferring audio data.
Under DMA Channel, select DMA_CHANNEL_2. You will use DMA Channel 2 for I²S data transfer.
Retain Interrupt Priority and Interrupt Sub-Priority as INT_PRIORITY_LEVEL1 and INT_SUBPRIORITY_LEVEL0 respectively. You will want I²S data transfer events (DMA) to have a higher priority.
Verify/set the I/O Pins used by the I²S 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 I²S1 has a dedicated pin for SCK1 signal. This pin is hardcoded and configured by the I²S driver.
Map I²S1 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 the 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 the 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 the 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! 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 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.
Don’t be surprised if you cannot step into the Peripheral Library (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 the 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, I²S 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-bits, at a 48000 sampling rate. The tone as such was produced statically and stored in the form of a lookup table in an array. The MHC 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 an 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.