#include <usb_audio.h>

Inheritance diagram for esphome::usb_audio::USBAudioComponent:

Data Structures
struct	ControlState

struct	EndpointState

struct	Op
	A blocking driver call, run on the worker. More...

Public Member Functions
void	setup () override

void	dump_config () override

void	loop () override

float	get_setup_priority () const override

bool	teardown () override

void	register_speaker (USBAudioStream *speaker)

void	register_microphone (USBAudioStream *microphone)

void	resume (Endpoint endpoint)
	Start streaming as soon as the device is connected; the platform hears back through on_stream_state().

void	suspend (Endpoint endpoint)

void	set_speaker_volume_level (float volume)
	Safe from any task; the worker sends the values to the device.

void	set_speaker_mute_state (bool mute_state)

esp_err_t	read_microphone (uint8_t buffer, size_t size, size_t bytes_read, uint32_t timeout_ms)

esp_err_t	write_speaker (const uint8_t *data, size_t length, uint32_t timeout_ms)

Public Member Functions inherited from esphome::Component
float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

void	call ()

virtual void	on_shutdown ()

virtual void	on_safe_shutdown ()

virtual void	on_powerdown ()
	Called after teardown is complete to power down hardware.

uint8_t	get_component_state () const

void	reset_to_construction_state ()
	Reset this component back to the construction state to allow setup to run again.

bool	is_in_loop_state () const
	Check if this component has completed setup and is in the loop state.

bool	is_idle () const
	Check if this component is idle.

void	mark_failed ()
	Mark this component as failed.

void	mark_failed (const LogString *message)

void	disable_loop ()
	Disable this component's loop.

void	enable_loop ()
	Enable this component's loop.

void	enable_loop_soon_any_context ()
	Thread and ISR-safe version of enable_loop() that can be called from any context.

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 ()

void	status_set_warning (const char *message)

void	status_set_warning (const LogString *message)

bool	status_comm_result (bool ok)
	Clears the warning when `ok`, else sets it with `message` (default "Communication failed"); returns `ok`.

bool	status_comm_result (bool ok, const LogString *message)

void	status_set_error ()

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

	ESPDEPRECATED ("Use status_momentary_warning() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_warning(const char *name

void	status_momentary_warning (uint32_t length=5000)
	Set warning status flag and clear it after `length` ms.

void	status_momentary_warning (const LogString *message, uint32_t length=5000)

	ESPDEPRECATED ("Use status_momentary_error() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_error(const char *name

void	status_momentary_error (uint32_t length=5000)
	Set error status flag and clear it after `length` ms.

void	status_momentary_error (const LogString *message, uint32_t length=5000)

bool	has_overridden_loop () const

const LogString *	get_component_log_str () const ESPHOME_ALWAYS_INLINE
	Get the integration where this component was declared as a LogString for logging.

bool	should_warn_of_blocking (uint32_t blocking_time, uint32_t &threshold_ms_out)

Protected Member Functions
EndpointState &	endpoint_ (Endpoint endpoint)

const EndpointState &	endpoint_ (Endpoint endpoint) const

void	process_events_ (uint32_t now)

void	process_event_ (const USBAudioEvent &event, uint32_t now)

void	open_stream_ (Endpoint endpoint, uint8_t addr, uint8_t iface_num)

void	on_opened_ (const USBAudioEvent &event)

void	on_started_ (const USBAudioEvent &event)

void	on_resumed_ (const USBAudioEvent &event)

void	on_closed_ (const USBAudioEvent &event, uint32_t now)

void	start_stream_ (Endpoint endpoint)

void	stream_failed_ (Endpoint endpoint)

void	handle_disconnect_ (uac_host_device_handle_t handle)

void	begin_close_ (Endpoint endpoint)

bool	finish_closes_ (uint32_t now)

bool	queue_op_ (const Op &op)

void	queue_controls_ ()

void	post_event_ (const USBAudioEvent &event)

void	run_op_ (const Op &op)

void	lock_driver_ ()
	Keep platform reads and writes out of the driver while the worker uses it.

bool	enter_driver_ (uint32_t &timeout_ms)
	Platform side: wait, within timeout_ms, until the worker is not using the driver, and count the caller as a driver user; timeout_ms is reduced by the wait.

void	unlock_driver_ ()

bool	populate_stream_config_ (Endpoint endpoint, uac_host_device_handle_t handle, uac_host_stream_config_t &stream_config, bool &rejected)

bool	apply_pending_speaker_controls_ ()
	Send pending volume and mute; returns true when one should be retried later.

bool	apply_control_ (ControlState &control, esp_err_t err, const LogString *name)

Protected Member Functions inherited from esphome::Component
friend	void::setup ()

friend	void::original_setup ()

void	set_component_source_ (uint8_t index)
	Set where this component was loaded from for some debug messages.

virtual void	call_setup ()

void	call_dump_config_ ()

void	enable_loop_slow_path_ ()

void	set_component_state_ (uint8_t state)
	Helper to set component state (clears state bits and sets new state)

bool	set_status_flag_ (uint8_t flag)
	Helper to set a status LED flag on both this component and the app.

bool	set_error_flag_ (const LogString *message)
	Set the error flag and log it; true when it was not set before.

void	set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a const char* name.

void	set_interval (uint32_t id, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a numeric ID (zero heap allocation).

void	set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)

void	set_interval (uint32_t interval, std::function< void()> &&f)

bool	cancel_interval (const char *name)
	Cancel an interval function.

bool	cancel_interval (uint32_t id)

bool	cancel_interval (InternalSchedulerID id)

void	set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a const char* name.

void	set_timeout (uint32_t id, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a numeric ID (zero heap allocation).

void	set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)

void	set_timeout (uint32_t timeout, std::function< void()> &&f)

bool	cancel_timeout (const char *name)
	Cancel a timeout function.

bool	cancel_timeout (uint32_t id)

bool	cancel_timeout (InternalSchedulerID id)

void	defer (const char *name, std::function< void()> &&f)
	Defer a callback to the next loop() call with a const char* name.

void	defer (std::function< void()> &&f)
	Defer a callback to the next loop() call.

void	defer (uint32_t id, std::function< void()> &&f)
	Defer a callback with a numeric ID (zero heap allocation)

bool	cancel_defer (const char *name)
	Cancel a defer callback using the specified name, name must not be empty.

bool	cancel_defer (uint32_t id)

void	status_clear_warning_slow_path_ ()

void	status_clear_error_slow_path_ ()

Static Protected Member Functions
static void	worker_task (void *param)

static void	driver_event_stub (uint8_t addr, uint8_t iface_num, uac_host_driver_event_t event, void *user_data)

static void	device_event_stub (uac_host_device_handle_t handle, uac_host_device_event_t event, void *user_data)

Protected Attributes
StaticTask	worker_

QueueHandle_t	event_queue_ {nullptr}

QueueHandle_t	op_queue_ {nullptr}

std::array< EndpointState, 2 >	endpoints_ {}

std::array< uac_host_device_handle_t, 2 >	lost_while_opening_ {}

std::atomic< uint32_t >	transfer_errors_ {0}

StaticQueue_t	event_queue_struct_ {}

StaticQueue_t	op_queue_struct_ {}

std::array< uint8_t, EVENT_QUEUE_LENGTH *sizeof(USBAudioEvent)>	event_queue_storage_ {}

std::array< uint8_t, OP_QUEUE_LENGTH *sizeof(Op)>	op_queue_storage_ {}

ControlState	volume_ {}

ControlState	mute_ {}

std::atomic< uint8_t >	speaker_volume_ {100}

std::atomic< bool >	speaker_muted_ {false}

std::atomic< bool >	controls_queued_ {false}

std::atomic< bool >	driver_busy_ {false}

std::atomic< uint8_t >	driver_users_ {0}

bool	uac_installed_ {false}

Protected Attributes inherited from esphome::Component
uint8_t	component_source_index_ {0}
	Index into component source PROGMEM lookup table (0 = not set)

uint8_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_CS}
	Warn threshold in centiseconds (max 2550ms)

uint8_t	component_state_ {0x00}
	State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.

volatile bool	pending_enable_loop_ {false}
	ISR-safe flag for enable_loop_soon_any_context.

ComponentRuntimeStats	runtime_stats_

Static Protected Attributes
static constexpr size_t	EVENT_QUEUE_LENGTH = 16

static constexpr size_t	OP_QUEUE_LENGTH = 8

static constexpr uint32_t	SPEAKER_RING_SLACK = 4

Additional Inherited Members
Data Fields inherited from esphome::Component
uint32_t	length = 5000)

Detailed Description

Definition at line 83 of file usb_audio.h.

Member Function Documentation

◆ apply_control_()

bool esphome::usb_audio::USBAudioComponent::apply_control_	(	ControlState &	control,
		esp_err_t	err,
		const LogString *	name )

protected

Definition at line 810 of file usb_audio.cpp.

◆ apply_pending_speaker_controls_()

bool esphome::usb_audio::USBAudioComponent::apply_pending_speaker_controls_ ( )

protected

Send pending volume and mute; returns true when one should be retried later.

Definition at line 793 of file usb_audio.cpp.

◆ begin_close_()

void esphome::usb_audio::USBAudioComponent::begin_close_ ( Endpoint endpoint )

protected

Definition at line 504 of file usb_audio.cpp.

◆ device_event_stub()

void esphome::usb_audio::USBAudioComponent::device_event_stub	(	uac_host_device_handle_t	handle,
		uac_host_device_event_t	event,
		void *	user_data )

staticprotected

Definition at line 854 of file usb_audio.cpp.

◆ driver_event_stub()

void esphome::usb_audio::USBAudioComponent::driver_event_stub	(	uint8_t	addr,
		uint8_t	iface_num,
		uac_host_driver_event_t	event,
		void *	user_data )

staticprotected

Definition at line 834 of file usb_audio.cpp.

◆ dump_config()

void esphome::usb_audio::USBAudioComponent::dump_config ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 111 of file usb_audio.cpp.

◆ endpoint_() [1/2]

EndpointState & esphome::usb_audio::USBAudioComponent::endpoint_ ( Endpoint endpoint )

inlineprotected

Definition at line 174 of file usb_audio.h.

◆ endpoint_() [2/2]

const EndpointState & esphome::usb_audio::USBAudioComponent::endpoint_ ( Endpoint endpoint ) const

inlineprotected

Definition at line 175 of file usb_audio.h.

◆ enter_driver_()

bool esphome::usb_audio::USBAudioComponent::enter_driver_ ( uint32_t & timeout_ms )

protected

Platform side: wait, within timeout_ms, until the worker is not using the driver, and count the caller as a driver user; timeout_ms is reduced by the wait.

Returns false when the worker still holds it.

Definition at line 211 of file usb_audio.cpp.

◆ finish_closes_()

bool esphome::usb_audio::USBAudioComponent::finish_closes_ ( uint32_t now )

protected

Definition at line 517 of file usb_audio.cpp.

◆ get_setup_priority()

float esphome::usb_audio::USBAudioComponent::get_setup_priority ( ) const

inlineoverridevirtual

Reimplemented from esphome::Component.

Definition at line 89 of file usb_audio.h.

◆ handle_disconnect_()

void esphome::usb_audio::USBAudioComponent::handle_disconnect_ ( uac_host_device_handle_t handle )

protected

Definition at line 478 of file usb_audio.cpp.

◆ lock_driver_()

void esphome::usb_audio::USBAudioComponent::lock_driver_ ( )

protected

Keep platform reads and writes out of the driver while the worker uses it.

Definition at line 595 of file usb_audio.cpp.

◆ loop()

void esphome::usb_audio::USBAudioComponent::loop ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 85 of file usb_audio.cpp.

◆ on_closed_()

void esphome::usb_audio::USBAudioComponent::on_closed_	(	const USBAudioEvent &	event,
		uint32_t	now )

protected

Definition at line 543 of file usb_audio.cpp.

◆ on_opened_()

void esphome::usb_audio::USBAudioComponent::on_opened_ ( const USBAudioEvent & event )

protected

Definition at line 339 of file usb_audio.cpp.

◆ on_resumed_()

void esphome::usb_audio::USBAudioComponent::on_resumed_ ( const USBAudioEvent & event )

protected

Definition at line 430 of file usb_audio.cpp.

◆ on_started_()

void esphome::usb_audio::USBAudioComponent::on_started_ ( const USBAudioEvent & event )

protected

Definition at line 401 of file usb_audio.cpp.

◆ open_stream_()

void esphome::usb_audio::USBAudioComponent::open_stream_	(	Endpoint	endpoint,
		uint8_t	addr,
		uint8_t	iface_num )

protected

Definition at line 302 of file usb_audio.cpp.

◆ populate_stream_config_()

bool esphome::usb_audio::USBAudioComponent::populate_stream_config_	(	Endpoint	endpoint,
		uac_host_device_handle_t	handle,
		uac_host_stream_config_t &	stream_config,
		bool &	rejected )

protected

Definition at line 719 of file usb_audio.cpp.

◆ post_event_()

void esphome::usb_audio::USBAudioComponent::post_event_ ( const USBAudioEvent & event )

protected

Definition at line 575 of file usb_audio.cpp.

◆ process_event_()

void esphome::usb_audio::USBAudioComponent::process_event_	(	const USBAudioEvent &	event,
		uint32_t	now )

protected

Definition at line 269 of file usb_audio.cpp.

◆ process_events_()

void esphome::usb_audio::USBAudioComponent::process_events_ ( uint32_t now )

protected

Definition at line 100 of file usb_audio.cpp.

◆ queue_controls_()

void esphome::usb_audio::USBAudioComponent::queue_controls_ ( )

protected

Definition at line 462 of file usb_audio.cpp.

◆ queue_op_()

bool esphome::usb_audio::USBAudioComponent::queue_op_ ( const Op & op )

protected

Definition at line 567 of file usb_audio.cpp.

◆ read_microphone()

esp_err_t esphome::usb_audio::USBAudioComponent::read_microphone	(	uint8_t *	buffer,
		size_t	size,
		size_t *	bytes_read,
		uint32_t	timeout_ms )

Definition at line 230 of file usb_audio.cpp.

◆ register_microphone()

void esphome::usb_audio::USBAudioComponent::register_microphone ( USBAudioStream * microphone )

inline

Definition at line 93 of file usb_audio.h.

◆ register_speaker()

void esphome::usb_audio::USBAudioComponent::register_speaker ( USBAudioStream * speaker )

inline

Definition at line 92 of file usb_audio.h.

◆ resume()

void esphome::usb_audio::USBAudioComponent::resume ( Endpoint endpoint )

Start streaming as soon as the device is connected; the platform hears back through on_stream_state().

Definition at line 155 of file usb_audio.cpp.

◆ run_op_()

void esphome::usb_audio::USBAudioComponent::run_op_ ( const Op & op )

protected

Definition at line 605 of file usb_audio.cpp.

◆ set_speaker_mute_state()

void esphome::usb_audio::USBAudioComponent::set_speaker_mute_state ( bool mute_state )

Definition at line 456 of file usb_audio.cpp.

◆ set_speaker_volume_level()

void esphome::usb_audio::USBAudioComponent::set_speaker_volume_level ( float volume )

Safe from any task; the worker sends the values to the device.

Definition at line 450 of file usb_audio.cpp.

◆ setup()

void esphome::usb_audio::USBAudioComponent::setup ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 51 of file usb_audio.cpp.

◆ start_stream_()

void esphome::usb_audio::USBAudioComponent::start_stream_ ( Endpoint endpoint )

protected

Definition at line 388 of file usb_audio.cpp.

◆ stream_failed_()

void esphome::usb_audio::USBAudioComponent::stream_failed_ ( Endpoint endpoint )

protected

Definition at line 443 of file usb_audio.cpp.

◆ suspend()

void esphome::usb_audio::USBAudioComponent::suspend ( Endpoint endpoint )

Definition at line 195 of file usb_audio.cpp.

◆ teardown()

bool esphome::usb_audio::USBAudioComponent::teardown ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 123 of file usb_audio.cpp.

◆ unlock_driver_()

void esphome::usb_audio::USBAudioComponent::unlock_driver_ ( )

protected

Definition at line 603 of file usb_audio.cpp.

◆ worker_task()

void esphome::usb_audio::USBAudioComponent::worker_task ( void * param )

staticprotected

Definition at line 582 of file usb_audio.cpp.

◆ write_speaker()

esp_err_t esphome::usb_audio::USBAudioComponent::write_speaker	(	const uint8_t *	data,
		size_t	length,
		uint32_t	timeout_ms )

Definition at line 249 of file usb_audio.cpp.

Field Documentation

◆ controls_queued_

std::atomic<bool> esphome::usb_audio::USBAudioComponent::controls_queued_ {false}

protected

Definition at line 230 of file usb_audio.h.

◆ driver_busy_

std::atomic<bool> esphome::usb_audio::USBAudioComponent::driver_busy_ {false}

protected

Definition at line 232 of file usb_audio.h.

◆ driver_users_

std::atomic<uint8_t> esphome::usb_audio::USBAudioComponent::driver_users_ {0}

protected

Definition at line 233 of file usb_audio.h.

◆ endpoints_

std::array<EndpointState, 2> esphome::usb_audio::USBAudioComponent::endpoints_ {}

protected

Definition at line 215 of file usb_audio.h.

◆ event_queue_

QueueHandle_t esphome::usb_audio::USBAudioComponent::event_queue_ {nullptr}

protected

Definition at line 212 of file usb_audio.h.

◆ EVENT_QUEUE_LENGTH

size_t esphome::usb_audio::USBAudioComponent::EVENT_QUEUE_LENGTH = 16

staticconstexprprotected

Definition at line 109 of file usb_audio.h.

◆ event_queue_storage_

std::array<uint8_t, EVENT_QUEUE_LENGTH * sizeof(USBAudioEvent)> esphome::usb_audio::USBAudioComponent::event_queue_storage_ {}

protected

Definition at line 223 of file usb_audio.h.

◆ event_queue_struct_

StaticQueue_t esphome::usb_audio::USBAudioComponent::event_queue_struct_ {}

protected

Definition at line 221 of file usb_audio.h.

◆ lost_while_opening_

std::array<uac_host_device_handle_t, 2> esphome::usb_audio::USBAudioComponent::lost_while_opening_ {}

protected

Definition at line 218 of file usb_audio.h.

◆ mute_

ControlState esphome::usb_audio::USBAudioComponent::mute_ {}

protected

Definition at line 226 of file usb_audio.h.

◆ op_queue_

QueueHandle_t esphome::usb_audio::USBAudioComponent::op_queue_ {nullptr}

protected

Definition at line 214 of file usb_audio.h.

◆ OP_QUEUE_LENGTH

size_t esphome::usb_audio::USBAudioComponent::OP_QUEUE_LENGTH = 8

staticconstexprprotected

Definition at line 110 of file usb_audio.h.

◆ op_queue_storage_

std::array<uint8_t, OP_QUEUE_LENGTH * sizeof(Op)> esphome::usb_audio::USBAudioComponent::op_queue_storage_ {}

protected

Definition at line 224 of file usb_audio.h.

◆ op_queue_struct_

StaticQueue_t esphome::usb_audio::USBAudioComponent::op_queue_struct_ {}

protected

Definition at line 222 of file usb_audio.h.

◆ speaker_muted_

std::atomic<bool> esphome::usb_audio::USBAudioComponent::speaker_muted_ {false}

protected

Definition at line 228 of file usb_audio.h.

◆ SPEAKER_RING_SLACK

uint32_t esphome::usb_audio::USBAudioComponent::SPEAKER_RING_SLACK = 4

staticconstexprprotected

Definition at line 112 of file usb_audio.h.

◆ speaker_volume_

std::atomic<uint8_t> esphome::usb_audio::USBAudioComponent::speaker_volume_ {100}

protected

Definition at line 227 of file usb_audio.h.

◆ transfer_errors_

std::atomic<uint32_t> esphome::usb_audio::USBAudioComponent::transfer_errors_ {0}

protected

Definition at line 220 of file usb_audio.h.

◆ uac_installed_

bool esphome::usb_audio::USBAudioComponent::uac_installed_ {false}

protected

Definition at line 234 of file usb_audio.h.

◆ volume_

ControlState esphome::usb_audio::USBAudioComponent::volume_ {}

protected

Definition at line 225 of file usb_audio.h.

◆ worker_

StaticTask esphome::usb_audio::USBAudioComponent::worker_

protected

Definition at line 210 of file usb_audio.h.

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

esphome/components/usb_audio/usb_audio.h
esphome/components/usb_audio/usb_audio.cpp

Data Structures

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ apply_control_()

◆ apply_pending_speaker_controls_()

◆ begin_close_()

◆ device_event_stub()

◆ driver_event_stub()

◆ dump_config()

◆ endpoint_() [1/2]

◆ endpoint_() [2/2]

◆ enter_driver_()

◆ finish_closes_()

◆ get_setup_priority()

◆ handle_disconnect_()

◆ lock_driver_()

◆ loop()

◆ on_closed_()

◆ on_opened_()

◆ on_resumed_()

◆ on_started_()

◆ open_stream_()

◆ populate_stream_config_()

◆ post_event_()

◆ process_event_()

◆ process_events_()

◆ queue_controls_()

◆ queue_op_()

◆ read_microphone()

◆ register_microphone()

◆ register_speaker()

◆ resume()

◆ run_op_()

◆ set_speaker_mute_state()

◆ set_speaker_volume_level()

◆ setup()

◆ start_stream_()

◆ stream_failed_()

◆ suspend()

◆ teardown()

◆ unlock_driver_()

◆ worker_task()

◆ write_speaker()

Field Documentation

◆ controls_queued_

◆ driver_busy_

◆ driver_users_

◆ endpoints_

◆ event_queue_

◆ EVENT_QUEUE_LENGTH

◆ event_queue_storage_

◆ event_queue_struct_

◆ lost_while_opening_

◆ mute_

◆ op_queue_

◆ OP_QUEUE_LENGTH

◆ op_queue_storage_

◆ op_queue_struct_

◆ speaker_muted_

◆ SPEAKER_RING_SLACK

◆ speaker_volume_

◆ transfer_errors_

◆ uac_installed_

◆ volume_

◆ worker_