i2s_audio_speaker.h

Go to the documentation of this file.

#pragma once
 
#ifdef USE_ESP32
 
#include "../i2s_audio.h"
 
#include <freertos/event_groups.h>
#include <freertos/queue.h>
#include <freertos/FreeRTOS.h>
 
#include "esphome/components/audio/audio.h"
#include "esphome/components/ring_buffer/ring_buffer.h"
#include "esphome/components/speaker/speaker.h"
 
#include "esphome/core/component.h"
#include "esphome/core/gpio.h"
#include "esphome/core/helpers.h"
 
#include <gain.h>  // esp-audio-libs
 
namespace esphome::i2s_audio {
 
// Shared constants used by both standard and SPDIF speaker implementations
static constexpr size_t TASK_STACK_SIZE = 4096;
static constexpr ssize_t TASK_PRIORITY = 19;
 
enum SpeakerEventGroupBits : uint32_t {
  COMMAND_START = (1 << 0),            // indicates loop should start speaker task
  COMMAND_STOP = (1 << 1),             // stops the speaker task
  COMMAND_STOP_GRACEFULLY = (1 << 2),  // Stops the speaker task once all data has been written
 
  TASK_STARTING = (1 << 10),
  TASK_RUNNING = (1 << 11),
  TASK_STOPPING = (1 << 12),
  TASK_STOPPED = (1 << 13),
 
  ERR_ESP_NO_MEM = (1 << 19),
 
  ERR_DROPPED_EVENT = (1 << 20),  // ISR overflowed the event queue, dropping a completion event
 
  ALL_BITS = 0x00FFFFFF,  // All valid FreeRTOS event group bits
};
 
class I2SAudioSpeakerBase : public I2SAudioOut, public speaker::Speaker, public Component {
 public:
  float get_setup_priority() const override { return esphome::setup_priority::PROCESSOR; }
 
  void setup() override;
  void dump_config() override;
  void loop() override;
 
  void set_buffer_duration(uint32_t buffer_duration_ms) { this->buffer_duration_ms_ = buffer_duration_ms; }
  void set_timeout(uint32_t ms) { this->timeout_ = ms; }
  void set_keep_alive(bool keep_alive) { this->keep_alive_ = keep_alive; }
  void set_dout_pin(uint8_t pin) { this->dout_pin_ = (gpio_num_t) pin; }
 
  i2s_chan_handle_t get_tx_handle() const { return this->tx_handle_; }
 
  void start() override;
  void stop() override;
  void finish() override;
 
  void set_pause_state(bool pause_state) override { this->pause_state_ = pause_state; }
  bool get_pause_state() const override { return this->pause_state_; }
 
  size_t play(const uint8_t *data, size_t length, TickType_t ticks_to_wait) override;
  size_t play(const uint8_t *data, size_t length) override { return play(data, length, 0); }
 
  bool has_buffered_data() const override;
 
  void set_volume(float volume) override;
 
  void set_mute_state(bool mute_state) override;
 
 protected:
  void post_software_gain_(uint32_t rate_samples);
 
  static void speaker_task(void *params);
 
  virtual void run_speaker_task() = 0;
 
  void stop_(bool wait_on_empty);
 
  static bool i2s_on_sent_cb(i2s_chan_handle_t handle, i2s_event_data_t *event, void *user_ctx);
 
  virtual esp_err_t start_i2s_driver(audio::AudioStreamInfo &audio_stream_info) = 0;
 
  esp_err_t 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 prepare_event_queues_(size_t event_queue_size);
 
#ifdef USE_I2S_AUDIO_FULL_DUPLEX
  esp_err_t acquire_full_duplex_channel_(size_t event_queue_size);
#endif
 
  void stop_i2s_driver_(bool keep_channel);
 
  void park_dout_pin_();
 
  void delete_channel_();
 
  virtual void on_task_stopped() {}
 
  template<typename F> bool resync_lockstep_(uint32_t extra_frames, F &&preload) {
    this->drain_lockstep_(extra_frames);
    return preload() && (i2s_channel_enable(this->tx_handle_) == ESP_OK);
  }
 
  void drain_lockstep_(uint32_t extra_frames);
 
  void apply_software_volume_(uint8_t *data, size_t bytes_read);
 
  static bool esp32_mono_swap_needed(const audio::AudioStreamInfo &stream_info);
  bool esp32_mono_swap_needed_() const { return esp32_mono_swap_needed(this->output_stream_info_); }
 
  void swap_esp32_mono_samples_(uint8_t *data, size_t bytes_read);
 
  TaskHandle_t speaker_task_handle_{nullptr};
  EventGroupHandle_t event_group_{nullptr};
 
  // Lockstepped DMA buffer queues: i2s_event is outgoing, write_records is incoming
  QueueHandle_t i2s_event_queue_{nullptr};
  QueueHandle_t write_records_queue_{nullptr};
 
  std::weak_ptr<ring_buffer::RingBuffer> audio_ring_buffer_;
 
  uint32_t buffer_duration_ms_;
 
  optional<uint32_t> timeout_;
 
  // A format start_i2s_driver() refused. Those checks compare against fixed settings, so it can never start.
  optional<audio::AudioStreamInfo> rejected_stream_info_;
 
  bool pause_state_{false};
  bool keep_alive_{false};
 
  // Smooths software gain changes. The main loop posts targets, the speaker task processes;
  // GainRamp's mailbox makes that safe. The main loop is the only poster.
  esp_audio_libs::gain::GainRamp gain_ramp_;
 
  audio::AudioStreamInfo current_stream_info_;  // Format of the audio in the ring buffer (the I2S input)
  // Format actually clocked out of the I2S peripheral. Same channel count and sample rate as
  // current_stream_info_, but the bits per sample may be converted to the speaker's configured slot bit width.
  // Set by start_i2s_driver before the speaker task starts.
  audio::AudioStreamInfo output_stream_info_;
 
  gpio_num_t dout_pin_;
  i2s_chan_handle_t tx_handle_{nullptr};
};
 
}  // namespace esphome::i2s_audio
 
#endif  // USE_ESP32