Audio HAL

Abstraction layer for audio board hardware, serves as an interface between the user application and the hardware driver for specific audio board like ESP32 LyraT.

The API provides data structures to configure sampling rates of ADC and DAC signal conversion, data bit widths, I2C stream parameters, and selection of signal channels connected to ADC and DAC. It also contains several specific functions to e.g. initialize the audio board, audio_hal_init(), control the volume, audio_hal_get_volume() and audio_hal_set_volume().

API Reference

Functions

audio_hal_handle_t audio_hal_init(audio_hal_codec_config_t *audio_hal_conf, audio_hal_func_t *audio_hal_func)

Initialize media codec driver.

Note
If selected codec has already been installed, it’ll return the audio_hal handle.
Return
int, 0success, othersfail
Parameters
  • audio_hal_conf: Configure structure audio_hal_config_t
  • audio_hal_func: Structure containing functions used to operate audio the codec chip

esp_err_t audio_hal_deinit(audio_hal_handle_t audio_hal)

Uninitialize media codec driver.

Return
int, 0success, othersfail
Parameters
  • audio_hal: reference function pointer for selected audio codec

esp_err_t audio_hal_ctrl_codec(audio_hal_handle_t audio_hal, audio_hal_codec_mode_t mode, audio_hal_ctrl_t audio_hal_ctrl)

Start/stop codec driver.

Return
int, 0success, othersfail
Parameters
  • audio_hal: reference function pointer for selected audio codec
  • mode: select media hal codec mode either encode/decode/or both to start from audio_hal_codec_mode_t
  • audio_hal_ctrl: select start stop state for specific mode

esp_err_t audio_hal_codec_iface_config(audio_hal_handle_t audio_hal, audio_hal_codec_mode_t mode, audio_hal_codec_i2s_iface_t *iface)

Set codec I2S interface samples rate & bit width and format either I2S or PCM/DSP.

Return
  • 0 Success
  • -1 Error
Parameters
  • audio_hal: reference function pointer for selected audio codec
  • mode: select media hal codec mode either encode/decode/or both to start from audio_hal_codec_mode_t
  • iface: I2S sample rate (ex: 16000, 44100), I2S bit width (16, 24, 32),I2s format (I2S, PCM, DSP).

esp_err_t audio_hal_set_mute(audio_hal_handle_t audio_hal, bool mute)

Set voice mute. Enables or disables DAC mute of a codec.

Note
audio_hal_get_volume will still give a non-zero number in mute state. It will be set to that number when speaker is unmuted.
Return
int, 0success, othersfail
Parameters
  • audio_hal: reference function pointer for selected audio codec
  • mute: true/false. If true speaker will be muted and if false speaker will be unmuted.

esp_err_t audio_hal_set_volume(audio_hal_handle_t audio_hal, int volume)

Set voice volume.

Note
if volume is 0, mute is enabled,range is 0-100.
Return
int, 0success, othersfail
Parameters
  • audio_hal: reference function pointer for selected audio codec
  • volume: value of volume in percent(%)

esp_err_t audio_hal_get_volume(audio_hal_handle_t audio_hal, int *volume)

get voice volume.

Note
if volume is 0, mute is enabled, range is 0-100.
Return
int, 0success, othersfail
Parameters
  • audio_hal: reference function pointer for selected audio codec
  • volume: value of volume in percent returned(%)

Structures

struct audio_hal_codec_i2s_iface_t

I2s interface configuration for audio codec chip.

Public Members

audio_hal_iface_mode_t mode

audio codec chip mode

audio_hal_iface_format_t fmt

I2S interface format

audio_hal_iface_samples_t samples

I2S interface samples per second

audio_hal_iface_bits_t bits

i2s interface number of bits per sample

struct audio_hal_codec_config_t

Configure media hal for initialization of audio codec chip.

Public Members

audio_hal_adc_input_t adc_input

set adc channel

audio_hal_dac_output_t dac_output

set dac channel

audio_hal_codec_mode_t codec_mode

select codec mode: adc, dac or both

audio_hal_codec_i2s_iface_t i2s_iface

set I2S interface configuration

struct audio_hal

Configuration of functions and variables used to operate audio codec chip.

Public Members

esp_err_t (*audio_codec_initialize)(audio_hal_codec_config_t *codec_cfg)

initialize codec

esp_err_t (*audio_codec_deinitialize)(void)

deinitialize codec

esp_err_t (*audio_codec_ctrl)(audio_hal_codec_mode_t mode, audio_hal_ctrl_t ctrl_state)

control codec mode and state

esp_err_t (*audio_codec_config_iface)(audio_hal_codec_mode_t mode, audio_hal_codec_i2s_iface_t *iface)

configure i2s interface

esp_err_t (*audio_codec_set_mute)(bool mute)

set codec mute

esp_err_t (*audio_codec_set_volume)(int volume)

set codec volume

esp_err_t (*audio_codec_get_volume)(int *volume)

get codec volume

xSemaphoreHandle audio_hal_lock

semaphore of codec

void *handle

handle of audio codec

Macros

AUDIO_HAL_VOL_DEFAULT

Type Definitions

typedef struct audio_hal *audio_hal_handle_t
typedef struct audio_hal audio_hal_func_t

Configuration of functions and variables used to operate audio codec chip.

Enumerations

enum audio_hal_codec_mode_t

Select media hal codec mode.

Values:

AUDIO_HAL_CODEC_MODE_ENCODE = 1

select adc

AUDIO_HAL_CODEC_MODE_DECODE

select dac

AUDIO_HAL_CODEC_MODE_BOTH

select both adc and dac

AUDIO_HAL_CODEC_MODE_LINE_IN

set adc channel

enum audio_hal_adc_input_t

Select adc channel for input mic signal.

Values:

AUDIO_HAL_ADC_INPUT_LINE1 = 0x00

mic input to adc channel 1

AUDIO_HAL_ADC_INPUT_LINE2

mic input to adc channel 2

AUDIO_HAL_ADC_INPUT_ALL

mic input to both channels of adc

AUDIO_HAL_ADC_INPUT_DIFFERENCE

mic input to adc difference channel

enum audio_hal_dac_output_t

Select channel for dac output.

Values:

AUDIO_HAL_DAC_OUTPUT_LINE1 = 0x00

dac output signal to channel 1

AUDIO_HAL_DAC_OUTPUT_LINE2

dac output signal to channel 2

AUDIO_HAL_DAC_OUTPUT_ALL

dac output signal to both channels

enum audio_hal_ctrl_t

Select operating mode i.e. start or stop for audio codec chip.

Values:

AUDIO_HAL_CTRL_STOP = 0x00

set stop mode

AUDIO_HAL_CTRL_START = 0x01

set start mode

enum audio_hal_iface_mode_t

Select I2S interface operating mode i.e. master or slave for audio codec chip.

Values:

AUDIO_HAL_MODE_SLAVE = 0x00

set slave mode

AUDIO_HAL_MODE_MASTER = 0x01

set master mode

enum audio_hal_iface_samples_t

Select I2S interface samples per second.

Values:

AUDIO_HAL_08K_SAMPLES

set to 8k samples per second

AUDIO_HAL_11K_SAMPLES

set to 11.025k samples per second

AUDIO_HAL_16K_SAMPLES

set to 16k samples in per second

AUDIO_HAL_22K_SAMPLES

set to 22.050k samples per second

AUDIO_HAL_24K_SAMPLES

set to 24k samples in per second

AUDIO_HAL_32K_SAMPLES

set to 32k samples in per second

AUDIO_HAL_44K_SAMPLES

set to 44.1k samples per second

AUDIO_HAL_48K_SAMPLES

set to 48k samples per second

enum audio_hal_iface_bits_t

Select I2S interface number of bits per sample.

Values:

AUDIO_HAL_BIT_LENGTH_16BITS = 1

set 16 bits per sample

AUDIO_HAL_BIT_LENGTH_24BITS

set 24 bits per sample

AUDIO_HAL_BIT_LENGTH_32BITS

set 32 bits per sample

enum audio_hal_iface_format_t

Select I2S interface format for audio codec chip.

Values:

AUDIO_HAL_I2S_NORMAL = 0

set normal I2S format

AUDIO_HAL_I2S_LEFT

set all left format

AUDIO_HAL_I2S_RIGHT

set all right format

AUDIO_HAL_I2S_DSP

set dsp/pcm format