i2s_audio_speaker.cpp

Go to the documentation of this file.

#include "i2s_audio_speaker.h"
 
#ifdef USE_ESP32
 
#include <driver/gpio.h>
#include <driver/i2s_std.h>
 
#include "esphome/components/audio/audio.h"
#include "esphome/components/audio/audio_transfer_buffer.h"
 
#include "esphome/core/application.h"
#include "esphome/core/hal.h"
#include "esphome/core/log.h"
 
#include "esp_timer.h"
 
#include <cmath>
 
namespace esphome::i2s_audio {
 
ESPHOME_LOG_TAG(TAG, "i2s_audio.speaker");
 
// Software volume control maps the user-facing (0.0, 1.0) range linearly to a dB reduction in
// [-49.0, 0.0] dB; 0.0 is silence.
static constexpr float SOFTWARE_VOLUME_MIN_DB = -49.0f;
 
// Rate at which the software gain moves toward a new target.
static constexpr uint32_t GAIN_RAMP_MS_PER_DB = 1;
 
void I2SAudioSpeakerBase::setup() {
  this->event_group_ = xEventGroupCreate();
 
  if (this->event_group_ == nullptr) {
    ESP_LOGE(TAG, "Event group creation failed");
    this->mark_failed();
    return;
  }
 
  // Initialize volume control. When audio_dac is configured, this sets the DAC volume and mute state.
  // When no audio_dac is configured, this initializes software volume control.
  this->set_volume(this->volume_);
  this->set_mute_state(this->mute_state_);
 
#ifdef USE_I2S_AUDIO_FULL_DUPLEX
  // The parent set up before us and already routed dout to the shared TX channel, which is never re-initialized.
  // Parking would detach the pin for good. SPDIF speakers cannot use a full duplex bus.
  if (this->parent_->is_full_duplex()) {
    if (this->parent_->is_failed()) {
      this->mark_failed(LOG_STR("Full duplex bus setup failed"));
    }
    return;
  }
#endif
 
  // Until the I2S driver first starts, dout sits in its reset state (often pulled high, or a JTAG
  // function on the ESP32-S3), which keeps a SPDIF optical transmitter lit. Park it low now.
  this->park_dout_pin_();
}
 
void I2SAudioSpeakerBase::park_dout_pin_() {
  gpio_reset_pin(this->dout_pin_);
  gpio_set_direction(this->dout_pin_, GPIO_MODE_OUTPUT);
  gpio_set_level(this->dout_pin_, 0);
}
 
void I2SAudioSpeakerBase::dump_config() {
  ESP_LOGCONFIG(TAG,
                "Speaker:\n"
                "  Pin: %d\n"
                "  Buffer duration: %" PRIu32 "\n"
                "  Keep alive: %s",
                static_cast<int8_t>(this->dout_pin_), this->buffer_duration_ms_, YESNO(this->keep_alive_));
  if (this->timeout_.has_value()) {
    ESP_LOGCONFIG(TAG, "  Timeout: %" PRIu32 " ms", this->timeout_.value());
  }
}
 
void I2SAudioSpeakerBase::loop() {
  uint32_t event_group_bits = xEventGroupGetBits(this->event_group_);
 
  // A stop that arrives while stopped cancels any start that has not been processed yet
  constexpr uint32_t stop_bits = SpeakerEventGroupBits::COMMAND_STOP | SpeakerEventGroupBits::COMMAND_STOP_GRACEFULLY;
  if ((event_group_bits & stop_bits) && (this->state_ == speaker::STATE_STOPPED)) {
    xEventGroupClearBits(this->event_group_, stop_bits | SpeakerEventGroupBits::COMMAND_START);
    event_group_bits &= ~(stop_bits | SpeakerEventGroupBits::COMMAND_START);
  }
 
  if ((event_group_bits & SpeakerEventGroupBits::COMMAND_START) && (this->state_ == speaker::STATE_STOPPED)) {
    this->state_ = speaker::STATE_STARTING;
    xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::COMMAND_START);
  }
 
  // Handle the task's state
  if (event_group_bits & SpeakerEventGroupBits::TASK_STARTING) {
    ESP_LOGD(TAG, "Starting");
    xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::TASK_STARTING);
  }
  if (event_group_bits & SpeakerEventGroupBits::TASK_RUNNING) {
    ESP_LOGV(TAG, "Started");
    xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::TASK_RUNNING);
    this->state_ = speaker::STATE_RUNNING;
#ifdef USE_AUDIO_DAC
    // The task raises TASK_RUNNING only after enabling the channel, so the clocks are already running
    if (this->audio_dac_ != nullptr) {
      this->audio_dac_->on_audio_started();
    }
#endif  // USE_AUDIO_DAC
  }
  if (event_group_bits & SpeakerEventGroupBits::TASK_STOPPING) {
    ESP_LOGV(TAG, "Stopping");
    xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::TASK_STOPPING);
    this->state_ = speaker::STATE_STOPPING;
  }
  if (event_group_bits & SpeakerEventGroupBits::TASK_STOPPED) {
    ESP_LOGD(TAG, "Stopped");
 
    vTaskDelete(this->speaker_task_handle_);
    this->speaker_task_handle_ = nullptr;
 
    // The task raises this bit before it exits, possibly a loop pass before TASK_STOPPED is seen, so read it
    // live here; a channel the task could not bring up is rebuilt next time rather than kept
    const bool task_failed = xEventGroupGetBits(this->event_group_) & SpeakerEventGroupBits::ERR_ESP_NO_MEM;
    if (task_failed) {
      ESP_LOGE(TAG, "Speaker task setup failed (allocation, preload, or channel enable)");
    }
    this->stop_i2s_driver_(this->keep_alive_ && !task_failed);
    // ALL_BITS includes COMMAND_START. Take the bits from the clear itself, not from the snapshot at
    // the top of loop(): the audio source's task can raise a start at any point above, including
    // during stop_i2s_driver_(), and nothing would ever re-issue it.
    const EventBits_t bits_before_clear = xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::ALL_BITS);
    if (bits_before_clear & SpeakerEventGroupBits::COMMAND_START) {
      ESP_LOGD(TAG, "Start requested while stopping; keeping the request");
      xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::COMMAND_START);
    }
    this->status_clear_error();
 
    this->on_task_stopped();
 
    this->state_ = speaker::STATE_STOPPED;
  }
 
  // Handle the speaker's state
  switch (this->state_) {
    case speaker::STATE_STARTING: {
      if (this->status_has_error()) {
        break;
      }
 
      // Still winding down from a previous run
      if (this->speaker_task_handle_ != nullptr) {
        break;
      }
 
#ifdef USE_I2S_AUDIO_FULL_DUPLEX
      if (this->parent_->is_tx_in_use()) {
        // Another speaker on the bus is playing; wait for it to release the channel
        break;
      }
#endif
      const esp_err_t err = this->start_i2s_driver(this->audio_stream_info_);
      if (err == ESP_ERR_NOT_SUPPORTED) {
        // Retrying cannot help; stay stopped so the audio source gives up instead of waiting forever
        ESP_LOGE(TAG, "Stream format not supported; not starting");
        this->rejected_stream_info_ = this->audio_stream_info_;
        this->state_ = speaker::STATE_STOPPED;
        break;
      }
      if (err != ESP_OK) {
        ESP_LOGE(TAG, "Driver failed to start; retrying in 1 second");
        this->status_momentary_error(1000);
        break;
      }
 
      // Seed the ramp at the live target so this run adopts it instantly rather than fading to it
      // from wherever the previous run left off. Posted here, not in the task: the ramp's mailbox
      // allows one writer, and that is the main loop.
      this->post_software_gain_(0);
      xTaskCreate(I2SAudioSpeakerBase::speaker_task, "speaker_task", TASK_STACK_SIZE, (void *) this, TASK_PRIORITY,
                  &this->speaker_task_handle_);
 
      if (this->speaker_task_handle_ == nullptr) {
        ESP_LOGE(TAG, "Task failed to start, retrying in 1 second");
        this->status_momentary_error(1000);
        this->stop_i2s_driver_(false);  // Stops the driver to return the lock; will be reloaded in next attempt
      }
      break;
    }
    case speaker::STATE_RUNNING:   // Intentional fallthrough
    case speaker::STATE_STOPPING:  // Intentional fallthrough
    case speaker::STATE_STOPPED:
      break;
  }
}
 
void I2SAudioSpeakerBase::set_volume(float volume) {
  speaker::Speaker::set_volume(volume);
  this->post_software_gain_(this->audio_stream_info_.ms_to_samples(GAIN_RAMP_MS_PER_DB));
}
 
void I2SAudioSpeakerBase::set_mute_state(bool mute_state) {
  speaker::Speaker::set_mute_state(mute_state);
  this->post_software_gain_(this->audio_stream_info_.ms_to_samples(GAIN_RAMP_MS_PER_DB));
}
 
void I2SAudioSpeakerBase::post_software_gain_(uint32_t rate_samples) {
#ifdef USE_AUDIO_DAC
  if (this->audio_dac_ != nullptr) {
    return;  // Hardware volume; the ramp stays at unity
  }
#endif  // USE_AUDIO_DAC
  // Software volume control. The ramp treats 0 dB as unity and skips processing there.
  float target_db;
  if (this->is_silent_()) {
    target_db = -INFINITY;
  } else if (this->volume_ >= 1.0f) {
    target_db = 0.0f;
  } else {
    target_db = remap<float, float>(this->volume_, 0.0f, 1.0f, SOFTWARE_VOLUME_MIN_DB, 0.0f);
  }
  this->gain_ramp_.set_target_db_at_rate(target_db, rate_samples);
}
 
size_t I2SAudioSpeakerBase::play(const uint8_t *data, size_t length, TickType_t ticks_to_wait) {
  if (this->is_failed()) {
    ESP_LOGE(TAG, "Setup failed; cannot play audio");
    return 0;
  }
 
  if (this->state_ != speaker::STATE_RUNNING && this->state_ != speaker::STATE_STARTING) {
    this->start();
  }
 
  if (this->state_ != speaker::STATE_RUNNING) {
    // Unable to write data to a running speaker, so delay the max amount of time so it can get ready
    vTaskDelay(ticks_to_wait);
    ticks_to_wait = 0;
  }
 
  size_t bytes_written = 0;
  if (this->state_ == speaker::STATE_RUNNING) {
    std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->audio_ring_buffer_.lock();
    if (temp_ring_buffer != nullptr) {
      // The weak_ptr locks successfully only while the speaker task owns the ring buffer, so it is safe to write
      bytes_written = temp_ring_buffer->write_without_replacement((void *) data, length, ticks_to_wait);
    }
  }
 
  return bytes_written;
}
 
bool I2SAudioSpeakerBase::has_buffered_data() const {
  std::shared_ptr<ring_buffer::RingBuffer> temp_ring_buffer = this->audio_ring_buffer_.lock();
  if (temp_ring_buffer != nullptr) {
    return temp_ring_buffer->available() > 0;
  }
  return false;
}
 
void I2SAudioSpeakerBase::speaker_task(void *params) {
  I2SAudioSpeakerBase *this_speaker = (I2SAudioSpeakerBase *) params;
  this_speaker->run_speaker_task();
}
 
void I2SAudioSpeakerBase::start() {
  if (!this->is_ready() || this->is_failed() || this->status_has_error())
    return;
  if ((this->state_ == speaker::STATE_STARTING) || (this->state_ == speaker::STATE_RUNNING))
    return;
  // play() calls start() on every write, so without this a rejected stream would be retried and logged nonstop
  if (this->rejected_stream_info_.has_value() && this->rejected_stream_info_.value() == this->audio_stream_info_)
    return;
 
  xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::COMMAND_START);
}
 
void I2SAudioSpeakerBase::stop() { this->stop_(false); }
 
void I2SAudioSpeakerBase::finish() { this->stop_(true); }
 
void I2SAudioSpeakerBase::stop_(bool wait_on_empty) {
  if (!this->is_ready() || this->is_failed())
    return;
 
  // Always set the bit, even when stopped, so loop() can cancel a start that is still pending
  if (wait_on_empty) {
    xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::COMMAND_STOP_GRACEFULLY);
  } else {
    xEventGroupSetBits(this->event_group_, SpeakerEventGroupBits::COMMAND_STOP);
  }
}
 
esp_err_t I2SAudioSpeakerBase::init_i2s_channel_(const i2s_chan_config_t &chan_cfg, const i2s_std_config_t &std_cfg,
                                                 size_t event_queue_size) {
  esp_err_t err = i2s_new_channel(&chan_cfg, &this->tx_handle_, NULL);
  if (err != ESP_OK) {
    ESP_LOGE(TAG, "I2S channel allocation failed: %s", esp_err_to_name(err));
    this->parent_->unlock();
    return err;
  }
 
  err = i2s_channel_init_std_mode(this->tx_handle_, &std_cfg);
  if (err != ESP_OK) {
    ESP_LOGE(TAG, "Failed to initialize I2S channel");
    this->delete_channel_();
    this->parent_->unlock();
    return err;
  }
 
  err = this->prepare_event_queues_(event_queue_size);
  if (err != ESP_OK) {
    this->delete_channel_();
    this->parent_->unlock();
  }
  return err;
}
 
esp_err_t I2SAudioSpeakerBase::prepare_event_queues_(size_t event_queue_size) {
  // Both queues are drained by the speaker task before it preloads, whether the channel is new or kept
  if (this->i2s_event_queue_ == nullptr) {
    this->i2s_event_queue_ = xQueueCreate(event_queue_size, sizeof(int64_t));
  }
 
  // Lockstep records queue. One record per in-flight DMA buffer; sized to match the I2S event queue
  // so a fully-saturated DMA pipeline cannot overflow either side before drain.
  if (this->write_records_queue_ == nullptr) {
    this->write_records_queue_ = xQueueCreate(event_queue_size, sizeof(uint32_t));
  }
 
  if (this->i2s_event_queue_ == nullptr || this->write_records_queue_ == nullptr) {
    ESP_LOGE(TAG, "Failed to allocate I2S event queue(s)");
    return ESP_ERR_NO_MEM;
  }
 
  return ESP_OK;
}
 
#ifdef USE_I2S_AUDIO_FULL_DUPLEX
esp_err_t I2SAudioSpeakerBase::acquire_full_duplex_channel_(size_t event_queue_size) {
  this->tx_handle_ = this->parent_->acquire_tx_channel();
  if (this->tx_handle_ == nullptr) {
    ESP_LOGE(TAG, "Full duplex channel unavailable");
    return ESP_ERR_INVALID_STATE;
  }
 
  esp_err_t err = this->prepare_event_queues_(event_queue_size);
  if (err != ESP_OK) {
    this->parent_->release_tx_channel();
    this->tx_handle_ = nullptr;
  }
  return err;
}
#endif
 
void I2SAudioSpeakerBase::stop_i2s_driver_(bool keep_channel) {
#ifdef USE_I2S_AUDIO_FULL_DUPLEX
  if (this->parent_->is_full_duplex()) {
    // The parent owns the channel pair and its pins, so only hand the TX channel back
    if (this->tx_handle_ != nullptr) {
      this->parent_->release_tx_channel();
      this->tx_handle_ = nullptr;
    }
    return;
  }
#endif
 
  if (this->tx_handle_ != nullptr) {
    i2s_channel_disable(this->tx_handle_);
    // A kept channel lets the next start skip i2s_new_channel and i2s_channel_init_std_mode, whose GPIO and
    // clock reconfiguration is the audible pop
    if (!keep_channel) {
      this->delete_channel_();
    }
  }
  this->parent_->unlock();
}
 
void I2SAudioSpeakerBase::delete_channel_() {
  i2s_del_channel(this->tx_handle_);
  this->tx_handle_ = nullptr;
 
  // i2s_del_channel() leaves dout wired to this port's data-out signal in the GPIO matrix: it only
  // clears an internal reservation mask, never the esp_rom_gpio_connect_out_signal() routing that
  // setup installed. If another speaker reuses this port (shared bus), its audio still reaches our
  // dout. Detach the pin and drive it low so a stale output stops driving downstream hardware: a
  // SPDIF optical transmitter would otherwise stay lit, and an analog DAC would emit noise.
  this->park_dout_pin_();
}
 
bool IRAM_ATTR I2SAudioSpeakerBase::i2s_on_sent_cb(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx) {
  int64_t now = esp_timer_get_time();
 
  BaseType_t need_yield1 = pdFALSE;
  BaseType_t need_yield2 = pdFALSE;
  BaseType_t need_yield3 = pdFALSE;
 
  I2SAudioSpeakerBase *this_speaker = (I2SAudioSpeakerBase *) user_ctx;
 
  if (xQueueIsQueueFullFromISR(this_speaker->i2s_event_queue_)) {
    // Queue is full, so discard the oldest event. The lockstep queues are now desynced; the task resyncs them.
    int64_t dummy;
    xQueueReceiveFromISR(this_speaker->i2s_event_queue_, &dummy, &need_yield1);
    xEventGroupSetBitsFromISR(this_speaker->event_group_, SpeakerEventGroupBits::ERR_DROPPED_EVENT, &need_yield2);
  }
 
  xQueueSendToBackFromISR(this_speaker->i2s_event_queue_, &now, &need_yield3);
 
  return need_yield1 | need_yield2 | need_yield3;
}
 
void I2SAudioSpeakerBase::drain_lockstep_(uint32_t extra_frames) {
  // Stop DMA so no more completion events arrive while the queues are rebuilt
  i2s_channel_disable(this->tx_handle_);
  xEventGroupClearBits(this->event_group_, SpeakerEventGroupBits::ERR_DROPPED_EVENT);
 
  uint32_t frames = extra_frames;
  uint32_t record_frames = 0;
  while (xQueueReceive(this->write_records_queue_, &record_frames, 0) == pdTRUE) {
    frames += record_frames;
  }
  xQueueReset(this->i2s_event_queue_);
 
  if (frames > 0) {
    ESP_LOGV(TAG, "Crediting %" PRIu32 " dropped frames as played", frames);
    this->audio_output_callback_(frames, esp_timer_get_time());
  }
}
 
void I2SAudioSpeakerBase::apply_software_volume_(uint8_t *data, size_t bytes_read) {
#ifdef USE_AUDIO_DAC
  if (this->audio_dac_ != nullptr) {
    return;  // Hardware volume; the ramp is never targeted
  }
#endif  // USE_AUDIO_DAC
  const size_t bytes_per_sample = this->current_stream_info_.samples_to_bytes(1);
  this->gain_ramp_.process(data, static_cast<uint8_t>(bytes_per_sample),
                           this->current_stream_info_.bytes_to_samples(bytes_read));
}
 
bool I2SAudioSpeakerBase::esp32_mono_swap_needed(const audio::AudioStreamInfo &stream_info) {
#ifdef USE_ESP32_VARIANT_ESP32
  return stream_info.get_channels() == 1 && stream_info.get_bits_per_sample() == 16;
#else
  return false;
#endif  // USE_ESP32_VARIANT_ESP32
}
 
void I2SAudioSpeakerBase::swap_esp32_mono_samples_(uint8_t *data, size_t bytes_read) {
#ifdef USE_ESP32_VARIANT_ESP32
  // For ESP32 16-bit mono mode, adjacent samples need to be swapped.
  if (this->esp32_mono_swap_needed_()) {
    int16_t *samples = reinterpret_cast<int16_t *>(data);
    size_t sample_count = bytes_read / sizeof(int16_t);
    for (size_t i = 0; i + 1 < sample_count; i += 2) {
      int16_t tmp = samples[i];
      samples[i] = samples[i + 1];
      samples[i + 1] = tmp;
    }
  }
#endif  // USE_ESP32_VARIANT_ESP32
}
 
}  // namespace esphome::i2s_audio
 
#endif  // USE_ESP32