Step 5: Review the Application Code

Open the file app_sdcard_audio_task.h. This file defines application states, data, and Application Peripheral Interfaces (APIs).

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

The audio player states are shown in the accompanying image.

All of these enumerations should be self-explanatory.

The application data structure is shown in the accompanying image.

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

The audio player data structure is shown in the accompanying image.

The functionality of some of the important structure members is 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 to SYS_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. The buffer 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 to DRV_CODEC_BufferAddWrite().
• bufferSize: indicates the number of decoded audio data elements available in the buffer.
• currentSongIdx, nextSongIdx, and previousSongIdx: point to the 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 to SYS_FS_FileRead().
• currentFilesize: holds the total size of the current audio file pointed by the fileHandle.
• readIdx and wrriteIdx: are used to index into the buffer containing audio data for the audio CODEC. writeIdx points to the index until the decoded audio data is available in the buffer. 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 to DECODER_Decode().

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

The enum APP_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.

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

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

The function APP_SDCARD_AUDIO_Tasks implements the task’s state machine as shown in the figure in the Overview section. As in the previous lab, Lab 3: SD Card Reader Support to Load Audio Files with MPLAB® Harmony v3, it starts in the APP_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 the APP_SDCARD_AUDIO_STATE_CODEC_SET_BUFFER_HANDLER state, mounts the file system in the APP_SDCARD_AUDIO_CARD_MOUNT state, and sets the current drive in the APP_SDCARD_AUDIO_CARD_CURRENT_DRIVE_SET state.

The application then enters the APP_SDCARD_AUDIO_STATE_RUNNING state where it calls the APP_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 the AppSdCardAudioCardFilesTable. It also selects the first WAV file from the AppSdCardAudioCardFilesTable and a call to the APP_SDCARD_AUDIO_Card_OpenTrack function opens it for playing.

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

The CODEC driver calls the buffer event handler APP_SDCARD_AUDIO_BufferEventHandler (registered with the CODEC by a call to the DRV_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 sending a call to the DRV_CODEC_BufferAddWrite function.

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 to APP_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 the AppSdCardAudioCardFilesTable, and opens it for playing. The player state machine then changes back to APP_SDCARD_AUDIO_PLAYER_STATE_RUNNING. This process continues and the audio files are continuously played in a circular manner from the AppSdCardAudioCardFilesTable, one after the other.

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