1.1.3.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 Generic. Answer Yes to all questions.
You should end up with a project graph that looks like this, after rearranging the boxes:
Click on the Generic Driver component (not Generic 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.
Number of Generic Clients indicates the maximum number of clients that can be connected to the Generic 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
24-bit Left Justified (ADC), 24-bit Right-justified(DAC)
24-bit Left Justified (ADC), 16-bit Right-justified(DAC)
24-bit Left Justified (ADC), 24-bit Left-justified(DAC)
24/16-bit I2S
32-bit Left Justified (ADC), 32-bit Left-justified(DAC)
32-bit I2S
It must match the audio protocol and data length set up in either the SSC or I2S PLIB..
You can also bring in the Generic Driver by itself, by double clicking Generic 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 Generic 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 Generic Codec Driver Library.
Description
This section lists the files that are available in the src folder of the Generic 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/Generic.
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_genericcodec.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_genericcodec.c | This file contains implementation of the Generic 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 Generic Codec Driver Library depends on the following modules:
I2S Driver Library
I2C Driver Library
Library Interface
Client Setup Functions
| Name | Description |
|---|---|
| DRV_GENERICCODEC_Open | Opens the specified Generic Codec driver instance and returns a handle to it |
| DRV_GENERICCODEC_Close | Closes an opened-instance of the Generic Codec driver |
| DRV_GENERICCODEC_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_GENERICCODEC_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 Types and Constants
| Name | Description |
|---|---|
| DRV_GENERICCODEC_BUFFER_EVENT | Identifies the possible events that can result from a buffer add request. |
| DRV_GENERICCODEC_BUFFER_EVENT_HANDLER | Pointer to a Generic Codec Driver Buffer Event handler function. |
| DRV_GENERICCODEC_BUFFER_HANDLE | Handle identifying a write buffer passed to the driver. |
| DRV_GENERICCODEC_CHANNEL | Identifies Left/Right Audio channel. |
| DRV_GENERICCODEC_COMMAND_EVENT_HANDLER | Pointer to a Generic Codec Driver Command Event Handler function. |
| DRV_GENERICCODEC_INIT | Defines the data required to initialize or reinitialize the Generic Codec driver. |
| DRV_GENERICCODEC_BUFFER_HANDLE_INVALID | Definition of an invalid buffer handle. |
| DRV_GENERICCODEC_COUNT | Number of valid Generic Codec driver index. |
| DRV_GENERICCODEC_INDEX_0 | Generic Codec driver index definitions. |
| DRV_GENERICCODEC_INDEX_1 | This is macro DRV_GENERICCODEC_INDEX_1. |
| DRV_GENERICCODEC_INDEX_2 | This is macro DRV_GENERICCODEC_INDEX_2. |
| DRV_GENERICCODEC_INDEX_3 | This is macro DRV_GENERICCODEC_INDEX_3. |
| DRV_GENERICCODEC_INDEX_4 | This is macro DRV_GENERICCODEC_INDEX_4. |
| DRV_GENERICCODEC_INDEX_5 | This is macro DRV_GENERICCODEC_INDEX_5. |
| DRV_GENERICCODEC_AUDIO_DATA_FORMAT | Identifies the Serial Audio data interface format. |
Data Transfer Functions
| Name | Description |
|---|---|
| DRV_GENERICCODEC_BufferAddRead | Schedule a non-blocking driver read operation. |
| DRV_GENERICCODEC_BufferAddWrite | Schedule a non-blocking driver write operation. |
| DRV_GENERICCODEC_BufferAddWriteRead | Schedule a non-blocking driver write-read operation. |
| DRV_GENERICCODEC_ReadQueuePurge | Removes all buffer requests from the read queue. |
| DRV_GENERICCODEC_WriteQueuePurge | Removes all buffer requests from the write queue. |
Other Functions
| Name | Description |
|---|---|
| DRV_GENERICCODEC_GetI2SDriver | Get the handle to the I2S driver for this codec instance. |
| DRV_GENERICCODEC_LRCLK_Sync | Synchronize to the start of the I2S LRCLK (left/right clock) signal |
Settings Functions
| Name | Description |
|---|---|
| DRV_GENERICCODEC_MicGainGet | This function gets the microphone gain for the Generic Codec. |
| DRV_GENERICCODEC_MicGainSet | This function sets the microphone gain for the Generic Codec CODEC. |
| DRV_GENERICCODEC_MicMuteOff | Umutes th Generic Codec's microphone input. |
| DRV_GENERICCODEC_MicMuteOn | Mutes the Generic Codec's microphone input |
| DRV_GENERICCODEC_MuteOff | This function disables Generic Codec output for soft mute. |
| DRV_GENERICCODEC_MuteOn | This function allows Generic Codec output for soft mute on. |
| DRV_GENERICCODEC_SamplingRateGet | This function gets the sampling rate set on the Generic Codec. |
| DRV_GENERICCODEC_SamplingRateSet | This function sets the sampling rate of the media stream. |
| DRV_GENERICCODEC_VersionGet | This function returns the version of Generic Codec driver |
| DRV_GENERICCODEC_VersionStrGet | This function returns the version of Generic Codec driver in string format. |
| DRV_GENERICCODEC_VolumeGet | This function gets the volume for Generic Codec. |
| DRV_GENERICCODEC_VolumeSet | This function sets the volume for Generic Codec. |
System Interaction Functions
| Name | Description |
|---|---|
| DRV_GENERICCODEC_Initialize | Initializes hardware and data for the instance of the Generic Codec module |
| DRV_GENERICCODEC_Deinitialize | Deinitializes the specified instance of the Generic Codec driver module |
| DRV_GENERICCODEC_Status | Gets the current status of the Generic Codec driver module. |
| DRV_GENERICCODEC_Tasks | Maintains the driver's control and data interface state machine. |