ESPHome  2024.11.1
Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes
esphome::i2s_audio::I2SAudioSpeaker Class Reference

#include <i2s_audio_speaker.h>

Inheritance diagram for esphome::i2s_audio::I2SAudioSpeaker:
esphome::i2s_audio::I2SAudioOut esphome::speaker::Speaker esphome::Component esphome::i2s_audio::I2SAudioBase esphome::Parented< I2SAudioComponent >

Public Member Functions

float get_setup_priority () const override
 
void setup () override
 
void loop () override
 
void set_buffer_duration (uint32_t buffer_duration_ms)
 
void set_timeout (uint32_t ms)
 
void set_dout_pin (uint8_t pin)
 
void set_internal_dac_mode (i2s_dac_mode_t mode)
 
void set_i2s_comm_fmt (i2s_comm_format_t mode)
 
void start () override
 
void stop () override
 
void finish () override
 
size_t play (const uint8_t *data, size_t length, TickType_t ticks_to_wait) override
 Plays the provided audio data. More...
 
size_t play (const uint8_t *data, size_t length) override
 
bool has_buffered_data () const override
 
void set_volume (float volume) override
 Sets the volume of the speaker. More...
 
void set_mute_state (bool mute_state) override
 Mutes or unmute the speaker. More...
 
- Public Member Functions inherited from esphome::i2s_audio::I2SAudioBase
void set_i2s_mode (i2s_mode_t mode)
 
void set_channel (i2s_channel_fmt_t channel)
 
void set_sample_rate (uint32_t sample_rate)
 
void set_bits_per_sample (i2s_bits_per_sample_t bits_per_sample)
 
void set_bits_per_channel (i2s_bits_per_chan_t bits_per_channel)
 
void set_use_apll (uint32_t use_apll)
 
- Public Member Functions inherited from esphome::Parented< I2SAudioComponent >
 Parented ()
 
 Parented (I2SAudioComponent *parent)
 
I2SAudioComponent * get_parent () const
 Get the parent of this object. More...
 
void set_parent (I2SAudioComponent *parent)
 Set the parent of this object. More...
 
- Public Member Functions inherited from esphome::speaker::Speaker
size_t play (const std::vector< uint8_t > &data)
 
bool is_running () const
 
bool is_stopped () const
 
float get_volume ()
 
bool get_mute_state ()
 
void set_audio_dac (audio_dac::AudioDac *audio_dac)
 
void set_audio_stream_info (const audio::AudioStreamInfo &audio_stream_info)
 
- Public Member Functions inherited from esphome::Component
virtual void dump_config ()
 
float get_actual_setup_priority () const
 
void set_setup_priority (float priority)
 
virtual float get_loop_priority () const
 priority of loop(). More...
 
void call ()
 
virtual void on_shutdown ()
 
virtual void on_safe_shutdown ()
 
uint32_t get_component_state () const
 
virtual void mark_failed ()
 Mark this component as failed. More...
 
bool is_failed () const
 
bool is_ready () const
 
virtual bool can_proceed ()
 
bool status_has_warning () const
 
bool status_has_error () const
 
void status_set_warning (const char *message="unspecified")
 
void status_set_error (const char *message="unspecified")
 
void status_clear_warning ()
 
void status_clear_error ()
 
void status_momentary_warning (const std::string &name, uint32_t length=5000)
 
void status_momentary_error (const std::string &name, uint32_t length=5000)
 
bool has_overridden_loop () const
 
void set_component_source (const char *source)
 Set where this component was loaded from for some debug messages. More...
 
const char * get_component_source () const
 Get the integration where this component was declared as a string. More...
 

Protected Member Functions

void stop_ (bool wait_on_empty)
 Sends a stop command to the speaker task via event_group_. More...
 
bool send_esp_err_to_event_group_ (esp_err_t err)
 Sets the corresponding ERR_ESP event group bits. More...
 
esp_err_t allocate_buffers_ (size_t data_buffer_size, size_t ring_buffer_size)
 Allocates the data buffer and ring buffer. More...
 
esp_err_t start_i2s_driver_ ()
 Starts the ESP32 I2S driver. More...
 
esp_err_t reconfigure_i2s_stream_info_ (audio::AudioStreamInfo &audio_stream_info)
 Adjusts the I2S driver configuration to match the incoming audio stream. More...
 
void delete_task_ (size_t buffer_size)
 Deletes the speaker's task. More...
 
- Protected Member Functions inherited from esphome::Component
virtual void call_loop ()
 
virtual void call_setup ()
 
virtual void call_dump_config ()
 
void set_interval (const std::string &name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a unique name. More...
 
void set_interval (uint32_t interval, std::function< void()> &&f)
 
bool cancel_interval (const std::string &name)
 Cancel an interval function. More...
 
void set_retry (const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
 Set an retry function with a unique name. More...
 
void set_retry (uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
 
bool cancel_retry (const std::string &name)
 Cancel a retry function. More...
 
void set_timeout (const std::string &name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a unique name. More...
 
void set_timeout (uint32_t timeout, std::function< void()> &&f)
 
bool cancel_timeout (const std::string &name)
 Cancel a timeout function. More...
 
void defer (const std::string &name, std::function< void()> &&f)
 Defer a callback to the next loop() call. More...
 
void defer (std::function< void()> &&f)
 Defer a callback to the next loop() call. More...
 
bool cancel_defer (const std::string &name)
 Cancel a defer callback using the specified name, name must not be empty. More...
 

Static Protected Member Functions

static void speaker_task (void *params)
 Function for the FreeRTOS task handling audio output. More...
 

Protected Attributes

TaskHandle_t speaker_task_handle_ {nullptr}
 
EventGroupHandle_t event_group_ {nullptr}
 
QueueHandle_t i2s_event_queue_
 
uint8_t * data_buffer_
 
std::shared_ptr< RingBufferaudio_ring_buffer_
 
uint32_t buffer_duration_ms_
 
optional< uint32_t > timeout_
 
uint8_t dout_pin_
 
bool task_created_ {false}
 
int16_t q15_volume_factor_ {INT16_MAX}
 
i2s_dac_mode_t internal_dac_mode_ {I2S_DAC_CHANNEL_DISABLE}
 
i2s_comm_format_t i2s_comm_fmt_
 
- Protected Attributes inherited from esphome::i2s_audio::I2SAudioBase
i2s_mode_t i2s_mode_ {}
 
i2s_channel_fmt_t channel_
 
uint32_t sample_rate_
 
i2s_bits_per_sample_t bits_per_sample_
 
i2s_bits_per_chan_t bits_per_channel_
 
bool use_apll_
 
- Protected Attributes inherited from esphome::Parented< I2SAudioComponent >
I2SAudioComponent * parent_
 
- Protected Attributes inherited from esphome::speaker::Speaker
State state_ {STATE_STOPPED}
 
audio::AudioStreamInfo audio_stream_info_
 
float volume_ {1.0f}
 
bool mute_state_ {false}
 
audio_dac::AudioDacaudio_dac_ {nullptr}
 
- Protected Attributes inherited from esphome::Component
uint32_t component_state_ {0x0000}
 State of this component. More...
 
float setup_priority_override_ {NAN}
 
const char * component_source_ {nullptr}
 

Detailed Description

Definition at line 24 of file i2s_audio_speaker.h.

Member Function Documentation

◆ allocate_buffers_()

esp_err_t esphome::i2s_audio::I2SAudioSpeaker::allocate_buffers_ ( size_t  data_buffer_size,
size_t  ring_buffer_size 
)
protected

Allocates the data buffer and ring buffer.

Parameters
data_buffer_sizeNumber of bytes to allocate for the data buffer.
ring_buffer_sizeNumber of bytes to allocate for the ring buffer.
Returns
ESP_ERR_NO_MEM if either buffer fails to allocate ESP_OK if successful

Definition at line 391 of file i2s_audio_speaker.cpp.

◆ delete_task_()

void esphome::i2s_audio::I2SAudioSpeaker::delete_task_ ( size_t  buffer_size)
protected

Deletes the speaker's task.

Deallocates the data_buffer_ and audio_ring_buffer_, if necessary, and deletes the task. Should only be called by the speaker_task itself.

Parameters
buffer_sizeThe allocated size of the data_buffer_.

Definition at line 504 of file i2s_audio_speaker.cpp.

◆ finish()

void esphome::i2s_audio::I2SAudioSpeaker::finish ( )
overridevirtual

Reimplemented from esphome::speaker::Speaker.

Definition at line 354 of file i2s_audio_speaker.cpp.

◆ get_setup_priority()

float esphome::i2s_audio::I2SAudioSpeaker::get_setup_priority ( ) const
inlineoverridevirtual

Reimplemented from esphome::Component.

Definition at line 26 of file i2s_audio_speaker.h.

◆ has_buffered_data()

bool esphome::i2s_audio::I2SAudioSpeaker::has_buffered_data ( ) const
overridevirtual

Implements esphome::speaker::Speaker.

Definition at line 214 of file i2s_audio_speaker.cpp.

◆ loop()

void esphome::i2s_audio::I2SAudioSpeaker::loop ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 104 of file i2s_audio_speaker.cpp.

◆ play() [1/2]

size_t esphome::i2s_audio::I2SAudioSpeaker::play ( const uint8_t *  data,
size_t  length,
TickType_t  ticks_to_wait 
)
overridevirtual

Plays the provided audio data.

Starts the speaker task, if necessary. Writes the audio data to the ring buffer.

Parameters
dataAudio data in the format set by the parent speaker classes set_audio_stream_info method.
lengthThe length of the audio data in bytes.
ticks_to_waitThe FreeRTOS ticks to wait before writing as much data as possible to the ring buffer.
Returns
The number of bytes that were actually written to the ring buffer.

Reimplemented from esphome::speaker::Speaker.

Definition at line 192 of file i2s_audio_speaker.cpp.

◆ play() [2/2]

size_t esphome::i2s_audio::I2SAudioSpeaker::play ( const uint8_t *  data,
size_t  length 
)
inlineoverridevirtual

Implements esphome::speaker::Speaker.

Definition at line 50 of file i2s_audio_speaker.h.

◆ reconfigure_i2s_stream_info_()

esp_err_t esphome::i2s_audio::I2SAudioSpeaker::reconfigure_i2s_stream_info_ ( audio::AudioStreamInfo audio_stream_info)
protected

Adjusts the I2S driver configuration to match the incoming audio stream.

Modifies I2S driver's sample rate, bits per sample, and number of channel settings. If the I2S is in secondary mode, it only modifies the number of channels.

Parameters
audio_stream_infoDescribes the incoming audio stream
Returns
ESP_ERR_INVALID_ARG if there is a parameter error, if there is more than 2 channels in the stream, or if the audio settings are incompatible with the configuration. ESP_ERR_NO_MEM if the driver fails to reconfigure due to a memory allocation error. ESP_OK if successful.

Definition at line 480 of file i2s_audio_speaker.cpp.

◆ send_esp_err_to_event_group_()

bool esphome::i2s_audio::I2SAudioSpeaker::send_esp_err_to_event_group_ ( esp_err_t  err)
protected

Sets the corresponding ERR_ESP event group bits.

Parameters
erresp_err_t error code.
Returns
True if an ERR_ESP bit is set and false if err == ESP_OK

Definition at line 369 of file i2s_audio_speaker.cpp.

◆ set_buffer_duration()

void esphome::i2s_audio::I2SAudioSpeaker::set_buffer_duration ( uint32_t  buffer_duration_ms)
inline

Definition at line 31 of file i2s_audio_speaker.h.

◆ set_dout_pin()

void esphome::i2s_audio::I2SAudioSpeaker::set_dout_pin ( uint8_t  pin)
inline

Definition at line 33 of file i2s_audio_speaker.h.

◆ set_i2s_comm_fmt()

void esphome::i2s_audio::I2SAudioSpeaker::set_i2s_comm_fmt ( i2s_comm_format_t  mode)
inline

Definition at line 37 of file i2s_audio_speaker.h.

◆ set_internal_dac_mode()

void esphome::i2s_audio::I2SAudioSpeaker::set_internal_dac_mode ( i2s_dac_mode_t  mode)
inline

Definition at line 35 of file i2s_audio_speaker.h.

◆ set_mute_state()

void esphome::i2s_audio::I2SAudioSpeaker::set_mute_state ( bool  mute_state)
overridevirtual

Mutes or unmute the speaker.

Uses the speaker's configured audio dac component. If unavailble, it is implemented as a software volume control. Overrides the default setter to convert the floating point volume to a Q15 fixed-point factor.

Parameters
mute_statetrue for muting, false for unmuting

Reimplemented from esphome::speaker::Speaker.

Definition at line 170 of file i2s_audio_speaker.cpp.

◆ set_timeout()

void esphome::i2s_audio::I2SAudioSpeaker::set_timeout ( uint32_t  ms)
inline

Definition at line 32 of file i2s_audio_speaker.h.

◆ set_volume()

void esphome::i2s_audio::I2SAudioSpeaker::set_volume ( float  volume)
overridevirtual

Sets the volume of the speaker.

Uses the speaker's configured audio dac component. If unavailble, it is implemented as a software volume control. Overrides the default setter to convert the floating point volume to a Q15 fixed-point factor.

Parameters
volumebetween 0.0 and 1.0

Reimplemented from esphome::speaker::Speaker.

Definition at line 153 of file i2s_audio_speaker.cpp.

◆ setup()

void esphome::i2s_audio::I2SAudioSpeaker::setup ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 92 of file i2s_audio_speaker.cpp.

◆ speaker_task()

void esphome::i2s_audio::I2SAudioSpeaker::speaker_task ( void *  params)
staticprotected

Function for the FreeRTOS task handling audio output.

After receiving the COMMAND_START signal, allocates space for the buffers, starts the I2S driver, and reads audio from the ring buffer and writes audio to the I2S port. Stops immmiately after receiving the COMMAND_STOP signal and stops only after the ring buffer is empty after receiving the COMMAND_STOP_GRACEFULLY signal. Stops if the ring buffer hasn't read data for more than timeout_ milliseconds. When stopping, it deallocates the buffers, stops the I2S driver, unlocks the I2S port, and deletes the task. It communicates the state and any errors via event_group_.

Parameters
paramsI2SAudioSpeaker component

Definition at line 221 of file i2s_audio_speaker.cpp.

◆ start()

void esphome::i2s_audio::I2SAudioSpeaker::start ( )
overridevirtual

Implements esphome::speaker::Speaker.

Definition at line 333 of file i2s_audio_speaker.cpp.

◆ start_i2s_driver_()

esp_err_t esphome::i2s_audio::I2SAudioSpeaker::start_i2s_driver_ ( )
protected

Starts the ESP32 I2S driver.

Attempts to lock the I2S port, starts the I2S driver, and sets the data out pin. If it fails, it will unlock the I2S port and uninstall the driver, if necessary.

Returns
ESP_ERR_INVALID_STATE if the I2S port is already locked. ESP_ERR_INVALID_ARG if installing the driver or setting the data out pin fails due to a parameter error. ESP_ERR_NO_MEM if the driver fails to install due to a memory allocation error. ESP_FAIL if setting the data out pin fails due to an IO error ESP_OK if successful

Definition at line 414 of file i2s_audio_speaker.cpp.

◆ stop()

void esphome::i2s_audio::I2SAudioSpeaker::stop ( )
overridevirtual

Implements esphome::speaker::Speaker.

Definition at line 352 of file i2s_audio_speaker.cpp.

◆ stop_()

void esphome::i2s_audio::I2SAudioSpeaker::stop_ ( bool  wait_on_empty)
protected

Sends a stop command to the speaker task via event_group_.

Parameters
wait_on_emptyIf false, sends the COMMAND_STOP signal. If true, sends the COMMAND_STOP_GRACEFULLY signal.

Definition at line 356 of file i2s_audio_speaker.cpp.

Field Documentation

◆ audio_ring_buffer_

std::shared_ptr<RingBuffer> esphome::i2s_audio::I2SAudioSpeaker::audio_ring_buffer_
protected

Definition at line 125 of file i2s_audio_speaker.h.

◆ buffer_duration_ms_

uint32_t esphome::i2s_audio::I2SAudioSpeaker::buffer_duration_ms_
protected

Definition at line 127 of file i2s_audio_speaker.h.

◆ data_buffer_

uint8_t* esphome::i2s_audio::I2SAudioSpeaker::data_buffer_
protected

Definition at line 124 of file i2s_audio_speaker.h.

◆ dout_pin_

uint8_t esphome::i2s_audio::I2SAudioSpeaker::dout_pin_
protected

Definition at line 130 of file i2s_audio_speaker.h.

◆ event_group_

EventGroupHandle_t esphome::i2s_audio::I2SAudioSpeaker::event_group_ {nullptr}
protected

Definition at line 120 of file i2s_audio_speaker.h.

◆ i2s_comm_fmt_

i2s_comm_format_t esphome::i2s_audio::I2SAudioSpeaker::i2s_comm_fmt_
protected

Definition at line 139 of file i2s_audio_speaker.h.

◆ i2s_event_queue_

QueueHandle_t esphome::i2s_audio::I2SAudioSpeaker::i2s_event_queue_
protected

Definition at line 122 of file i2s_audio_speaker.h.

◆ internal_dac_mode_

i2s_dac_mode_t esphome::i2s_audio::I2SAudioSpeaker::internal_dac_mode_ {I2S_DAC_CHANNEL_DISABLE}
protected

Definition at line 137 of file i2s_audio_speaker.h.

◆ q15_volume_factor_

int16_t esphome::i2s_audio::I2SAudioSpeaker::q15_volume_factor_ {INT16_MAX}
protected

Definition at line 134 of file i2s_audio_speaker.h.

◆ speaker_task_handle_

TaskHandle_t esphome::i2s_audio::I2SAudioSpeaker::speaker_task_handle_ {nullptr}
protected

Definition at line 119 of file i2s_audio_speaker.h.

◆ task_created_

bool esphome::i2s_audio::I2SAudioSpeaker::task_created_ {false}
protected

Definition at line 132 of file i2s_audio_speaker.h.

◆ timeout_

optional<uint32_t> esphome::i2s_audio::I2SAudioSpeaker::timeout_
protected

Definition at line 129 of file i2s_audio_speaker.h.


The documentation for this class was generated from the following files: