1.1.4.2 Configuring MHC
Provides examples on how to configure the MPLAB Harmony Configurator (MHC) for a specific driver.
Description
When building a new application, start by creating a 32-bit MPLAB Harmony 3 project in MPLAB X IDE by selecting File > New Project. Chose the Configuration name the based on the BSP, and select the appropriate processor (such as ATSAME70Q21B).
In the MHC, under Available Components select the appropriate BSP, such as SAM E70 Xplained Ultra. Under Audio>Templates, double-click on a codec template such as WM8904. Answer Yes to all questions.
You should end up with a project graph that looks like this, after rearranging the boxes:
Click on the WM8904 Driver component (not WM8904 Codec) and the following menu will be displayed in the Configurations Options:
I2C Driver Used will display the driver instance used for the I2C interface.
I2S Driver Used will display the driver instance used for the I2S interface.
Usage Mode indicates whether the WM8904 is a Host (supplies I2S clocks) or a Client (MCU supplies I2S clocks).
Number of WM8904 Clients indicates the maximum number of clients that can be connected to the WM8904 Driver.
Sampling Rate indicates the number of samples per second per channel, 8000 to 96,000.
Volume indicates the volume in a linear scale from 0-255.
Audio Data Format is either 16-bit Left Justified, 16-bit I2S, 32-bit Left Justified, or 32-bit I2S. It must match the audio protocol and data length set up in either the SSC or I2S PLIB.
Sampling Rate indicates the number of samples per second per channel, 8000 to 96,000.
Enable Microphone Input should be checked a microphone is being used. If checked, another option,
Enable Microphone Bias should be checked if using an electret microphone.
You can also bring in the WM8904 Driver by itself, by double clicking WM8904 under Audio_->Driver->Codec_ in the Available Components list. You will then need to add any additional needed components manually and connect them together.
Note that the WM8904 requires the TCx Peripheral Library and TIME System Service in order to perform some of its internal timing sequences.
Building the Library
This section lists the files that are available in the WM8904 Codec Driver Library.
Description
This section lists the files that are available in the src folder of the WM8904 Codec Driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system.
The following three tables list and describe the header (.h) and source (.c) files that implement this library. The parent folder for these files is audio/driver/codec/WM8904.
Interface File(s)
This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library.
| Source File Name | Description |
|---|---|
| drv_wm8904.h | Header file that exports the driver API. |
Required File(s)
This table lists and describes the source and header files that must always be included in the MPLAB X IDE project to build this library.
| Source File Name | Description |
|---|---|
| /src/drv_wm8904.c | This file contains implementation of the WM8904 Codec Driver. |
Optional File(s)
This table lists and describes the source and header files that may optionally be included if required for the desired implementation.
| Source File Name | Description |
|---|---|
| N/A | No optional files are available for this library. |
Module Dependencies
The WM8904 Codec Driver Library depends on the following modules:
I2S Driver Library
I2C Driver Library
Library Interface
Client Setup Functions
| Name | Description |
|---|---|
| DRV_WM8904_Open | Opens the specified WM8904 driver instance and returns a handle to it |
| DRV_WM8904_Close | Closes an opened-instance of the WM8904 driver |
| DRV_WM8904_BufferEventHandlerSet | This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. |
| DRV_WM8904_CommandEventHandlerSet | This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. |
Data Transfer Functions
| Name | Description |
|---|---|
| DRV_WM8904_BufferAddRead | Schedule a non-blocking driver read operation. |
| DRV_WM8904_BufferAddWrite | Schedule a non-blocking driver write operation. |
| DRV_WM8904_BufferAddWriteRead | Schedule a non-blocking driver write-read operation. |
| DRV_WM8904_ReadQueuePurge | Removes all buffer requests from the read queue. |
| DRV_WM8904_WriteQueuePurge | Removes all buffer requests from the write queue. |
Data Types and Constants
| Name | Description |
|---|---|
| DATA_LENGTH | in bits |
| DRV_WM8904_AUDIO_DATA_FORMAT | Identifies the Serial Audio data interface format. |
| DRV_WM8904_BUFFER_EVENT | Identifies the possible events that can result from a buffer add request. |
| DRV_WM8904_BUFFER_EVENT_HANDLER | Pointer to a WM8904 Driver Buffer Event handler function. |
| DRV_WM8904_BUFFER_HANDLE | Handle identifying a write buffer passed to the driver. |
| DRV_WM8904_CHANNEL | Identifies Left/Right Audio channel. |
| DRV_WM8904_COMMAND_EVENT_HANDLER | Pointer to a WM8904 Driver Command Event Handler function. |
| DRV_WM8904_INIT | Defines the data required to initialize or reinitialize the WM8904 driver. |
| DRV_WM8904_BUFFER_HANDLE_INVALID | Definition of an invalid buffer handle. |
| DRV_WM8904_COUNT | Number of valid WM8904 driver index. |
| DRV_WM8904_INDEX_0 | WM8904 driver index definitions. |
| DRV_I2C_INDEX | This is macro DRV_I2C_INDEX. |
Other Functions
| Name | Description |
|---|---|
| DRV_WM8904_GetI2SDriver | Get the handle to the I2S driver for this codec instance. |
| DRV_WM8904_VersionGet | This function returns the version of WM8904 driver |
| DRV_WM8904_VersionStrGet | This function returns the version of WM8904 driver in string format. |
| DRV_WM8904_LRCLK_Sync | Synchronize to the start of the I2S LRCLK (left/right clock) signal |
Settings Functions
| Name | Description |
|---|---|
| DRV_WM8904_MuteOff | This function disables WM8904 output for soft mute. |
| DRV_WM8904_MuteOn | This function allows WM8904 output for soft mute on. |
| DRV_WM8904_SamplingRateGet | This function gets the sampling rate set on the WM8904. |
| DRV_WM8904_SamplingRateSet | This function sets the sampling rate of the media stream. |
| DRV_WM8904_VolumeGet | This function gets the volume for WM8904 Codec. |
| DRV_WM8904_VolumeSet | This function sets the volume for WM8904 Codec. |
System Interaction Functions
| Name | Description |
|---|---|
| DRV_WM8904_Initialize | Initializes hardware and data for the instance of the WM8904 DAC module |
| DRV_WM8904_Deinitialize | Deinitializes the specified instance of the WM8904 driver module |
| DRV_WM8904_Status | Gets the current status of the WM8904 driver module. |
| DRV_WM8904_Tasks | Maintains the driver's control and data interface state machine. |