Purpose:
After completing this lab, you will have an understanding of how to configure and add theHarmony Universal Serial Bus (USB) Library for Mass Storage Device (MSD) class using theMPLAB® Harmony Configurator (MHC).
Overview:
This lab extendsaudio_player_lab2 by adding SD (Secure Digital) card reader functionality. Theaudio_player_lab3 application shows how to edit contents of an SD card. ThePIC32 Multimedia Expansion Board II is connected to a USB host, (typically a PC) and after a successful enumeration, the SD card is presented as a mass storage drive on the PC allowing you to add/delete contents.
You will add a new task to handle the USB device events for the SD card reader. Apart from registering a USB device layer events handler, the application need not intervene in the functionality of Mass Storage Device (MSD) Function driver since the MSD function driver does not provide any application callable functions.
You will also add a task to handle button (switch S1 on the MEB II Board) press events. Pressingswitch S1 will allow you to switch between the SD cardplayer mode and the SD cardreader mode. By default, the SD card player mode is selected and the application will read and play thetone.txt file (if present) on the SD card. When switch S1 is pressed, the device will act as an SD card reader allowing you to connect to the PC and load files (tone.txt for this lab) to the SD card.
For Lab3, you will be able to play audio data saved in atone.txt file by loading it through the USB interface.
For subsequent labs, you will be able to playWAV files by loading them to the SD card using the USB interface.
| App_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:
This lab builds off the work you performed in the previous lab. If you did not performSD card Audio Player Lab2, please start Lab3 using the Lab2 solution project (found under thefirmware folder). Verify it works as expected before continuing with this lab.
All steps must be completed before you will be ready to build, download, and run the application.
Lab Index
- Step 1 – Copy source files and rename project for Lab3.
- Step 2 – With MHC, Configure USB Library.
- Step 3 – Generate Harmony code.
- Step 4 – Include application-specific source files, add required code and build the project.
- Step 5 – Review the application code.
- Step 6 – Debug your application.
Step 1: Copy source files and rename project for Lab3
1
Create a new folderaudio_player_lab3 under
apps/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_lab2
to the newly created folder (audio_player_lab3).
3
Rename the project fromaudio_player_lab2 toaudio_player_lab3, because by the end of this session the lab will haveaudio_player_lab3 funcitonality. Openaudio_player_lab2.
4
UnderProjects, Right click onaudio_player_lab2 and selectRename…
5
In the popup window rename the lab fromaudio_player_lab2 toaudio_player_lab3.
The MPLAB X IDE renames the project. It closes the old projectaudio_player_lab2 and opens the renamed projectaudio_player_lab3.
6
.7
In the MPLAB X IDEProjects pane, right click onaudio_player_lab3 and selectSet as Main Project.
8
Open the MHC: In the MPLAB X IDE click on:Tools > Embedded > MPLAB Harmony Configurator.
Step 2: Configure the USB Library
1
Expand theHarmony Framework Configuration > USB Library selection tree.
a
Check theUse USB Stack? box.
b
Make sure theInterrupt Mode box is checked.
c
The MEB II Board will be acting as a USB device with the PC acting as the USB host. ExpandSelect Host or Device Stack and verify theUSB Device box is checked.
d
Set theNumber of Endpoints Used to 2. The MSD uses Bulk-Only Transport (BOT) protocol. This protocol uses one bulk endpoint for data from the host, one bulk endpoint for data going to the host and the control endpoint for other control-related transfers.
e
Make sure that theEndpoint 0 Buffer Size is set to 64. You will be using the USB in High-Speed mode which requires the endpoint buffer size to be set to 64.
f
Verify theUSB Device Instance 0 box is checked and expand this option. Note: Since there is only one USB peripheral on the device, there is only one USB instance. This is selected by default.
g
Verify that the device speed is set toUSB_SPEED_HIGH. PIC32MZ devices support full speed and high speed. Selecting high speed will allow the device to work at both full speed and high speed.
h
You will only need MSD functionality. Hence, theNumber of Functions Registered to this Device Instance must be left at 1.
i
Check theFunction 1 box and expand it.
j
TheDevice Class is set to MSD because you will be using the USB device as the interface to detect and access the SD card as a MSD on the PC.
k
Set the configuration value to which this function driver is tied. You will have only one configuration and hence retain the defaultConfiguration Value of 1.
l
Retain the defaultStart Interface Number at 0.
m
TheSpeed member of the entry specifies the device speeds for which this function driver should be initialized. This can be set to eitherUSB_SPEED_FULL,USB_SPEED_HIGH or a logical or a combination of both. The Device Layer will initialize the function if the device attaches speed matches the speed mentioned in the speed member of the entry. You will allow for both high speed and full speed operations and hence set it toUSB_SPEED_HIGH|USB_SPEED_FULL.
n
Verify theEndpoint Number is set to 1. This is the endpoint number to use for bulk data in and bulk data out operations.
o
Change theMax number of sectors to buffer to 8.This will allow up to 8 sectors to be buffered before a read/write operation is performed.
p
Retain theNumber of Logical Units to 1.
q
Check theLUN 0 box and expand it.
r
This application falls into the category of SD card reader. Set theMedia Type toSDCARD.
s
Verify theProduct ID Selection is set tomsd_basic_sdcard_demo. Retain the default values forEnter Vendor ID,Enter Product ID,Manufacturer String, andProduct String.
t
Make sure theSuspend in Sleep is unchecked. Retain the default priority settings forUSB Interrupt Priority,USB Interrupt Sub-priority,USB DMA Interrupt Priority, andUSB DMA Interrupt Sub-priority.
u
Keep the default value ofSYS_MODULE_POWER_RUN_FULL forPower State.
v
The following other options must be left unchecked:
EnableSOF Events
EnableSet Descriptor Events
EnableSync Frame Events
UseRemote Wakeup Feature
EnableBOS Descriptor Support
Enableadvanced String Descriptor Table
You have finished configuring the USB library for your application. Save the configuration.
2
Since the USB MSD class will be using the SD card media, you must increment the number of clients for the SD card driver to 2. One client will be the file system and the other will be the USB MSD class.
Expand theHarmony Framework Configuration > Drivers > SD Card > Use SD Card Driver? selection tree.
Change theNumber of SD Card Driver Clients to 2.
3
Save the MHC configuration by clicking the save button.
Step 3: Generate Harmony code
1
Click theGenerate Code button as shown in the following figure. Make sure theMerging Strategy selected isPrompt Merge For All User Changes.
2
Resolve code generation merge conflicts.
When theGenerate button is clicked, the MHC will modify and generate source files based on the options selected in the MHC. If the 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).
Note: Retain the below definitions in theCurrent File
3
Let’s examine what was done after generating code:
Theapp folder contains files related to your specific application. In the following steps, you will add your application code to the existingapp.c andapp.h files. You will also add other application-specific source files to the project. As you can see, no new (with respect to the previous lab) files have been added to theapp folder.
Also, note theSource Files/framework 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 theapp 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.
As you can see theusb folder has been added to thisframework folder. Also anotherusb folder has been added under theSource Files/framework/driver folder.
Step 4: Include application-specific source files, add required code and build the project
1
Copy source files into your project'sSource Files folder:
app_sdcard_reader_task.c
app_sdcard_reader_task.h
app_button_press_task.c
app_button_press_task.h
Copy them from this folder:
apps/training/middleware/audio_player/audio_player_lab3/dev_files
to this one:
apps/training/middleware/dev/audio_player/audio_player_lab3/firmware/src
2
Add the copied source files to your project.
- Addapp_sdcard_reader_task.c andapp_button_press_task.c to theSource Files/app folder (in the MPLAB X IDEProjects pane) by right clicking and selectingAdd Existing Items…
- Addapp_sdcard_reader_task.h andapp_button_press_task.h to theHeader Files/app folder by right clicking and selectingAdd Existing Items…
The files under the project should look like this:
3
Open theapp.c file and add the initialization routines for the SD card reader and button press tasks.
4
Modify theAPP_Tasks function to add the two newly added tasks, under theAPP_STATE_SERVICE_TASKS state.
Add two functions that will set and get the current mode of the application. This will execute either the player functionality implemented by theAPP_TONE_TEXTFILE_SDCARD_Tasks, or the SD card reader functionality implemented by theAPP_SDCARD_READER_Tasks.
5
Now, open theapp.h file and add the following enumeration. This will be used to manage the application modes.
6
Next, modify theAPP_DATA structure to include the application's mode related information.
7
Also, you need to expose the set and get mode functions to other tasks. Include the following declarations in theapp.h file.
8
Finally, openapp_tone_textfile_sdcard.c and add the following condition. This will ensure theAPP_TONE_TEXTFILE_SDCARD_Tasks function runs only when the audio playback mode is selected.
Note: You must also add the closing bracket for theif condition.
9
Save all the files before closing.
10
icon and verify that the project builds successfully.Step5: Review the Application code
Application File:app_tone_textfile_sdcard.c
This file remains the same as inaudio_player_lab2, except for the condition added above which makes sure thatAPP_TONE_TEXTFILE_SDCARD_Tasks runs only when the application is in Audio Player mode.
Application File:app_tone_textfile_sdcard.h
This file remains same as inaudio_player_lab2.
Application File:app_sdcard_reader_task.h
1
Open fileapp_sdcard_reader_task.h. This file defines application enums, data, and Application Programming Interfaces (APIs).
2
The below enumeration defines the states of the SD card reader task.
Only two states are needed as the entire functionality is handled by the USB MSD class driver.
3
The SD card reader data structure holds information on the USB device handle, current state of the task and whether the USB interface is detached or not.
Application File:app_sdcard_reader_task.c
4
Open fileapp_sdcard_reader_task.c. This file contains the SD card reader task initialization routine and the SD card task function.
5
TheAPP_SDCARD_READER_Initialize routine initializes the task to a known state.
6
The functionAPP_USBDeviceEventHandler notifies the application of USB MSD events.
7
The functionAPP_SDCARD_READER_Tasks opens the USB device and registers the USB device layer event handler. After this, the task enters the run state. From here on, the USB MSD driver handles all the events and there is really nothing that the application needs to handle for USB SD card read/write functionality.
8
The functionsAPP_SDCARD_READER_AttachDevice andAPP_SDCARD_READER_DetachDevice attaches and detaches the USB device respectively.
Application File:app_button_press_task.h
9
Open the fileapp_button_press_task.h. This file defines the enums, data, and APIs related to the button press task.
10
The enumAPP_BUTTON_PRESS_TASK_STATE helps maintain the states of the button task.
11
TheAPP_BUTTON_PRESS_TASK_DATA data structure holds the button task's state and button de-bounce related data.
Application File:app_button_press_task.c
12
Open the fileapp_button_press_task.c. This file initializes and runs the button press task.
13
The buttonPress Task uses the system timer service to implement de-bouncing. When the user presses the button, while the application is in Player mode, it suspends the audio streaming and un-mounts the file system. It then attaches the USB device and switches to the SD card reader mode. Similarly, when the user presses the button, while the application is in the SD card reader mode, the USB device is first detached, the tone text file SD card task is initialized and the application mode is switched back to SD card playback mode.
Step 6: Debug your Application
your third application.1
Before you program and run the application, delete thetone.txt file on the micro SD card. You will load thetone.txt file using the newly added SD card reader functionality.
2
Make sure that the micro SD card is inserted into the micro SD card slot (J8) on the MEB II board.
3
Connect a USB cable from the micro USB connector (J4) on the PIC32MZEF Starter Kit Board to the PC.
4
Connect a headphone to the HP Out connector on the Multimedia Expansion Board II.
5
Before you start the debugger, you may want to set a breakpoint in the application file inapp_button_press_task.c to verify that the application reads the button press and switches to the appropriate mode.
6
icon.7
The application boots in the SD Card Player mode. You will not be able to hear the tone as thetone.txt file was already deleted from the micro SD card.
8
Next, you will load thetone.txt file to the SD card from the PC. Press the switchS1 on the MEB II board. Verify that the breakpoint is hit and the Application mode is changed to SD card reader mode.
9
Remove all breakpoints, press KeyF5 and allow the application to run.
10
Wait for the PC to enumerate the USB MSD. Verify that the device appears as aRemovable Storage Device. On a Windows machine, do this by clicking on theMy Computer (orComputer) icon. Click on the drive and copy thetone.txt file.
11
Once thetone.txt file is copied, press theS1 button to go back to the Player mode. Plugin your earphones and you should be able to listen to the tone!
Results
You should be able to view and edit the contents of the micro SD card by connecting the device to the USB host (PC). You will also be able to switch between the audio player functionality and the SD card reader functionality through the press of a button.
Analysis
In this lab, you added USB MSD support using the MHC. You also demonstrated how the MHC is capable of handling multiple clients that access the same SD card media. At the application layer, you added a new task (state machine) to handle a button press event to allow the users to switch between the audio player and SD card reader modes.
Conclusions
You added USB SD card reader support, thereby bringing your application one step closer to a full-fledged audio player. The lab demonstrates how easily you can add USB MSD class functionality to your applications. It also shows that there is little to no application overhead when it comes to handling MSD class events, as all these events are handled by the USB library. Going forward, you may want to add USB host functionality to the device to read a file (e.g.,tone.txt or audio files) stored on a thumb-drive.
Table of Contents |
