ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
i2s_audio_microphone.cpp
Go to the documentation of this file.
2
3#ifdef USE_ESP32
4
5#include <driver/i2s_std.h>
6#include <driver/i2s_pdm.h>
7#include <esp_timer.h>
8
9#include "esphome/core/hal.h"
10#include "esphome/core/log.h"
11
13
14#include "capture_time.h"
15
16#include <algorithm>
17
18namespace esphome::i2s_audio {
19
20static const UBaseType_t MAX_LISTENERS = 16;
21
22static const uint32_t READ_DURATION_MS = 16;
23
24static constexpr uint32_t DMA_BUFFERS_COUNT = 4;
25static constexpr uint32_t DMA_FRAME_NUM = 256;
26
27static const size_t TASK_STACK_SIZE = 4096;
28static const ssize_t TASK_PRIORITY = 23;
29
30ESPHOME_LOG_TAG(TAG, "i2s_audio.microphone");
31
33 COMMAND_STOP = (1 << 0), // stops the microphone task, set and cleared by ``loop``
34
35 TASK_STARTING = (1 << 10), // set by mic task, cleared by ``loop``
36 TASK_RUNNING = (1 << 11), // set by mic task, cleared by ``loop``
37 TASK_STOPPED = (1 << 13), // set by mic task, cleared by ``loop``
38
39 ALL_BITS = 0x00FFFFFF, // All valid FreeRTOS event group bits
40};
41
43 this->active_listeners_semaphore_ = xSemaphoreCreateCounting(MAX_LISTENERS, MAX_LISTENERS);
44 if (this->active_listeners_semaphore_ == nullptr) {
45 ESP_LOGE(TAG, "Creating semaphore failed");
46 this->mark_failed();
47 return;
48 }
49
50 this->event_group_ = xEventGroupCreate();
51 if (this->event_group_ == nullptr) {
52 ESP_LOGE(TAG, "Creating event group failed");
53 this->mark_failed();
54 return;
55 }
56
57#ifdef USE_I2S_AUDIO_FULL_DUPLEX
58 if (this->parent_->is_full_duplex() && this->parent_->is_failed()) {
59 this->mark_failed(LOG_STR("Full duplex bus setup failed"));
60 return;
61 }
62#endif
63
65}
66
68 ESP_LOGCONFIG(TAG,
69 "Microphone:\n"
70 " Pin: %d\n"
71 " PDM: %s\n"
72 " DC offset correction: %s",
73 static_cast<int8_t>(this->din_pin_), YESNO(this->pdm_), YESNO(this->correct_dc_offset_));
74}
75
77 uint8_t channel_count = 1;
78 uint8_t bits_per_sample = 16;
79 if (this->slot_bit_width_ != I2S_SLOT_BIT_WIDTH_AUTO) {
80 bits_per_sample = this->slot_bit_width_;
81 }
82
83 if (this->slot_mode_ == I2S_SLOT_MODE_STEREO) {
84 channel_count = 2;
85 }
86
87#ifdef USE_ESP32_VARIANT_ESP32
88 // ESP32 reads audio aligned to a multiple of 2 bytes. For example, if configured for 24 bits per sample, then it will
89 // produce 32 bits per sample, where the actual data is in the most significant bits. Other ESP32 variants produce 24
90 // bits per sample in this situation.
91 if (bits_per_sample < 16) {
92 bits_per_sample = 16;
93 } else if ((bits_per_sample > 16) && (bits_per_sample <= 32)) {
94 bits_per_sample = 32;
95 }
96#endif
97
98 if (this->pdm_) {
99 bits_per_sample = 16; // PDM mics are always 16 bits per sample
100 }
101
102 this->audio_stream_info_ = audio::AudioStreamInfo(bits_per_sample, channel_count, this->sample_rate_);
103}
104
106 if (!this->is_ready())
107 return;
108
109 xSemaphoreTake(this->active_listeners_semaphore_, 0);
110}
111
112void I2SAudioMicrophone::build_std_config_(i2s_std_config_t &std_cfg) const {
113 i2s_std_slot_config_t std_slot_cfg =
114 I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG((i2s_data_bit_width_t) this->slot_bit_width_, this->slot_mode_);
115 std_slot_cfg.slot_bit_width = this->slot_bit_width_;
116 std_slot_cfg.slot_mask = this->std_slot_mask_;
117
118 i2s_std_gpio_config_t pin_config = this->parent_->get_pin_config();
119 pin_config.din = this->din_pin_;
120
121 std_cfg = {
122 .clk_cfg =
123 {
124 .sample_rate_hz = this->sample_rate_,
125 .clk_src = this->get_clock_source_(),
126 .mclk_multiple = this->mclk_multiple_,
127 },
128 .slot_cfg = std_slot_cfg,
129 .gpio_cfg = pin_config,
130 };
131}
132
133#ifdef USE_I2S_AUDIO_FULL_DUPLEX
134void I2SAudioMicrophone::build_full_duplex_config(i2s_std_config_t &std_cfg) { this->build_std_config_(std_cfg); }
135
136void I2SAudioMicrophone::full_duplex_rx_enabling(i2s_chan_handle_t rx_handle, uint32_t dma_desc_num) {
137 // A failure only loses capture times; the speaker may still need RX enabled, so it is not passed on
138 this->start_capture_count_(rx_handle, dma_desc_num);
139}
140#endif
141
142bool I2SAudioMicrophone::start_capture_count_(i2s_chan_handle_t rx_handle, uint32_t dma_desc_num) {
143 // Neither the interrupt nor the mic task runs while the channel is disabled
144 this->dma_bytes_received_ = 0;
145 this->dma_buffers_dropped_.store(0, std::memory_order_relaxed);
146 this->dma_receive_time_us_ = 0;
147 this->dma_bytes_read_ = 0;
148 this->dma_desc_num_ = dma_desc_num;
149 const i2s_event_callbacks_t callbacks = {
150 .on_recv = i2s_on_recv_cb,
151 .on_recv_q_ovf = i2s_on_recv_q_ovf_cb,
152 };
153 esp_err_t err = i2s_channel_register_event_callback(rx_handle, &callbacks, this);
154 if (err != ESP_OK) {
155 ESP_LOGE(TAG, "Registering callbacks failed: %s", esp_err_to_name(err));
156 return false;
157 }
158 return true;
159}
160
161bool I2SAudioMicrophone::read_dma_buffer_size_() {
162 i2s_chan_info_t chan_info{};
163 esp_err_t err = i2s_channel_get_info(this->rx_handle_, &chan_info);
164 if ((err != ESP_OK) || (chan_info.total_dma_buf_size == 0) || (this->dma_desc_num_ == 0)) {
165 ESP_LOGE(TAG, "Getting the DMA buffer size failed");
166 return false;
167 }
168 this->dma_buffer_bytes_ = chan_info.total_dma_buf_size / this->dma_desc_num_;
169 return true;
170}
171
172bool I2SAudioMicrophone::start_driver_() {
173#ifdef USE_I2S_AUDIO_FULL_DUPLEX
174 if (this->parent_->is_full_duplex()) {
175 this->rx_handle_ = this->parent_->acquire_rx_channel();
176 if (this->rx_handle_ == nullptr) {
177 ESP_LOGE(TAG, "Full duplex channel unavailable");
178 return false;
179 }
181 return this->read_dma_buffer_size_();
182 }
183#endif
184
185 if (!this->parent_->try_lock()) {
186 return false; // Waiting for another i2s to return lock
187 }
188 this->locked_driver_ = true;
189 esp_err_t err;
190
191 i2s_chan_config_t chan_cfg = {
192 .id = this->parent_->get_port(),
193 .role = this->i2s_role_,
194 .dma_desc_num = DMA_BUFFERS_COUNT,
195 .dma_frame_num = DMA_FRAME_NUM,
196 .auto_clear = false,
197 };
198 /* Allocate a new RX channel and get the handle of this channel */
199 err = i2s_new_channel(&chan_cfg, NULL, &this->rx_handle_);
200 if (err != ESP_OK) {
201 ESP_LOGE(TAG, "Error creating channel: %s", esp_err_to_name(err));
202 return false;
203 }
204
205#if SOC_I2S_SUPPORTS_PDM_RX
206 if (this->pdm_) {
207 i2s_std_gpio_config_t pin_config = this->parent_->get_pin_config();
208 i2s_pdm_rx_clk_config_t clk_cfg = {
209 .sample_rate_hz = this->sample_rate_,
210 .clk_src = this->get_clock_source_(),
211 .mclk_multiple = this->mclk_multiple_,
212 .dn_sample_mode = this->pdm_dsr_,
213 };
214
215 i2s_pdm_rx_slot_config_t slot_cfg = I2S_PDM_RX_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, this->slot_mode_);
216 switch (this->std_slot_mask_) {
217 case I2S_STD_SLOT_LEFT:
218 slot_cfg.slot_mask = I2S_PDM_SLOT_LEFT;
219 break;
220 case I2S_STD_SLOT_RIGHT:
221 slot_cfg.slot_mask = I2S_PDM_SLOT_RIGHT;
222 break;
223 case I2S_STD_SLOT_BOTH:
224 slot_cfg.slot_mask = I2S_PDM_SLOT_BOTH;
225 break;
226 }
227
228 /* Init the channel into PDM RX mode */
229 i2s_pdm_rx_config_t pdm_rx_cfg = {
230 .clk_cfg = clk_cfg,
231 .slot_cfg = slot_cfg,
232 .gpio_cfg =
233 {
234 .clk = pin_config.ws,
235 .din = this->din_pin_,
236 .invert_flags =
237 {
238 .clk_inv = pin_config.invert_flags.ws_inv,
239 },
240 },
241 };
242 err = i2s_channel_init_pdm_rx_mode(this->rx_handle_, &pdm_rx_cfg);
243 } else
244#endif
245 {
246 i2s_std_config_t std_cfg;
247 this->build_std_config_(std_cfg);
248 /* Initialize the channel */
249 err = i2s_channel_init_std_mode(this->rx_handle_, &std_cfg);
250 }
251 if (err != ESP_OK) {
252 ESP_LOGE(TAG, "Error initializing channel: %s", esp_err_to_name(err));
253 return false;
254 }
255
256 if (!this->start_capture_count_(this->rx_handle_, DMA_BUFFERS_COUNT)) {
257 return false;
258 }
259
260 /* Before reading data, start the RX channel first */
261 err = i2s_channel_enable(this->rx_handle_);
262 if (err != ESP_OK) {
263 ESP_LOGE(TAG, "Enabling failed: %s", esp_err_to_name(err));
264 return false;
265 }
266
267 this->configure_stream_settings_(); // redetermine the settings in case some settings were changed after compilation
268
269 return this->read_dma_buffer_size_();
270}
271
273 if (!this->is_ready())
274 return;
275
276 // Not gated on state_: a start() that loop() has not acted on yet must be given back too
277 xSemaphoreGive(this->active_listeners_semaphore_);
278}
279
280void I2SAudioMicrophone::stop_driver_() {
281 // There is no harm continuing to unload the driver if an error is ever returned by the various functions. This
282 // ensures that we stop/unload the driver when it only partially starts.
283
284#ifdef USE_I2S_AUDIO_FULL_DUPLEX
285 if (this->parent_->is_full_duplex()) {
286 // The parent owns the channel pair, so only hand the RX channel back
287 if (this->rx_handle_ != nullptr) {
288 this->parent_->release_rx_channel();
289 this->rx_handle_ = nullptr;
290 }
291 return;
292 }
293#endif
294
295 esp_err_t err;
296 if (this->rx_handle_ != nullptr) {
297 /* Have to stop the channel before deleting it */
298 err = i2s_channel_disable(this->rx_handle_);
299 if (err != ESP_OK) {
300 ESP_LOGW(TAG, "Error stopping: %s", esp_err_to_name(err));
301 }
302 /* If the handle is not needed any more, delete it to release the channel resources */
303 err = i2s_del_channel(this->rx_handle_);
304 if (err != ESP_OK) {
305 ESP_LOGW(TAG, "Error deleting channel: %s", esp_err_to_name(err));
306 }
307 this->rx_handle_ = nullptr;
308 }
309 if (this->locked_driver_) {
310 this->parent_->unlock();
311 this->locked_driver_ = false;
312 }
313}
314
316 I2SAudioMicrophone *this_microphone = (I2SAudioMicrophone *) params;
317 xEventGroupSetBits(this_microphone->event_group_, MicrophoneEventGroupBits::TASK_STARTING);
318
319 { // Ensures the samples vector is freed when the task stops
320
321 // Copied so the format cannot change while the task runs
322 const audio::AudioStreamInfo stream_info = this_microphone->audio_stream_info_;
323 if (this_microphone->correct_dc_offset_) {
324 this_microphone->dc_offset_filter_.reset(stream_info.get_sample_rate());
325 }
326
327 // Read whole DMA buffers. When its queue is nearly full, the driver discards the unread rest of a buffer it is
328 // partway through without reporting it, which would throw off the capture time count.
329 const size_t dma_buffer_bytes = this_microphone->dma_buffer_bytes_;
330 const size_t bytes_to_read =
331 std::max<size_t>(1, (stream_info.ms_to_bytes(READ_DURATION_MS) + dma_buffer_bytes / 2) / dma_buffer_bytes) *
332 dma_buffer_bytes;
333 const uint32_t read_duration_ms =
334 (stream_info.bytes_to_frames(bytes_to_read) * 1000 + stream_info.get_sample_rate() - 1) /
335 stream_info.get_sample_rate();
336 std::vector<uint8_t> samples;
337 samples.reserve(bytes_to_read);
338
339 xEventGroupSetBits(this_microphone->event_group_, MicrophoneEventGroupBits::TASK_RUNNING);
340
341 while (!(xEventGroupGetBits(this_microphone->event_group_) & MicrophoneEventGroupBits::COMMAND_STOP)) {
342 if (this_microphone->has_data_callbacks_()) {
343 const uint32_t drops_before_read = this_microphone->dma_buffers_dropped_.load(std::memory_order_relaxed);
344
345 samples.resize(bytes_to_read);
346 size_t bytes_read = this_microphone->read_(samples.data(), bytes_to_read, 2 * read_duration_ms);
347 if (bytes_read == 0) {
348 continue;
349 }
350
351 portENTER_CRITICAL(&this_microphone->dma_lock_);
352 const uint32_t bytes_received = this_microphone->dma_bytes_received_;
353 const uint32_t drops = this_microphone->dma_buffers_dropped_.load(std::memory_order_relaxed);
354 const int64_t receive_time_us = this_microphone->dma_receive_time_us_;
355 portEXIT_CRITICAL(&this_microphone->dma_lock_);
356
357 const int64_t capture_time_us = dma_capture_time_us(
358 bytes_received, drops, drops_before_read, receive_time_us, this_microphone->dma_bytes_read_, bytes_read,
359 this_microphone->dma_desc_num_, dma_buffer_bytes, stream_info);
360 this_microphone->dma_bytes_read_ += bytes_read;
361
362 samples.resize(bytes_read);
363 if (this_microphone->correct_dc_offset_) {
364 this_microphone->dc_offset_filter_.process(samples.data(), samples.size(), stream_info);
365 }
366 this_microphone->publish_audio_(samples, stream_info, capture_time_us);
367 } else {
368 vTaskDelay(pdMS_TO_TICKS(READ_DURATION_MS));
369 }
370 }
371 }
372
373 xEventGroupSetBits(this_microphone->event_group_, MicrophoneEventGroupBits::TASK_STOPPED);
374 while (true) {
375 // Continuously delay until the loop method deletes the task
376 vTaskDelay(pdMS_TO_TICKS(10));
377 }
378}
379
380bool IRAM_ATTR I2SAudioMicrophone::i2s_on_recv_cb(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx) {
381 const int64_t now = esp_timer_get_time();
382 auto *this_microphone = static_cast<I2SAudioMicrophone *>(user_ctx);
383 portENTER_CRITICAL_ISR(&this_microphone->dma_lock_);
384 this_microphone->dma_bytes_received_ += event->size;
385 this_microphone->dma_receive_time_us_ = now;
386 portEXIT_CRITICAL_ISR(&this_microphone->dma_lock_);
387 return false;
388}
389
390bool IRAM_ATTR I2SAudioMicrophone::i2s_on_recv_q_ovf_cb(i2s_chan_handle_t handle, i2s_event_data_t *event,
391 void *user_ctx) {
392 auto *this_microphone = static_cast<I2SAudioMicrophone *>(user_ctx);
393 // A load and a store rather than fetch_add, which is not a hardware instruction on every variant
394 this_microphone->dma_buffers_dropped_.store(this_microphone->dma_buffers_dropped_.load(std::memory_order_relaxed) + 1,
395 std::memory_order_relaxed);
396 return false;
397}
398
399size_t I2SAudioMicrophone::read_(uint8_t *buf, size_t len, uint32_t timeout_ms) {
400 size_t bytes_read = 0;
401 esp_err_t err = i2s_channel_read(this->rx_handle_, buf, len, &bytes_read, timeout_ms);
402 if ((err != ESP_OK) && ((err != ESP_ERR_TIMEOUT) || (timeout_ms != 0))) {
403 // Ignore ESP_ERR_TIMEOUT if timeout_ms = 0, as it will read the data on the next call
404 if (!this->status_has_warning()) {
405 // Avoid spamming the logs with the error message if its repeated
406 ESP_LOGW(TAG, "Read error: %s", esp_err_to_name(err));
407 }
408 this->status_set_warning();
409 } else if ((bytes_read == 0) && (timeout_ms > 0)) {
410 this->status_set_warning();
411 } else {
412 this->status_clear_warning();
413 }
414 // Even after an error, any bytes read have left the DMA buffers and are valid audio
415#ifdef USE_ESP32_VARIANT_ESP32
416 // For ESP32 16-bit standard mono mode, adjacent samples need to be swapped.
417 if (this->slot_mode_ == I2S_SLOT_MODE_MONO && this->slot_bit_width_ == I2S_SLOT_BIT_WIDTH_16BIT && !this->pdm_) {
418 int16_t *samples = reinterpret_cast<int16_t *>(buf);
419 size_t sample_count = bytes_read / sizeof(int16_t);
420 for (size_t i = 0; i + 1 < sample_count; i += 2) {
421 int16_t tmp = samples[i];
422 samples[i] = samples[i + 1];
423 samples[i + 1] = tmp;
424 }
425 }
426#endif
427 return bytes_read;
428}
429
431 uint32_t event_group_bits = xEventGroupGetBits(this->event_group_);
432
433 if (event_group_bits & MicrophoneEventGroupBits::TASK_STARTING) {
434 ESP_LOGV(TAG, "Task started, attempting to allocate buffer");
435 xEventGroupClearBits(this->event_group_, MicrophoneEventGroupBits::TASK_STARTING);
436 }
437
438 if (event_group_bits & MicrophoneEventGroupBits::TASK_RUNNING) {
439 ESP_LOGV(TAG, "Task is running and reading data");
440
441 xEventGroupClearBits(this->event_group_, MicrophoneEventGroupBits::TASK_RUNNING);
443 }
444
445 if ((event_group_bits & MicrophoneEventGroupBits::TASK_STOPPED)) {
446 ESP_LOGV(TAG, "Task finished, freeing resources and uninstalling driver");
447
448 vTaskDelete(this->task_handle_);
449 this->task_handle_ = nullptr;
450 this->stop_driver_();
451 xEventGroupClearBits(this->event_group_, ALL_BITS);
452 this->status_clear_error();
453
455 }
456
457 // Start the microphone if any semaphores are taken
458 if ((uxSemaphoreGetCount(this->active_listeners_semaphore_) < MAX_LISTENERS) &&
461 }
462
463 // Stop the microphone if all semaphores are returned
464 if ((uxSemaphoreGetCount(this->active_listeners_semaphore_) == MAX_LISTENERS) &&
467 }
468
469 switch (this->state_) {
471 if (this->status_has_error()) {
472 break;
473 }
474
475 if (!this->start_driver_()) {
476 ESP_LOGE(TAG, "Driver failed to start; retrying in 1 second");
477 this->status_momentary_error(1000);
478 this->stop_driver_(); // Stop/frees whatever possibly started
479 break;
480 }
481
482 if (this->task_handle_ == nullptr) {
483 xTaskCreate(I2SAudioMicrophone::mic_task, "mic_task", TASK_STACK_SIZE, (void *) this, TASK_PRIORITY,
484 &this->task_handle_);
485
486 if (this->task_handle_ == nullptr) {
487 ESP_LOGE(TAG, "Task failed to start, retrying in 1 second");
488 this->status_momentary_error(1000);
489 this->stop_driver_(); // Stops the driver to return the lock; will be reloaded in next attempt
490 }
491 }
492
493 break;
495 break;
497 xEventGroupSetBits(this->event_group_, MicrophoneEventGroupBits::COMMAND_STOP);
498 break;
500 break;
501 }
502}
503
504} // namespace esphome::i2s_audio
505
506#endif // USE_ESP32
void mark_failed()
Mark this component as failed.
void status_clear_error()
Definition component.h:315
bool is_ready() const
bool status_has_warning() const
Definition component.h:293
bool status_has_error() const
Definition component.h:295
void status_momentary_error(uint32_t length=5000)
Set error status flag and clear it after length ms.
void status_clear_warning()
Definition component.h:309
size_t ms_to_bytes(uint32_t ms) const
Converts duration to bytes.
Definition audio.h:75
uint32_t bytes_to_frames(size_t bytes) const
Convert bytes to frames.
Definition audio.h:43
uint32_t get_sample_rate() const
Definition audio.h:30
void reset(uint32_t sample_rate)
void process(uint8_t *data, size_t size, const audio::AudioStreamInfo &stream_info)
i2s_std_slot_mask_t std_slot_mask_
Definition i2s_audio.h:38
i2s_slot_bit_width_t slot_bit_width_
Definition i2s_audio.h:39
i2s_clock_src_t get_clock_source_() const
Definition i2s_audio.h:27
i2s_mclk_multiple_t mclk_multiple_
Definition i2s_audio.h:42
static bool i2s_on_recv_q_ovf_cb(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx)
Counts a buffer the driver dropped because the task fell behind; it will never be read.
void build_full_duplex_config(i2s_std_config_t &std_cfg) override
static bool i2s_on_recv_cb(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx)
Records the byte count and time of each DMA buffer the driver queues for reading.
void configure_stream_settings_()
Starts the I2S driver.
void build_std_config_(i2s_std_config_t &std_cfg) const
Builds the standard (non-PDM) mode configuration from the configured settings.
void full_duplex_rx_enabling(i2s_chan_handle_t rx_handle, uint32_t dma_desc_num) override
void publish_audio_(std::span< uint8_t > data, const audio::AudioStreamInfo &stream_info, int64_t capture_time_us=0)
While muted, data is zeroed first, so it must be a buffer the platform owns.
Definition microphone.h:98
audio::AudioStreamInfo audio_stream_info_
Definition microphone.h:110
__int64 ssize_t
Definition httplib.h:178
const char * esp_err_to_name(esp_err_t err)
ESPHOME_LOG_TAG(TAG, "i2s_audio")
int64_t dma_capture_time_us(uint32_t bytes_received, uint32_t drops, uint32_t drops_before_read, int64_t receive_time_us, uint32_t bytes_read_before, uint32_t bytes_read, uint32_t dma_desc_num, uint32_t dma_buffer_bytes, const audio::AudioStreamInfo &stream_info)
Returns when the first frame of a read was captured, counted back from the newest DMA buffer,...
const void size_t len
Definition hal.h:68
int64_t esp_timer_get_time(void)
static void uint32_t
spi_device_handle_t handle