1.1.2.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 AK4954. Answer Yes to all questions.
You should end up with a project graph that looks like this, after rearranging the boxes:
Click on the AK4954 Driver component (not AK4954 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 AK4954 is a Host (supplies I2S clocks) or a Client (MCU supplies I2S clocks).
Number of AK4954 Clients indicates the maximum number of clients that can be connected to the AK4954 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.
Microphone/Line Input selects which microphone or line input is selected, either:
Internal Mic (mounted on the AK4954 daughterboard)
External Mic Input
Line Input
If External Mic input or Line Input is selected, then the following option is provided:
• Ext Mic Gain in dB range 0(min) to 31(max)
If External Mic input is selected, then the following option is provided:
• Enable Microphone Bias should be checked if using an electret microphone.
You can also bring in the AK4954 Driver by itself, by double clicking AK4954 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 AK4954 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 AK4954 Codec Driver Library.
Description
This section lists the files that are available in the src folder of the AK4954 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/AK4954.
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_ak4954.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_ak4954.c | This file contains implementation of the AK4954 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 AK4954 Codec Driver Library depends on the following modules:
I2S Driver Library
I2C Driver Library
Library Interface
Client Setup Functions
| Name | Description |
|---|---|
| DRV_AK4954_Open | Opens the specified AK4954 driver instance and returns a handle to it. |
| DRV_AK4954_Close | Closes an opened-instance of the AK4954 driver |
| DRV_AK4954_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_AK4954_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_AK4954_BufferAddRead | Schedule a non-blocking driver read operation. |
| DRV_AK4954_BufferAddWrite | Schedule a non-blocking driver write operation. |
| DRV_AK4954_BufferAddWriteRead | Schedule a non-blocking driver write-read operation. |
| DRV_AK4954_ReadQueuePurge | Removes all buffer requests from the read queue. |
| DRV_AK4954_WriteQueuePurge | Removes all buffer requests from the write queue. |
Data Types and Constants
| Name | Description |
|---|---|
| DRV_AK4954_AUDIO_DATA_FORMAT | Identifies the Serial Audio data interface format. |
| DRV_AK4954_BUFFER_EVENT | Identifies the possible events that can result from a buffer add request. |
| DRV_AK4954_BUFFER_EVENT_HANDLER | Pointer to a AK4954 Driver Buffer Event handler function. |
| DRV_AK4954_BUFFER_HANDLE | Handle identifying a write buffer passed to the driver. |
| DRV_AK4954_CHANNEL | Identifies Left/Right Audio channel. |
| DRV_AK4954_COMMAND_EVENT_HANDLER | Pointer to a AK4954 Driver Command Event Handler function. |
| DRV_AK4954_DIGITAL_BLOCK_CONTROL | Identifies Bass-Boost Control function. |
| DRV_AK4954_INIT | Defines the data required to initialize or reinitialize the AK4954 driver. |
| DRV_AK4954_INT_EXT_MIC | Identifies the Mic input source. |
| DRV_AK4954_MIC | This is type DRV_AK4954_MIC. |
| DRV_AK4954_MONO_STEREO_MIC | Identifies the Mic input as Mono / Stereo. |
| SAMPLE_LENGTH | in bits |
| DRV_AK4954_AUDIO_DATA_FORMAT_I2S | for compatability with old code. |
| DRV_AK4954_BUFFER_HANDLE_INVALID | Definition of an invalid buffer handle. |
| DRV_AK4954_COUNT | Number of valid AK4954 driver index. |
| DRV_AK4954_INDEX_0 | AK4954 driver index definitions. |
| DRV_AK4954_INDEX_1 | This is macro DRV_AK4954_INDEX_1. |
| DRV_AK4954_INDEX_2 | This is macro DRV_AK4954_INDEX_2. |
| DRV_AK4954_INDEX_3 | This is macro DRV_AK4954_INDEX_3. |
| DRV_AK4954_INDEX_4 | This is macro DRV_AK4954_INDEX_4. |
| DRV_AK4954_INDEX_5 | This is macro DRV_AK4954_INDEX_5. |
Other Functions
| Name | Description |
|---|---|
| DRV_AK4954_LRCLK_Sync | Synchronize to the start of the I2S LRCLK (left/right clock) signal |
| DRV_AK4954_GetI2SDriver | Get the handle to the I2S driver for this codec instance. |
| DRV_AK4954_VersionStrGet | This function returns the version of AK4954 driver in string format. |
| DRV_AK4954_VersionGet | This function returns the version of AK4954 driver. |
Settings Functions
| Name | Description |
|---|---|
| DRV_AK4954_MicGainGet | This function gets the microphone gain for the AK4954 Codec. |
| DRV_AK4954_MicGainSet | This function sets the microphone gain for the AK4954 CODEC. |
| DRV_AK4954_MicMuteOff | Umutes th AK4954's microphone input. |
| DRV_AK4954_MicMuteOn | Mutes the AK4954's microphone input |
| DRV_AK4954_MicSet | This function sets up the codec for the internal or the AK4954 Mic1 or Mic2 input. |
| DRV_AK4954_MonoStereoMicSet | This function sets up the codec for the Mono or Stereo microphone mode. |
| DRV_AK4954_MuteOff | This function disables AK4954 output for soft mute. |
| DRV_AK4954_MuteOn | This function allows AK4954 output for soft mute on. |
| DRV_AK4954_IntExtMicSet | This function sets up the codec for the X32 DB internal or the external microphone use. |
| DRV_AK4954_SamplingRateGet | This function gets the sampling rate set on the DAC AK4954. |
| DRV_AK4954_SamplingRateSet | This function sets the sampling rate of the media stream. |
| DRV_AK4954_VolumeGet | This function gets the volume for AK4954 Codec. |
| DRV_AK4954_VolumeSet | This function sets the volume for AK4954 Codec. |
System Interaction Functions
| Name | Description |
|---|---|
| DRV_AK4954_Initialize | Initializes hardware and data for the instance of the AK4954 Codec module. |
| DRV_AK4954_EnableInitialization | Enable delayed initialization of the driver. |
| DRV_AK4954_IsInitializationDelayed | Checks if delayed initialization of the driver has been requested. |
| DRV_AK4954_Deinitialize | Deinitializes the specified instance of the AK4954 driver module. |
| DRV_AK4954_Status | Gets the current status of the AK4954 driver module. |
| DRV_AK4954_Tasks | Maintains the driver's control and data interface state machine. |