1

Create a new folderaudio_player_lab4 underapps/training/middleware/dev/audio_player.

At this point, we suggest you close any open projects from previous Labs. This will avoid confusion since you will be opening the project with the same name as the previous Lab before renaming it for this lab.

2

Copy thefirmware folder from
apps/training/middleware/dev/audio_player/audio_player_lab3 to the newly created folder,audio_player_lab4.

3

Rename the project fromaudio_player_lab3 toaudio_player_lab4.

• Openaudio_player_lab3.
• UnderProjects, right click onaudio_player_lab3 and selectRename….

• In the pop up window, rename the project fromaudio_player_lab3 toaudio_player_lab4.

• MPLAB X IDE then renames the project. It closes the old projectaudio_player_lab3 and opens the renamed projectaudio_player_lab4.

4

5

ClickTools > Embedded > MPLAB Harmony Configurator to open MHC.

1

Generate and save the configuration as shown below :

• Make sure that the Merging Strategy selected isPrompt Merge For All User Changes.

2

Resolve code generation merge conflicts.

When you click theGenerate button, MHC will modify and generate source files based on the options selected in MHC. If MHC generates code that will change a pre-existing file, it will show you the code it generated, and allow you to confirm if you want to add it to your source code. The following screenshots will guide you on which changes need to be merged (i.e., accepted).

Click theNext button (highlighted in blue) to keep the #define statement shown in the following image and move to the next set of merge conflicts.

Click the arrow highlighted in green and merge the code from the generated code to the current file as shown in the following image.

1

Copy source files into your project's source files folder:

• app_sdcard_audio_task.c
• app_sdcard_audio_task.h
• decoder.c
• decoder.h

Copy them from this folder:
apps/training/middleware/audio_player/audio_player_lab4/dev_files
to this one:
apps/training/middleware/dev/audio_player/audio_player_lab4/firmware/src

2

Add the copied source files to your project.

• Addapp_sdcard_audio_task.c anddecoder.c toSource Files\app by right clicking and selectingAdd Existing Items…

• Addapp_sdcard_audio_task.h anddecoder.h toHeader Files\app by right clicking and selectingAdd Existing Items…

3

Removeapp_tone_textfile_sdcard.c andapp_tone_textfile_sdcard.h from the folder.

• Right click on theapp_tone_textfile_sdcard.h file and selectRemove From Project.

• Right click on theapp_tone_textfile_sdcard.c file and selectRemove From Project.

After performing this step, the files under the project should look like this:

4

Next, we need to tell the compiler about the path of the decoders and include files.

• To include this path, right click on the project nameaudio_player_lab4 in the MPLAB XProjects pane and selectProperties.
• In theCategories pane, selectConf:[pic32mz_ef_sk_meb2] > XC32 (Global Options) > xc32-gcc.
• Now, click on theOption categories dropdown menu and select thePreprocessing and Messages option.

• Click on the box besideInclude directories.

Browse to the following path:
..\microchip\harmony\v1_08\apps\audio\universal_audio_decoders\firmware\src\audio_decoder.
SelectOK.

5

As we did with the previous exercise, we will modify theapp.c andapp.h files from the previous exercise in order to change function names to match the function names in the newly includedapp_sdcard_audio_task.c file. Open the fileapp.c and find theAPP_Initialize function. Change the function named:
APP_TONE_TEXTFILE_SDCARD_Initialize()
to:
APP_SDCARD_AUDIO_Initialize() as shown below.

6

Find theAPP_Tasks function and change the function named:
APP_TONE_TEXTFILE_SDCARD_Tasks()
to:
APP_SDCARD_AUDIO_Tasks() as shown below.

7

An additional step is required here. We must include theapp_sdcard_audio_task.h file inapp.h. This is required because the decoder filewav.c depends on definitions present in other files and expectsapp.h to include those files. Includingapp_sdcard_audio_task.h inapp.h will include all the relevant files needed by the decoder.
Fromapps/training/middleware/dev/audio_player/audio_player_lab4/firmware/src, openapp.h and add the line as shown below:

8

Next, openapp_button_press_task.c and change the name of the function from:
APP_TONE_TEXTFILE_SDCARD_SuspendStreaming
to:
APP_SDCARD_AUDIO_SuspendStreaming.
Also, change the name of the function from:
APP_TONE_TEXTFILE_SDCARD_Initialize
to:
APP_SDCARD_AUDIO_Initialize, as shown below.

9

Finally, we need to add application specific definitions in thesystem_config.h file. Opensystem_config.h.

10

1

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

2

Application states corresponding to the state machine described in theOverview section are as follows. (Note the newly added states are indicated by a red box.)

3

The audio player states are shown below.

All of the these enumerations should be self-explanatory.

4

The application data structure is shown below:

The variablesstate andcodec are retained from the previous lab. They hold the state of application and codec related variables respectively.

5

The audio player data structure is shown below.

The functionality of some of the important structure members are explained below:

• fileHandle holds "handle" to the audio file currently being played.
• fileStatus holds the file status for the current audio file, returned by a call toSYS_FS_FileStat().
• state holds the state of the audio player state machine
• buffer holds the buffer related information that is used by the decoder and the audio CODEC. Thebuffer members are:

• buffer holds the decoded audio data.
• inUse, a buffer is marked to be in use when the buffer is queued for playing with the CODEC.
• decoded, a buffer is marked as decoded when the buffer contains the decoded audio data (output of decoder).
• writeHandler, holds the buffer handle returned by a call toDRV_CODEC_BufferAddWrite().
• bufferSize indicates the number of decoded audio data elements available in thebuffer.
• currentSongIdx,nextSongIdx andpreviousSongIdx point to index of the current song, next song and previous song respectively in the global buffer that contains the path information of all the audio files.
• totalAudioFiles holds the total number of WAV audio files found on the SD card.
• nBytesRead holds the actual number of bytes read from the file; returned by a call toSYS_FS_FileRead().
• currentFilesize holds the total size of the current audio file pointed by thefileHandle.
• readIdx andwrriteIdx are used to index into thebuffer containing audio data for the audio CODEC.writeIdx points to the index until the decoded audio data is available in thebuffer.readIdx points to the index until the audio data is queued to the audio CODEC.
• decodeDataSize holds the number of data bytes decoded by the decoder; returned by a call toDECODER_Decode().

6

APP_SDCARD_AUDIO_CARD_EVENT enumerates the events passed to the SD card event handler.

The enumAPP_SDCARD_AUDIO_CARD_EVENT is passed to the SD card event handler,APP_SDCARD_AUDIO_Card_EventHandler(), allowing the application to take various actions based on the SD card events.

7

Open the fileapp_sdcard_audio_task.c. This file contains the application state machine and implements the APIs.

8

The implementation of functionAPP_SDCARD_AUDIO_Initialize sets up the default state ofAPP_SDCARD_AUDIO_Tasks and initializes the variables for the CODEC driver and player state machine along with other variables.

9

The functionAPP_SDCARD_AUDIO_Tasks implements the task’s state machine as shown in the figure inOverview section. As in the previous lab,SD Card Audio Player Lab3, it starts in theAPP_SDCARD_AUDIO_STATE_CODEC_OPEN state and remains in it until it opens the CODEC driver and gets a valid driver handle. After this, it registers a CODEC buffer handler in theAPP_SDCARD_AUDIO_STATE_CODEC_SET_BUFFER_HANDLER state, mounts the file system in theAPP_SDCARD_AUDIO_CARD_MOUNT state, and sets the current drive in theAPP_SDCARD_AUDIO_CARD_CURRENT_DRIVE_SET state.

10

The application then enters theAPP_SDCARD_AUDIO_STATE_RUNNING state where it calls theAPP_SDCARD_AUDIO_Card_Tasks function that traverses through all the directories on the SD card and saves the path of all WAV files found to theAppSdCardAudioCardFilesTable. It also selects the first WAV file from theAppSdCardAudioCardFilesTable and a call to theAPP_SDCARD_AUDIO_Card_OpenTrack function opens it for playing.

11

The audio player state machine then starts executing. The audio player stateAPP_SDCARD_AUDIO_PLAYER_STATE_RUNNING checks if any buffer is available and, if yes, reads the current audio file by a call to theAPP_SDCARD_AUDIO_Card_FillBuffer function and passes the read data to theAPP_SDCARD_AUDIO_Player_Decode function which decodes the WAV formatted data read from the file. Finally, if none of the decoded buffer is in use, it queues the decoded buffer to the CODEC driver for playing by a call toDRV_CODEC_BufferAddWrite function and marks it as in use.
The player state remains in theAPP_SDCARD_AUDIO_PLAYER_STATE_RUNNING state until the entire audio file has been read out.

12

The CODEC driver calls the buffer event handlerAPP_SDCARD_AUDIO_BufferEventHandler (registered with the CODEC by a call to theDRV_CODEC_BufferEventHandlerSet function), upon completion of each queued buffer to the audio CODEC. The application checks if a decoded buffer is ready and, if yes, queues the decoded buffer for playing with the audio CODEC by a call to theDRV_CODEC_BufferAddWrite function.

13

Once the audio file is completely read out, or if the decoder output is zero (i.e., there is nothing to decode), the player state is changed toAPP_SDCARD_AUDIO_PLAYER_STATE_TRACK_CHANGE, where it first waits for the already queued audio buffers to the CODEC driver to complete; after which it selects the next audio file from theAppSdCardAudioCardFilesTable, and opens it for playing. The player state machine then changes back toAPP_SDCARD_AUDIO_PLAYER_STATE_RUNNING. This process continues and the audio files are continuously played in a circular manner from theAppSdCardAudioCardFilesTable, one after the other.

14

Several other APIs are developed that provide information on the current state of the audio player to other state machines or tasks.

15

The macroAPP_SDCARD_AUDIO_CODEC_WRITE_QUEUE_SIZE contains the size of the CODEC driver buffer queue.

#defineAPP_SDCARD_AUDIO_CODEC_WRITE_QUEUE_SIZEQUEUE_SIZE_TX_IDX0

16

The macroAPP_SDCARD_AUDIO_CARD_MAX_DIRS defines the maximum number of folders that will be scanned for the audio files.

#defineAPP_SDCARD_AUDIO_CARD_MAX_DIRS20

17

The macroAPP_SDCARD_AUDIO_CARD_MAX_FILES defines the maximum number of files that will be saved.

#defineAPP_SDCARD_AUDIO_CARD_MAX_FILES500

18

The macrosDECODER_MAX_INPUT_BUFFER_SIZE andDECODER_MAX_OUTPUT_BUFFER_SIZE define the size of input and output buffers to the decoder respectively.

#defineDECODER_MAX_OUTPUT_BUFFER_SIZE1024 *12#defineDECODER_MAX_INPUT_BUFFER_SIZE1024 *20

1

Before we program and run our application, we need to program the micro SD card with the WAV audio files. Go to thedev_files folder of this exercise and copy a few sample WAV files to the micro SD card.

2

Insert the micro SD card into the micro SD card slot (J8) on the MEB II.

3

Before you start the debugger, you may want to set a breakpoint in the application file inapp_sdcard_audio_task.c to verify that important stages of the application (like the opening of the CODEC driver and mounting of the file system on the SD card) were executed successfully.

4

Put a breakpoint in theAPP_SDCARD_AUDIO_PLAYER_STATE_TRACK_CHANGE state which will indicate that an audio track is complete and the next track will be selected for playing.

5

6

Single step (by clickingF7) and observe the flow of control in the application state machine.

7

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.

8

Remove all break points and clickF5 to allow the application to run.

9

Connect a headphone to the HP Out connector on the MEB II and you should hear the audio track being played.

10

You may load more WAV audio files by switching to the USB SD card reader mode (by pressing the switchS1 on the MEB II). After loading, switch back to the player mode and you should hear the newly added audio tracks to the SD card.