ESP-IDF UART driver wrapper. More...

#include <uart_component_esp_idf.h>

Inheritance diagram for esphome::uart::IDFUARTComponent:

Data Structures
struct	Framing

Public Member Functions
	IDFUARTComponent ()

void	setup () override

void	dump_config () override

float	get_setup_priority () const override

void	set_rx_full_threshold (size_t rx_full_threshold) override

void	set_rx_timeout (size_t rx_timeout) override

void	write_array (const uint8_t *data, size_t len) override

bool	peek_byte (uint8_t *data) override

bool	read_array (uint8_t *data, size_t len) override

size_t	available () override

size_t	available_for_write () override

UARTFlushResult	flush () override

void	set_flush_timeout (uint32_t flush_timeout_ms) override

void	set_tx_buffer_size (size_t tx_buffer_size)
	TX ring buffer size for the driver; 0 leaves TX unbuffered so write_array() blocks until the FIFO has taken everything.

void	set_clock_source (uart_sclk_t clock_source)

uint8_t	get_hw_serial_number ()

void	flush_input ()
	Discard everything received so far: the peek cache and the driver's RX buffer.

void	load_settings (bool dump_config) override
	Load the UART with the current settings.

esp_err_t	apply_settings_live ()
	Apply the current framing (baud rate, parity, data/stop bits) to the installed driver in place, without the delete/reinstall of load_settings().

void	on_shutdown () override

void	load_settings ()
	Load the UART settings.

Public Member Functions inherited from esphome::uart::UARTComponent
void	write_array (const std::vector< uint8_t > &data)

void	write_byte (uint8_t data)

void	write_str (const char *str)

void	write_array_progmem (const uint8_t *data, size_t len)

void	write_array_progmem (const uint8_t *data, size_t len)

bool	read_byte (uint8_t *data)

size_t	paced_write_room (uint32_t last_write_ms)

virtual bool	is_connected ()

void	set_tx_pin (InternalGPIOPin *tx_pin)

void	set_rx_pin (InternalGPIOPin *rx_pin)

void	set_flow_control_pin (InternalGPIOPin *flow_control_pin)

void	set_rx_buffer_size (size_t rx_buffer_size)

size_t	get_rx_buffer_size ()

void	set_rx_full_threshold_ms (uint8_t time)

size_t	get_rx_full_threshold ()

size_t	get_rx_timeout ()

void	set_stop_bits (uint8_t stop_bits)

uint8_t	get_stop_bits () const

void	set_data_bits (uint8_t data_bits)

uint8_t	get_data_bits () const

void	set_parity (UARTParityOptions parity)

UARTParityOptions	get_parity () const

void	set_baud_rate (uint32_t baud_rate)

uint32_t	get_baud_rate () const

void	set_flow_control (UARTFlowControl flow_control)

UARTFlowControl	get_flow_control () const

void	load_settings ()
	Load the UART settings.

template<typename F >
void	add_debug_callback (F &&callback)

Public Member Functions inherited from esphome::Component
virtual void	loop ()
	This method will be called repeatedly.

float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

void	call ()

virtual void	on_safe_shutdown ()

virtual bool	teardown ()
	Called during teardown to allow component to gracefully finish operations.

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
void	check_logger_conflict () override

void	set_pins_hold_ (bool hold)

uint32_t	line_inversion_mask_ ()

esp_err_t	apply_line_settings_ ()

uart_config_t	get_config_ ()

Framing	framing_ () const

void	set_framing_ (const Framing &framing)

Protected Member Functions inherited from esphome::uart::UARTComponent
bool	check_read_timeout_ (size_t len=1)

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	uart_rx_isr_callback (uart_port_t uart_num, uart_select_notif_t uart_select_notif, BaseType_t *task_woken)

Protected Attributes
uart_port_t	uart_num_ {UART_NUM_MAX}

Framing	last_good_framing_ {}

bool	has_peek_ {false}

uint8_t	peek_byte_ {0}

uint8_t	clock_source_ {UART_SCLK_DEFAULT}
	uart_sclk_t stored in a byte; the IDF values are all small.

uint32_t	flush_timeout_ms_ {0}
	0 means wait indefinitely (portMAX_DELAY).

size_t	tx_buffer_size_ {0}

Protected Attributes inherited from esphome::uart::UARTComponent
InternalGPIOPin *	tx_pin_ {}

InternalGPIOPin *	rx_pin_ {}

InternalGPIOPin *	flow_control_pin_ {}

size_t	rx_buffer_size_ {}

size_t	rx_full_threshold_ {RX_FULL_THRESHOLD_UNSET}

size_t	rx_timeout_ {0}

uint32_t	baud_rate_ {0}

uint8_t	stop_bits_ {0}

uint8_t	data_bits_ {0}

UARTFlowControl	flow_control_ {UART_FLOW_CONTROL_NONE}

UARTParityOptions	parity_ {UART_CONFIG_PARITY_NONE}

CallbackManager< void(UARTDirection, uint8_t)>	debug_callback_ {}

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_

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

Static Public Attributes inherited from esphome::uart::UARTComponent
static constexpr size_t	RX_FULL_THRESHOLD_UNSET = 0

Detailed Description

ESP-IDF UART driver wrapper.

Thread safety: All public methods must only be called from the main loop. The ESP-IDF UART driver API does not guarantee thread safety, and ESPHome's peek byte state (has_peek_/peek_byte_) is not synchronized.

Definition at line 19 of file uart_component_esp_idf.h.

Constructor & Destructor Documentation

◆ IDFUARTComponent()

esphome::uart::IDFUARTComponent::IDFUARTComponent ( )

inline

Definition at line 22 of file uart_component_esp_idf.h.

Member Function Documentation

◆ apply_line_settings_()

esp_err_t esphome::uart::IDFUARTComponent::apply_line_settings_ ( )

protected

Definition at line 273 of file uart_component_esp_idf.cpp.

◆ apply_settings_live()

esp_err_t esphome::uart::IDFUARTComponent::apply_settings_live ( )

Apply the current framing (baud rate, parity, data/stop bits) to the installed driver in place, without the delete/reinstall of load_settings().

Tasks blocked in the driver survive and the ring buffers are kept, but both hardware FIFOs are flushed: a frame in flight reaches the peer truncated and bytes not yet out of the RX FIFO are dropped. No lock is taken: quiesce writers first if that matters. rx_full_threshold is not rescaled (call set_rx_full_threshold_ms() first if it should follow the baud rate); a rollback restores the value from the last accepted configuration, undoing a standalone set_rx_full_threshold() made since. Without an installed driver this is a full load_settings(false) instead.

Returns: ESP_OK once the new framing is live (a line-setting error after that only logs). On rejection (unreachable baud rate) the previous framing is restored and the driver's error returned; if the restore fails too the component is marked failed. ESP_ERR_INVALID_STATE if already failed; ESP_FAIL if the fallback load_settings() fails.

Definition at line 312 of file uart_component_esp_idf.cpp.

◆ available()

size_t esphome::uart::IDFUARTComponent::available ( )

overridevirtual

Implements esphome::uart::UARTComponent.

Definition at line 472 of file uart_component_esp_idf.cpp.

◆ available_for_write()

size_t esphome::uart::IDFUARTComponent::available_for_write ( )

overridevirtual

Reimplemented from esphome::uart::UARTComponent.

Definition at line 407 of file uart_component_esp_idf.cpp.

◆ check_logger_conflict()

void esphome::uart::IDFUARTComponent::check_logger_conflict ( )

overrideprotectedvirtual

Implements esphome::uart::UARTComponent.

Definition at line 499 of file uart_component_esp_idf.cpp.

◆ dump_config()

void esphome::uart::IDFUARTComponent::dump_config ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 352 of file uart_component_esp_idf.cpp.

◆ flush()

UARTFlushResult esphome::uart::IDFUARTComponent::flush ( )

overridevirtual

Implements esphome::uart::UARTComponent.

Definition at line 488 of file uart_component_esp_idf.cpp.

◆ flush_input()

void esphome::uart::IDFUARTComponent::flush_input ( )

inline

Discard everything received so far: the peek cache and the driver's RX buffer.

Definition at line 50 of file uart_component_esp_idf.h.

◆ framing_()

Framing esphome::uart::IDFUARTComponent::framing_ ( ) const

inlineprotected

Definition at line 109 of file uart_component_esp_idf.h.

◆ get_config_()

uart_config_t esphome::uart::IDFUARTComponent::get_config_ ( )

protected

Definition at line 68 of file uart_component_esp_idf.cpp.

◆ get_hw_serial_number()

uint8_t esphome::uart::IDFUARTComponent::get_hw_serial_number ( )

inline

Definition at line 47 of file uart_component_esp_idf.h.

◆ get_setup_priority()

float esphome::uart::IDFUARTComponent::get_setup_priority ( ) const

inlineoverridevirtual

Reimplemented from esphome::Component.

Definition at line 25 of file uart_component_esp_idf.h.

◆ line_inversion_mask_()

uint32_t esphome::uart::IDFUARTComponent::line_inversion_mask_ ( )

protected

Definition at line 259 of file uart_component_esp_idf.cpp.

◆ load_settings() [1/2]

void esphome::uart::UARTComponent::load_settings ( )

inline

Load the UART settings.

Example:

id(uart1).load_settings();

id

uint16_t id

Definition dns_server_esp32_idf.cpp:0

This will load the current UART interface with the latest settings (baud_rate, parity, etc).

Definition at line 229 of file uart_component.h.

◆ load_settings() [2/2]

void esphome::uart::IDFUARTComponent::load_settings ( bool dump_config )

overridevirtual

Load the UART with the current settings.

Parameters

dump_config (Optional, default true): True for displaying new settings or false to change it quitely

Example:

id(uart1).load_settings();

This will load the current UART interface with the latest settings (baud_rate, parity, etc).

Implements esphome::uart::UARTComponent.

Definition at line 153 of file uart_component_esp_idf.cpp.

◆ on_shutdown()

void esphome::uart::IDFUARTComponent::on_shutdown ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 512 of file uart_component_esp_idf.cpp.

◆ peek_byte()

bool esphome::uart::IDFUARTComponent::peek_byte ( uint8_t * data )

overridevirtual

Implements esphome::uart::UARTComponent.

Definition at line 432 of file uart_component_esp_idf.cpp.

◆ read_array()

bool esphome::uart::IDFUARTComponent::read_array	(	uint8_t *	data,
		size_t	len )

overridevirtual

Implements esphome::uart::UARTComponent.

Definition at line 449 of file uart_component_esp_idf.cpp.

◆ set_clock_source()

void esphome::uart::IDFUARTComponent::set_clock_source ( uart_sclk_t clock_source )

inline

Definition at line 45 of file uart_component_esp_idf.h.

◆ set_flush_timeout()

void esphome::uart::IDFUARTComponent::set_flush_timeout ( uint32_t flush_timeout_ms )

inlineoverridevirtual

Reimplemented from esphome::uart::UARTComponent.

Definition at line 39 of file uart_component_esp_idf.h.

◆ set_framing_()

void esphome::uart::IDFUARTComponent::set_framing_ ( const Framing & framing )

protected

Definition at line 304 of file uart_component_esp_idf.cpp.

◆ set_pins_hold_()

void esphome::uart::IDFUARTComponent::set_pins_hold_ ( bool hold )

protected

Definition at line 528 of file uart_component_esp_idf.cpp.

◆ set_rx_full_threshold()

void esphome::uart::IDFUARTComponent::set_rx_full_threshold ( size_t rx_full_threshold )

overridevirtual

Reimplemented from esphome::uart::UARTComponent.

Definition at line 385 of file uart_component_esp_idf.cpp.

◆ set_rx_timeout()

void esphome::uart::IDFUARTComponent::set_rx_timeout ( size_t rx_timeout )

overridevirtual

Reimplemented from esphome::uart::UARTComponent.

Definition at line 396 of file uart_component_esp_idf.cpp.

◆ set_tx_buffer_size()

void esphome::uart::IDFUARTComponent::set_tx_buffer_size ( size_t tx_buffer_size )

inline

TX ring buffer size for the driver; 0 leaves TX unbuffered so write_array() blocks until the FIFO has taken everything.

Definition at line 43 of file uart_component_esp_idf.h.

◆ setup()

void esphome::uart::IDFUARTComponent::setup ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 107 of file uart_component_esp_idf.cpp.

◆ uart_rx_isr_callback()

void IRAM_ATTR esphome::uart::IDFUARTComponent::uart_rx_isr_callback	(	uart_port_t	uart_num,
		uart_select_notif_t	uart_select_notif,
		BaseType_t *	task_woken )

staticprotected

Definition at line 504 of file uart_component_esp_idf.cpp.

◆ write_array()

void esphome::uart::IDFUARTComponent::write_array	(	const uint8_t *	data,
		size_t	len )

overridevirtual

Implements esphome::uart::UARTComponent.

Definition at line 419 of file uart_component_esp_idf.cpp.

Field Documentation

◆ clock_source_

uint8_t esphome::uart::IDFUARTComponent::clock_source_ {UART_SCLK_DEFAULT}

protected

uart_sclk_t stored in a byte; the IDF values are all small.

Definition at line 118 of file uart_component_esp_idf.h.

◆ flush_timeout_ms_

uint32_t esphome::uart::IDFUARTComponent::flush_timeout_ms_ {0}

protected

0 means wait indefinitely (portMAX_DELAY).

Definition at line 119 of file uart_component_esp_idf.h.

◆ has_peek_

bool esphome::uart::IDFUARTComponent::has_peek_ {false}

protected

Definition at line 116 of file uart_component_esp_idf.h.

◆ last_good_framing_

Framing esphome::uart::IDFUARTComponent::last_good_framing_ {}

protected

Definition at line 114 of file uart_component_esp_idf.h.

◆ peek_byte_

uint8_t esphome::uart::IDFUARTComponent::peek_byte_ {0}

protected

Definition at line 117 of file uart_component_esp_idf.h.

◆ tx_buffer_size_

size_t esphome::uart::IDFUARTComponent::tx_buffer_size_ {0}

protected

Definition at line 120 of file uart_component_esp_idf.h.

◆ uart_num_

uart_port_t esphome::uart::IDFUARTComponent::uart_num_ {UART_NUM_MAX}

protected

Definition at line 99 of file uart_component_esp_idf.h.

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

esphome/components/uart/uart_component_esp_idf.h
esphome/components/uart/uart_component_esp_idf.cpp

Data Structures

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ IDFUARTComponent()

Member Function Documentation

◆ apply_line_settings_()

◆ apply_settings_live()

◆ available()

◆ available_for_write()

◆ check_logger_conflict()

◆ dump_config()

◆ flush()

◆ flush_input()

◆ framing_()

◆ get_config_()

◆ get_hw_serial_number()

◆ get_setup_priority()

◆ line_inversion_mask_()

◆ load_settings() [1/2]

◆ load_settings() [2/2]

◆ on_shutdown()

◆ peek_byte()

◆ read_array()

◆ set_clock_source()

◆ set_flush_timeout()

◆ set_framing_()

◆ set_pins_hold_()

◆ set_rx_full_threshold()

◆ set_rx_timeout()

◆ set_tx_buffer_size()

◆ setup()

◆ uart_rx_isr_callback()

◆ write_array()

Field Documentation

◆ clock_source_

◆ flush_timeout_ms_

◆ has_peek_

◆ last_good_framing_

◆ peek_byte_

◆ tx_buffer_size_

◆ uart_num_