Arduino AudioKit HAL
audio_hal.h
Go to the documentation of this file.
1 /*
2  * ESPRESSIF MIT License
3  *
4  * Copyright (c) 2018 <ESPRESSIF SYSTEMS (SHANGHAI) PTE LTD>
5  *
6  * Permission is hereby granted for use on all ESPRESSIF SYSTEMS products, in which case,
7  * it is free of charge, to any person obtaining a copy of this software and associated
8  * documentation files (the "Software"), to deal in the Software without restriction, including
9  * without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  * and/or sell copies of the Software, and to permit persons to whom the Software is furnished
11  * to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in all copies or
14  * substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
18  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
19  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
20  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22  *
23  */
24 
25 /*! \file */
26 
27 
28 #ifndef _AUDIO_HAL_H_
29 #define _AUDIO_HAL_H_
30 
31 #include "AudioKitSettings.h"
32 #include "audio_error.h"
33 
34 #ifdef AUDIOKIT_FREE_RTOS
35 #include "freertos/FreeRTOS.h"
36 #include "freertos/semphr.h"
37 #include "freertos/task.h"
38 #else
39 #define portTICK_PERIOD_MS 1
40 #define portTICK_RATE_MS portTICK_PERIOD_MS
41 typedef void* xSemaphoreHandle;
42 #endif
43 
44 #ifndef ESP32
45 #include <stdint.h>
46 #include <stdbool.h>
47 #include "audio_error.h"
48 
49 #endif
50 
51 
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
55 
56 
57 #define AUDIO_HAL_VOL_DEFAULT 20
58 #define ets_printf KIT_LOGI
59 
60 typedef struct audio_hal *audio_hal_handle_t;
61 
62 /**
63  * @brief Select media hal codec mode
64  */
65 typedef enum {
66  AUDIO_HAL_CODEC_MODE_ENCODE = 1, /*!< select adc */
67  AUDIO_HAL_CODEC_MODE_DECODE, /*!< select dac */
68  AUDIO_HAL_CODEC_MODE_BOTH, /*!< select both adc and dac */
69  AUDIO_HAL_CODEC_MODE_LINE_IN, /*!< set adc channel */
71 
72 /**
73  * @brief Select adc channel for input mic signal
74  */
75 typedef enum {
76  AUDIO_HAL_ADC_INPUT_LINE1 = 0x00, /*!< mic input to adc channel 1 */
77  AUDIO_HAL_ADC_INPUT_LINE2, /*!< mic input to adc channel 2 */
78  AUDIO_HAL_ADC_INPUT_ALL, /*!< mic input to both channels of adc */
79  AUDIO_HAL_ADC_INPUT_DIFFERENCE, /*!< mic input to adc difference channel */
81 
82 /**
83  * @brief Select channel for dac output
84  */
85 typedef enum {
86  AUDIO_HAL_DAC_OUTPUT_LINE1 = 0x00, /*!< dac output signal to channel 1 */
87  AUDIO_HAL_DAC_OUTPUT_LINE2, /*!< dac output signal to channel 2 */
88  AUDIO_HAL_DAC_OUTPUT_ALL, /*!< dac output signal to both channels */
90 
91 /**
92  * @brief Select operating mode i.e. start or stop for audio codec chip
93  */
94 typedef enum {
95  AUDIO_HAL_CTRL_STOP = 0x00, /*!< set stop mode */
96  AUDIO_HAL_CTRL_START = 0x01, /*!< set start mode */
98 
99 /**
100  * @brief Select I2S interface operating mode i.e. master or slave for audio codec chip
101  */
102 typedef enum {
103  AUDIO_HAL_MODE_SLAVE = 0x00, /*!< set slave mode */
104  AUDIO_HAL_MODE_MASTER = 0x01, /*!< set master mode */
106 
107 /**
108  * @brief Select I2S interface samples per second
109  */
110 typedef enum {
111  AUDIO_HAL_08K_SAMPLES, /*!< set to 8k samples per second */
112  AUDIO_HAL_11K_SAMPLES, /*!< set to 11.025k samples per second */
113  AUDIO_HAL_16K_SAMPLES, /*!< set to 16k samples in per second */
114  AUDIO_HAL_22K_SAMPLES, /*!< set to 22.050k samples per second */
115  AUDIO_HAL_24K_SAMPLES, /*!< set to 24k samples in per second */
116  AUDIO_HAL_32K_SAMPLES, /*!< set to 32k samples in per second */
117  AUDIO_HAL_44K_SAMPLES, /*!< set to 44.1k samples per second */
118  AUDIO_HAL_48K_SAMPLES, /*!< set to 48k samples per second */
120 
121 /**
122  * @brief Select I2S interface number of bits per sample
123  */
124 typedef enum {
125  AUDIO_HAL_BIT_LENGTH_16BITS = 1, /*!< set 16 bits per sample */
126  AUDIO_HAL_BIT_LENGTH_24BITS, /*!< set 24 bits per sample */
127  AUDIO_HAL_BIT_LENGTH_32BITS, /*!< set 32 bits per sample */
129 
130 /**
131  * @brief Select I2S interface format for audio codec chip
132  */
133 typedef enum {
134  AUDIO_HAL_I2S_NORMAL = 0, /*!< set normal I2S format */
135  AUDIO_HAL_I2S_LEFT, /*!< set all left format */
136  AUDIO_HAL_I2S_RIGHT, /*!< set all right format */
137  AUDIO_HAL_I2S_DSP, /*!< set dsp/pcm format */
139 
140 /**
141  * @brief I2s interface configuration for audio codec chip
142  */
143 typedef struct {
144  audio_hal_iface_mode_t mode; /*!< audio codec chip mode */
145  audio_hal_iface_format_t fmt; /*!< I2S interface format */
146  audio_hal_iface_samples_t samples; /*!< I2S interface samples per second */
147  audio_hal_iface_bits_t bits; /*!< i2s interface number of bits per sample */
149 
150 /**
151  * @brief Configure media hal for initialization of audio codec chip
152  */
153 typedef struct {
154  audio_hal_adc_input_t adc_input; /*!< set adc channel */
155  audio_hal_dac_output_t dac_output; /*!< set dac channel */
156  audio_hal_codec_mode_t codec_mode; /*!< select codec mode: adc, dac or both */
157  audio_hal_codec_i2s_iface_t i2s_iface; /*!< set I2S interface configuration */
159 
160 /**
161  * @brief Configuration of functions and variables used to operate audio codec chip
162  */
163 typedef struct audio_hal {
164  esp_err_t (*audio_codec_initialize)(audio_hal_codec_config_t *codec_cfg); /*!< initialize codec */
165  esp_err_t (*audio_codec_deinitialize)(void); /*!< deinitialize codec */
166  esp_err_t (*audio_codec_ctrl)(audio_hal_codec_mode_t mode, audio_hal_ctrl_t ctrl_state); /*!< control codec mode and state */
167  esp_err_t (*audio_codec_config_iface)(audio_hal_codec_mode_t mode, audio_hal_codec_i2s_iface_t *iface); /*!< configure i2s interface */
168  esp_err_t (*audio_codec_set_mute) (bool mute); /*!< set codec mute */
169  esp_err_t (*audio_codec_set_volume)(int volume); /*!< set codec volume */
170  esp_err_t (*audio_codec_get_volume)(int *volume); /*!< get codec volume */
171  xSemaphoreHandle audio_hal_lock; /*!< semaphore of codec */
172  void *handle; /*!< handle of audio codec */
174 
175 
176 
177 /**
178  *
179  * @brief Initialize media codec driver
180  *
181  * @note If selected codec has already been installed, it'll return the audio_hal handle.
182  *
183  * @param audio_hal_conf Configure structure audio_hal_config_t
184  * @param audio_hal_func Structure containing functions used to operate audio the codec chip
185  *
186  * @return int, 0--success, others--fail
187  */
189 
190 /**
191  * @brief Uninitialize media codec driver
192  *
193  * @param audio_hal reference function pointer for selected audio codec
194  *
195  * @return int, 0--success, others--fail
196  */
198 
199 /**
200  * @brief Start/stop codec driver
201  *
202  * @param audio_hal reference function pointer for selected audio codec
203  * @param mode select media hal codec mode either encode/decode/or both to start from audio_hal_codec_mode_t
204  * @param audio_hal_ctrl select start stop state for specific mode
205  *
206  * @return int, 0--success, others--fail
207  */
209 
210 /**
211  * @brief Set codec I2S interface samples rate & bit width and format either I2S or PCM/DSP.
212  *
213  * @param audio_hal reference function pointer for selected audio codec
214  * @param mode select media hal codec mode either encode/decode/or both to start from audio_hal_codec_mode_t
215  * @param iface I2S sample rate (ex: 16000, 44100), I2S bit width (16, 24, 32),I2s format (I2S, PCM, DSP).
216  *
217  * @return
218  * - 0 Success
219  * - -1 Error
220  */
222 
223 /**
224  * @brief Set voice mute. Enables or disables DAC mute of a codec.
225  * @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.
226  *
227  * @param audio_hal reference function pointer for selected audio codec
228  * @param mute true/false. If true speaker will be muted and if false speaker will be unmuted.
229  *
230  * @return int, 0--success, others--fail
231  */
233 
234 /**
235  * @brief Set voice volume.
236  * @note if volume is 0, mute is enabled,range is 0-100.
237  *
238  * @param audio_hal reference function pointer for selected audio codec
239  * @param volume value of volume in percent(%)
240  *
241  * @return int, 0--success, others--fail
242  */
244 
245 /**
246  * @brief get voice volume.
247  * @note if volume is 0, mute is enabled, range is 0-100.
248  *
249  * @param audio_hal reference function pointer for selected audio codec
250  * @param volume value of volume in percent returned(%)
251  *
252  * @return int, 0--success, others--fail
253  */
255 
256 
257 #ifdef __cplusplus
258 }
259 #endif
260 
261 #endif //__AUDIO_HAL_H__
AUDIOKIT_BOARD selects a specic board: 1) lyrat_v4_3 2) lyrat_v4_2 3) lyrat_mini_v1_1 4) esp32_s2_kal...
audio_hal_iface_format_t fmt
Definition: audio_hal.h:145
audio_hal_codec_mode_t
Select media hal codec mode.
Definition: audio_hal.h:65
@ AUDIO_HAL_CODEC_MODE_LINE_IN
Definition: audio_hal.h:69
@ AUDIO_HAL_CODEC_MODE_BOTH
Definition: audio_hal.h:68
@ AUDIO_HAL_CODEC_MODE_ENCODE
Definition: audio_hal.h:66
@ AUDIO_HAL_CODEC_MODE_DECODE
Definition: audio_hal.h:67
esp_err_t audio_hal_deinit(audio_hal_handle_t audio_hal)
Uninitialize media codec driver.
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.
audio_hal_iface_samples_t samples
Definition: audio_hal.h:146
audio_hal_iface_bits_t
Select I2S interface number of bits per sample.
Definition: audio_hal.h:124
@ AUDIO_HAL_BIT_LENGTH_24BITS
Definition: audio_hal.h:126
@ AUDIO_HAL_BIT_LENGTH_16BITS
Definition: audio_hal.h:125
@ AUDIO_HAL_BIT_LENGTH_32BITS
Definition: audio_hal.h:127
audio_hal_codec_mode_t codec_mode
Definition: audio_hal.h:156
audio_hal_iface_mode_t
Select I2S interface operating mode i.e. master or slave for audio codec chip.
Definition: audio_hal.h:102
@ AUDIO_HAL_MODE_MASTER
Definition: audio_hal.h:104
@ AUDIO_HAL_MODE_SLAVE
Definition: audio_hal.h:103
audio_hal_dac_output_t
Select channel for dac output.
Definition: audio_hal.h:85
@ AUDIO_HAL_DAC_OUTPUT_LINE1
Definition: audio_hal.h:86
@ AUDIO_HAL_DAC_OUTPUT_LINE2
Definition: audio_hal.h:87
@ AUDIO_HAL_DAC_OUTPUT_ALL
Definition: audio_hal.h:88
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.
audio_hal_adc_input_t
Select adc channel for input mic signal.
Definition: audio_hal.h:75
@ AUDIO_HAL_ADC_INPUT_ALL
Definition: audio_hal.h:78
@ AUDIO_HAL_ADC_INPUT_LINE2
Definition: audio_hal.h:77
@ AUDIO_HAL_ADC_INPUT_LINE1
Definition: audio_hal.h:76
@ AUDIO_HAL_ADC_INPUT_DIFFERENCE
Definition: audio_hal.h:79
audio_hal_adc_input_t adc_input
Definition: audio_hal.h:154
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.
audio_hal_iface_mode_t mode
Definition: audio_hal.h:144
audio_hal_iface_samples_t
Select I2S interface samples per second.
Definition: audio_hal.h:110
@ AUDIO_HAL_08K_SAMPLES
Definition: audio_hal.h:111
@ AUDIO_HAL_16K_SAMPLES
Definition: audio_hal.h:113
@ AUDIO_HAL_24K_SAMPLES
Definition: audio_hal.h:115
@ AUDIO_HAL_32K_SAMPLES
Definition: audio_hal.h:116
@ AUDIO_HAL_11K_SAMPLES
Definition: audio_hal.h:112
@ AUDIO_HAL_22K_SAMPLES
Definition: audio_hal.h:114
@ AUDIO_HAL_44K_SAMPLES
Definition: audio_hal.h:117
@ AUDIO_HAL_48K_SAMPLES
Definition: audio_hal.h:118
struct audio_hal audio_hal_func_t
Configuration of functions and variables used to operate audio codec chip.
audio_hal_dac_output_t dac_output
Definition: audio_hal.h:155
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.
audio_hal_iface_format_t
Select I2S interface format for audio codec chip.
Definition: audio_hal.h:133
@ AUDIO_HAL_I2S_LEFT
Definition: audio_hal.h:135
@ AUDIO_HAL_I2S_DSP
Definition: audio_hal.h:137
@ AUDIO_HAL_I2S_RIGHT
Definition: audio_hal.h:136
@ AUDIO_HAL_I2S_NORMAL
Definition: audio_hal.h:134
audio_hal_codec_i2s_iface_t i2s_iface
Definition: audio_hal.h:157
audio_hal_iface_bits_t bits
Definition: audio_hal.h:147
esp_err_t audio_hal_get_volume(audio_hal_handle_t audio_hal, int *volume)
get voice volume.
audio_hal_ctrl_t
Select operating mode i.e. start or stop for audio codec chip.
Definition: audio_hal.h:94
@ AUDIO_HAL_CTRL_START
Definition: audio_hal.h:96
@ AUDIO_HAL_CTRL_STOP
Definition: audio_hal.h:95
esp_err_t audio_hal_set_volume(audio_hal_handle_t audio_hal, int volume)
Set voice volume.
Configure media hal for initialization of audio codec chip.
Definition: audio_hal.h:153
I2s interface configuration for audio codec chip.
Definition: audio_hal.h:143
Configuration of functions and variables used to operate audio codec chip.
Definition: audio_hal.h:163
esp_err_t(* audio_codec_initialize)(audio_hal_codec_config_t *codec_cfg)
Definition: audio_hal.h:164
esp_err_t(* audio_codec_set_volume)(int volume)
Definition: audio_hal.h:169
esp_err_t(* audio_codec_set_mute)(bool mute)
Definition: audio_hal.h:168
xSemaphoreHandle audio_hal_lock
Definition: audio_hal.h:171
esp_err_t(* audio_codec_ctrl)(audio_hal_codec_mode_t mode, audio_hal_ctrl_t ctrl_state)
Definition: audio_hal.h:166
void * handle
Definition: audio_hal.h:172
esp_err_t(* audio_codec_deinitialize)(void)
Definition: audio_hal.h:165
esp_err_t(* audio_codec_config_iface)(audio_hal_codec_mode_t mode, audio_hal_codec_i2s_iface_t *iface)
Definition: audio_hal.h:167
esp_err_t(* audio_codec_get_volume)(int *volume)
Definition: audio_hal.h:170