|
ESPHome 2026.10.0-dev
|
ESPHomeOTAComponent provides a simple way to integrate Over-the-Air updates into your app using ArduinoOTA. More...
#include <ota_esphome.h>
Data Structures | |
| struct | NoiseSession |
Public Types | |
| enum class | OTAState : uint8_t { IDLE , MAGIC_READ , MAGIC_ACK , FEATURE_READ , FEATURE_ACK , AUTH_SEND , AUTH_READ , NOISE_HANDSHAKE , DATA } |
Public Member Functions | |
| void | set_auth_password (const std::string &password) |
| template<bool B = false> | |
| void | set_auth_password (const std::string &) |
| void | set_noise_psk (const uint8_t *psk) |
| psk points at 32 bytes that live in flash for the life of the program | |
| void | set_port (uint16_t port) |
| Manually set the port OTA should listen on. | |
| void | setup () override |
| void | dump_config () override |
| float | get_setup_priority () const override |
| void | loop () override |
| uint16_t | get_port () const |
Public Member Functions inherited from esphome::ota::OTAComponent | |
| void | add_state_listener (OTAStateListener *listener) |
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 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) |
| void | status_set_error () |
| void | status_set_error (const LogString *message) |
| void | status_clear_warning () |
| void | status_clear_error () |
| void | status_momentary_warning (const char *name, uint32_t length=5000) |
| Set warning status flag and automatically clear it after a timeout. | |
| void | status_momentary_error (const char *name, uint32_t length=5000) |
| Set error status flag and automatically clear it after a timeout. | |
| 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 | handle_handshake_ () |
| void | handle_data_ () |
| bool | handle_auth_send_ () |
| bool | handle_auth_read_ () |
| bool | select_auth_type_ () |
| void | cleanup_auth_ () |
| void | log_auth_warning_ (const LogString *msg) |
| bool | readall_ (uint8_t *buf, size_t len) |
| bool | writeall_ (const uint8_t *buf, size_t len) |
| bool | write_byte_ (uint8_t byte) |
| const noise::NoiseContext & | noise_context_ () const |
| bool | noise_start_session_ (uint8_t server_feature_flags) |
| Allocate the session and start the responder handshake. | |
| bool | handle_noise_handshake_ () |
| Drive the non-blocking handshake from loop(); returns true once the transport ciphers are ready. | |
| bool | noise_try_read_frame_ () |
| Non-blocking read of one handshake frame into the session buffer. | |
| size_t | noise_frame_payload_len_ (const uint8_t *header, size_t min_len, size_t max_len) |
| Payload length from a frame header, or 0 (logged) when the indicator or the length is out of range. | |
| bool | noise_try_write_frame_ () |
| Non-blocking write of the pending session-buffer frame. | |
| void | noise_send_reject_ (const LogString *reason) |
| Best-effort explicit reject frame so the client can log a readable reason. | |
| ssize_t | noise_decrypt_ (uint8_t *buf, size_t len) |
| Decrypt a ciphertext in place; returns the plaintext size or -1. | |
| ssize_t | noise_read_frame_blocking_ (uint8_t *buf, size_t min_ciphertext, size_t max_ciphertext) |
| Blocking read of one frame whose ciphertext size must be within the given bounds, decrypted in place; returns the plaintext size, or -1 on error. | |
| bool | noise_readall_ (uint8_t *buf, size_t len) |
| Blocking read of one frame whose plaintext must be exactly len bytes (control units are one unit per frame). | |
| ssize_t | noise_read_data_ (uint8_t *buf, size_t capacity) |
| Blocking read of one data-phase frame, decrypted in place; returns the plaintext size, or -1 on error. | |
| bool | noise_write_byte_ (uint8_t byte) |
| Blocking write of one response byte as an encrypted frame. | |
| bool | data_write_byte_ (uint8_t byte) |
| bool | data_readall_ (uint8_t *buf, size_t len) |
| bool | try_read_ (size_t to_read, const LogString *desc) |
| bool | try_write_ (size_t to_write, const LogString *desc) |
| bool | would_block_ (int error_code) const |
| bool | handle_read_error_ (ssize_t read, const LogString *desc) |
| bool | handle_write_error_ (ssize_t written, const LogString *desc) |
| void | transition_ota_state_ (OTAState next_state) |
| void | server_failed_ (const LogString *msg) |
| void | log_socket_error_ (const LogString *msg) |
| void | log_read_error_ (const LogString *what) |
| void | log_start_ (const LogString *phase) |
| void | log_remote_closed_ (const LogString *during) |
| void | cleanup_connection_ () |
| void | send_error_and_cleanup_ (ota::OTAResponseTypes error) |
| void | yield_and_feed_watchdog_ () |
| bool | extended_proto_ () const |
Protected Member Functions inherited from esphome::ota::OTAComponent | |
| void | notify_state_ (OTAState state, float progress, uint8_t error) |
| void | notify_state_deferred_ (OTAState state, float progress, uint8_t error) |
| Notify state with deferral to main loop (for thread safety). | |
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. | |
| 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_ () |
Protected Attributes | |
| std::string | password_ |
| std::unique_ptr< uint8_t[]> | auth_buf_ |
| noise::NoiseContext | noise_ctx_ |
| std::unique_ptr< NoiseSession > | noise_ |
| socket::ListenSocket * | server_ {nullptr} |
| std::unique_ptr< socket::Socket > | client_ |
| ota::OTABackendPtr | backend_ |
| uint32_t | client_connect_time_ {0} |
| uint32_t | running_app_offset_ {0} |
| size_t | running_app_size_ {0} |
| uint16_t | port_ |
| uint8_t | handshake_buf_ [HANDSHAKE_BUF_SIZE] |
| OTAState | ota_state_ {OTAState::IDLE} |
| uint8_t | handshake_buf_pos_ {0} |
| uint8_t | ota_features_ {0} |
| uint8_t | auth_buf_pos_ {0} |
| uint8_t | auth_type_ {0} |
Protected Attributes inherited from esphome::ota::OTAComponent | |
| std::vector< OTAStateListener * > | state_listeners_ |
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 | SHA256_HEX_SIZE = 64 |
| static constexpr size_t | HANDSHAKE_BUF_SIZE = 5 |
| static constexpr size_t | OTA_BUFFER_SIZE = 1040 |
| static constexpr size_t | NOISE_CLIENT_MAX_PLAINTEXT = 1024 |
| static constexpr uint8_t | MAGIC_BYTES [5] = {0x6C, 0x26, 0xF7, 0x5C, 0x45} |
ESPHomeOTAComponent provides a simple way to integrate Over-the-Air updates into your app using ArduinoOTA.
Definition at line 18 of file ota_esphome.h.
|
strong |
| Enumerator | |
|---|---|
| IDLE | |
| MAGIC_READ | |
| MAGIC_ACK | |
| FEATURE_READ | |
| FEATURE_ACK | |
| AUTH_SEND | |
| AUTH_READ | |
| NOISE_HANDSHAKE | |
| DATA | |
Definition at line 20 of file ota_esphome.h.
|
protected |
Definition at line 944 of file ota_esphome.cpp.
|
protected |
Definition at line 777 of file ota_esphome.cpp.
|
inlineprotected |
Definition at line 114 of file ota_esphome.h.
|
inlineprotected |
Definition at line 106 of file ota_esphome.h.
|
overridevirtual |
Reimplemented from esphome::Component.
Definition at line 111 of file ota_esphome.cpp.
|
inlineprotected |
Definition at line 192 of file ota_esphome.cpp.
|
inline |
Definition at line 60 of file ota_esphome.h.
|
overridevirtual |
Reimplemented from esphome::Component.
Definition at line 697 of file ota_esphome.cpp.
|
protected |
Definition at line 886 of file ota_esphome.cpp.
|
protected |
Definition at line 817 of file ota_esphome.cpp.
|
protected |
Handle the OTA data transfer and update process.
This method is blocking and will not return until the OTA update completes, fails, or times out. It receives the firmware data, writes it to flash, and reboots on success.
Authentication has already been handled in the non-blocking states AUTH_SEND/AUTH_READ.
Socket I/O strategy:
Before this function, the handshake states use non-blocking I/O: read()/write() return immediately with EWOULDBLOCK if no data loop() retries on next iteration (~16ms), no delay needed
This function switches to blocking mode with SO_RCVTIMEO/SO_SNDTIMEO:
| Path | Wait mechanism | WDT strategy |
|---|---|---|
| Main read | SO_RCVTIMEO (2s block) | feed_wdt() only, no delay |
| readall_() | SO_RCVTIMEO (2s block) | feed_wdt() + delay(0) |
| writeall_() | SO_SNDTIMEO (2s block) | feed_wdt() + delay(1) |
readall_() uses delay(0) because SO_RCVTIMEO already waited — just yield. writeall_() uses delay(1) because on raw TCP (ESP8266, RP2040) writes never block (tcp_write returns immediately), so delay(1) prevents spinning.
Platform details: BSD sockets (ESP32): setblocking(true) makes read/write block lwip sockets (LT): setblocking(true) makes read/write block Raw TCP (8266, RP2040): setblocking is no-op; SO_RCVTIMEO uses wakeable_delay() in read(); write() always returns immediately
Definition at line 397 of file ota_esphome.cpp.
|
protected |
Handle the OTA handshake and authentication.
This method is non-blocking and will return immediately if no data is available. It manages the state machine through connection, magic bytes validation, feature negotiation, and authentication before entering the blocking data transfer phase.
Definition at line 201 of file ota_esphome.cpp.
|
protected |
Drive the non-blocking handshake from loop(); returns true once the transport ciphers are ready.
A would-block returns false and the next loop() resumes from the NoiseSession cursors; on failure the connection is cleaned up.
Definition at line 86 of file ota_esphome_noise.cpp.
|
protected |
Definition at line 724 of file ota_esphome.cpp.
|
protected |
Definition at line 737 of file ota_esphome.cpp.
|
protected |
Definition at line 802 of file ota_esphome.cpp.
|
protected |
Definition at line 703 of file ota_esphome.cpp.
|
protected |
Definition at line 711 of file ota_esphome.cpp.
|
protected |
Definition at line 699 of file ota_esphome.cpp.
|
protected |
Definition at line 705 of file ota_esphome.cpp.
|
overridevirtual |
Reimplemented from esphome::Component.
Definition at line 169 of file ota_esphome.cpp.
|
protected |
Definition at line 34 of file ota_esphome.cpp.
|
protected |
Decrypt a ciphertext in place; returns the plaintext size or -1.
Definition at line 219 of file ota_esphome_noise.cpp.
|
protected |
Payload length from a frame header, or 0 (logged) when the indicator or the length is out of range.
Callers pass min_len >= 1 so 0 is never valid.
Definition at line 159 of file ota_esphome_noise.cpp.
|
protected |
Blocking read of one data-phase frame, decrypted in place; returns the plaintext size, or -1 on error.
buf is the OTA_BUFFER_SIZE data buffer. The ciphertext must fit that buffer and its plaintext must fit what the caller accepts (the remaining image bytes).
Definition at line 263 of file ota_esphome_noise.cpp.
|
protected |
Blocking read of one frame whose ciphertext size must be within the given bounds, decrypted in place; returns the plaintext size, or -1 on error.
buf needs max_ciphertext capacity.
Definition at line 235 of file ota_esphome_noise.cpp.
|
protected |
Blocking read of one frame whose plaintext must be exactly len bytes (control units are one unit per frame).
buf needs len + noise::MAC_SIZE capacity; the plaintext lands at buf[0..len).
Definition at line 254 of file ota_esphome_noise.cpp.
|
protected |
Best-effort explicit reject frame so the client can log a readable reason.
Definition at line 208 of file ota_esphome_noise.cpp.
|
protected |
Allocate the session and start the responder handshake.
The prologue binds the whole plaintext preamble, so any tampering with the negotiation (a stripped feature flag, a changed version) breaks the first handshake MAC on either side: "NoiseOTAInit" | magic(5) | OK,version | client_features | FEATURE_FLAGS,server_flags
Definition at line 43 of file ota_esphome_noise.cpp.
|
protected |
Non-blocking read of one handshake frame into the session buffer.
Definition at line 169 of file ota_esphome_noise.cpp.
|
protected |
Non-blocking write of the pending session-buffer frame.
Definition at line 195 of file ota_esphome_noise.cpp.
|
protected |
Blocking write of one response byte as an encrypted frame.
Definition at line 269 of file ota_esphome_noise.cpp.
|
protected |
Definition at line 639 of file ota_esphome.cpp.
|
protected |
Definition at line 804 of file ota_esphome.cpp.
|
inlineprotected |
Definition at line 139 of file ota_esphome.h.
|
protected |
Definition at line 715 of file ota_esphome.cpp.
|
inline |
Definition at line 40 of file ota_esphome.h.
|
inline |
Definition at line 36 of file ota_esphome.h.
|
inline |
psk points at 32 bytes that live in flash for the life of the program
Definition at line 49 of file ota_esphome.h.
|
inline |
Manually set the port OTA should listen on.
Definition at line 53 of file ota_esphome.h.
|
overridevirtual |
Reimplemented from esphome::Component.
Definition at line 60 of file ota_esphome.cpp.
|
inlineprotected |
Definition at line 128 of file ota_esphome.h.
|
protected |
Definition at line 749 of file ota_esphome.cpp.
|
protected |
Definition at line 763 of file ota_esphome.cpp.
|
inlineprotected |
Definition at line 125 of file ota_esphome.h.
|
inlineprotected |
Definition at line 75 of file ota_esphome.h.
|
protected |
Definition at line 669 of file ota_esphome.cpp.
|
protected |
Definition at line 796 of file ota_esphome.cpp.
|
protected |
Definition at line 148 of file ota_esphome.h.
|
protected |
Definition at line 187 of file ota_esphome.h.
|
protected |
Definition at line 188 of file ota_esphome.h.
|
protected |
Definition at line 159 of file ota_esphome.h.
|
protected |
Definition at line 158 of file ota_esphome.h.
|
protected |
Definition at line 161 of file ota_esphome.h.
|
protected |
Definition at line 182 of file ota_esphome.h.
|
protected |
Definition at line 184 of file ota_esphome.h.
|
staticconstexprprotected |
Definition at line 162 of file ota_esphome.h.
|
staticconstexprprotected |
Definition at line 174 of file ota_esphome.h.
|
protected |
Definition at line 154 of file ota_esphome.h.
|
staticconstexprprotected |
Definition at line 170 of file ota_esphome.h.
|
protected |
Definition at line 152 of file ota_esphome.h.
|
staticconstexprprotected |
Definition at line 166 of file ota_esphome.h.
|
protected |
Definition at line 185 of file ota_esphome.h.
|
protected |
Definition at line 183 of file ota_esphome.h.
|
protected |
Definition at line 147 of file ota_esphome.h.
|
protected |
Definition at line 181 of file ota_esphome.h.
|
protected |
Definition at line 178 of file ota_esphome.h.
|
protected |
Definition at line 179 of file ota_esphome.h.
|
protected |
Definition at line 157 of file ota_esphome.h.
|
staticconstexprprotected |
Definition at line 66 of file ota_esphome.h.