From 5e79c617e84bea388354ffe9716f10b71a89e93e Mon Sep 17 00:00:00 2001 From: kbx81 Date: Wed, 2 Sep 2026 14:19:52 -0500 Subject: [PATCH] [serial_proxy] Make port mode protocol-neutral Rename SERIAL_PROXY_MODE_EZSP_ASH to SERIAL_PROXY_MODE_PROTOCOL so the serial_proxy API surface carries no protocol-specific names. The mode now means "the port's tap is active"; which protocol the tap speaks is a property of the device configuration, discoverable from the tap component's own API surface. Future protocol taps need no serial_proxy or API changes. --- esphome/components/api/api.proto | 11 +++++++---- esphome/components/api/api_pb2.h | 2 +- esphome/components/api/api_pb2_dump.cpp | 4 ++-- esphome/components/serial_proxy/__init__.py | 9 +++++---- esphome/components/serial_proxy/serial_proxy.cpp | 6 +++--- tests/components/zigbee_proxy/common.yaml | 2 +- .../zigbee_proxy/test-usb.esp32-s3-idf.yaml | 2 +- 7 files changed, 20 insertions(+), 16 deletions(-) diff --git a/esphome/components/api/api.proto b/esphome/components/api/api.proto index 3e18ae03c0..f57579fd27 100644 --- a/esphome/components/api/api.proto +++ b/esphome/components/api/api.proto @@ -2845,12 +2845,15 @@ message SerialProxyRequestResponse { string error_message = 4; // Additional detail on failure (optional) } -// How a port treats the bytes passing through it. RAW is a plain byte pipe; EZSP_ASH lets -// a protocol-aware tap acknowledge NCP frames and read network metadata. A client that is -// about to flash firmware selects RAW first, which definitively disables that injection. +// How a port treats the bytes passing through it. RAW is a plain byte pipe; PROTOCOL +// activates the port's protocol-aware tap (if one is configured), letting it observe +// traffic and inject protocol bytes such as acknowledgements. Which protocol the tap +// speaks is a property of the device configuration, discoverable from the tap +// component's own API surface. A client that is about to flash firmware selects RAW +// first, which definitively disables that injection. enum SerialProxyMode { SERIAL_PROXY_MODE_RAW = 0; - SERIAL_PROXY_MODE_EZSP_ASH = 1; + SERIAL_PROXY_MODE_PROTOCOL = 1; } message SerialProxySetModeRequest { diff --git a/esphome/components/api/api_pb2.h b/esphome/components/api/api_pb2.h index 20570a68f2..26958e8a50 100644 --- a/esphome/components/api/api_pb2.h +++ b/esphome/components/api/api_pb2.h @@ -368,7 +368,7 @@ enum SerialProxyStatus : uint32_t { }; enum SerialProxyMode : uint32_t { SERIAL_PROXY_MODE_RAW = 0, - SERIAL_PROXY_MODE_EZSP_ASH = 1, + SERIAL_PROXY_MODE_PROTOCOL = 1, }; #endif #ifdef USE_ZIGBEE_PROXY diff --git a/esphome/components/api/api_pb2_dump.cpp b/esphome/components/api/api_pb2_dump.cpp index 840ac6939c..828e06f96d 100644 --- a/esphome/components/api/api_pb2_dump.cpp +++ b/esphome/components/api/api_pb2_dump.cpp @@ -882,8 +882,8 @@ template<> const char *proto_enum_to_string(enums::Seria switch (value) { case enums::SERIAL_PROXY_MODE_RAW: return ESPHOME_PSTR("SERIAL_PROXY_MODE_RAW"); - case enums::SERIAL_PROXY_MODE_EZSP_ASH: - return ESPHOME_PSTR("SERIAL_PROXY_MODE_EZSP_ASH"); + case enums::SERIAL_PROXY_MODE_PROTOCOL: + return ESPHOME_PSTR("SERIAL_PROXY_MODE_PROTOCOL"); default: return ESPHOME_PSTR("UNKNOWN"); } diff --git a/esphome/components/serial_proxy/__init__.py b/esphome/components/serial_proxy/__init__.py index e17518b148..158c9609e4 100644 --- a/esphome/components/serial_proxy/__init__.py +++ b/esphome/components/serial_proxy/__init__.py @@ -41,12 +41,13 @@ SERIAL_PROXY_PORT_TYPES = { } SerialProxyMode = api_enums_ns.enum("SerialProxyMode") -# The mode a port starts in. `raw` is a plain byte pipe; `ezsp_ash` lets a tap -# acknowledge NCP frames and read network metadata off the wire. Clients may change -# it at runtime, so this only decides what the device boots into. +# The mode a port starts in. `raw` is a plain byte pipe; `protocol` activates the +# port's tap (if one is configured), letting it observe traffic and inject protocol +# bytes such as acknowledgements. Clients may change it at runtime, so this only +# decides what the device boots into. SERIAL_PROXY_MODES = { "RAW": SerialProxyMode.SERIAL_PROXY_MODE_RAW, - "EZSP_ASH": SerialProxyMode.SERIAL_PROXY_MODE_EZSP_ASH, + "PROTOCOL": SerialProxyMode.SERIAL_PROXY_MODE_PROTOCOL, } CONF_DTR_PIN = "dtr_pin" diff --git a/esphome/components/serial_proxy/serial_proxy.cpp b/esphome/components/serial_proxy/serial_proxy.cpp index b6c2271be4..5d0e9cbbd7 100644 --- a/esphome/components/serial_proxy/serial_proxy.cpp +++ b/esphome/components/serial_proxy/serial_proxy.cpp @@ -130,7 +130,7 @@ bool SerialProxy::tap_observing_() const { // Otherwise the mode decides. RAW must be inert: a client that flips to RAW before // flashing firmware is entitled to a byte pipe with nothing injecting protocol bytes // into it, and "the tap turned out not to recognise the stream" is not good enough. - return this->mode_ == api::enums::SERIAL_PROXY_MODE_EZSP_ASH; + return this->mode_ == api::enums::SERIAL_PROXY_MODE_PROTOCOL; } void SerialProxy::tap_pump() { @@ -156,7 +156,7 @@ void SerialProxy::dump_config() { this->port_type_ == api::enums::SERIAL_PROXY_PORT_TYPE_RS485 ? LOG_STR_LITERAL("RS485") : this->port_type_ == api::enums::SERIAL_PROXY_PORT_TYPE_RS232 ? LOG_STR_LITERAL("RS232") : LOG_STR_LITERAL("TTL"), - this->mode_ == api::enums::SERIAL_PROXY_MODE_EZSP_ASH ? LOG_STR_LITERAL("EZSP_ASH") : LOG_STR_LITERAL("RAW"), + this->mode_ == api::enums::SERIAL_PROXY_MODE_PROTOCOL ? LOG_STR_LITERAL("PROTOCOL") : LOG_STR_LITERAL("RAW"), this->rts_pin_ != nullptr ? LOG_STR_LITERAL("configured") : LOG_STR_LITERAL("not configured"), this->dtr_pin_ != nullptr ? LOG_STR_LITERAL("configured") : LOG_STR_LITERAL("not configured")); } @@ -239,7 +239,7 @@ void SerialProxy::set_mode(api::APIConnection *api_connection, api::enums::Seria } #endif ESP_LOGD(TAG, "Serial proxy [%" PRIu32 "] mode set to %s", this->instance_index_, - mode == api::enums::SERIAL_PROXY_MODE_EZSP_ASH ? "EZSP_ASH" : "RAW"); + mode == api::enums::SERIAL_PROXY_MODE_PROTOCOL ? "PROTOCOL" : "RAW"); const bool leaving_protocol_mode = this->mode_ != api::enums::SERIAL_PROXY_MODE_RAW && mode == api::enums::SERIAL_PROXY_MODE_RAW; this->mode_ = mode; diff --git a/tests/components/zigbee_proxy/common.yaml b/tests/components/zigbee_proxy/common.yaml index 8623b73991..91e27efd7d 100644 --- a/tests/components/zigbee_proxy/common.yaml +++ b/tests/components/zigbee_proxy/common.yaml @@ -20,4 +20,4 @@ serial_proxy: uart_id: zigbee_uart name: Zigbee port_type: TTL - mode: ezsp_ash + mode: protocol diff --git a/tests/components/zigbee_proxy/test-usb.esp32-s3-idf.yaml b/tests/components/zigbee_proxy/test-usb.esp32-s3-idf.yaml index 8d7407ce01..93b7707d16 100644 --- a/tests/components/zigbee_proxy/test-usb.esp32-s3-idf.yaml +++ b/tests/components/zigbee_proxy/test-usb.esp32-s3-idf.yaml @@ -22,7 +22,7 @@ serial_proxy: uart_id: zigbee_usb_channel name: Zigbee port_type: TTL - mode: ezsp_ash + mode: protocol zigbee_proxy: serial_proxy_id: zigbee_usb_serial