[packet_interface] Add session and XXTEA encryption layers (#21088)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>

.agents/skills/hardware-test/SKILL.md

@@ -115,7 +115,7 @@ Per-topic scripts, each described in the matching `reference/recipes/<component>
 (host driver, Zephyr driver probe), `rtsp_server/` (protocol client, raw rate reader, measurement set,
 API image grab), `cse7766/` (API observer with ping), `zephyr_coredump/` (reader flow, decode with the
 Zephyr tools), `libretiny_prefs/` (rtc preference harness header), `libretiny_crash/` (BK72xx crash probe header and
-capture decoder), `api_outgoing/` (wake cycle and Wi-Fi drop timing readers), `ld2450/` (zone number driver), `dfrobot_sen0395/` (API driver and case runner), `homeassistant_light/` (direct bulb driver, held-report case driver), `usb_audio/` (URL player), `speaker_media_player/` (API player driver, pipeline task case runner), `web_server/` (SSE client, request mix, SSE and HTTPD case runners), `mqtt/` (broker config with TLS, client-certificate and WebSocket listeners, test CA with server and client certificates, transport case runner, flash-and-drive runner, CLI TLS check without a board), `udp/` (datagram recorder, `udp.write` payload checker and case driver), `entity_icons/` (icon and device class readback over the API, MQTT discovery, web_server and dump_config, with a comparer).
+capture decoder), `api_outgoing/` (wake cycle and Wi-Fi drop timing readers), `ld2450/` (zone number driver, loopback harness driver with number and binary sensor states and TX frame summarizer), `api/` (raw plaintext native API client for user defined actions, store_yaml recovery client over Noise or plaintext), `http_request/` (update manifest server, update state driver), `modem/` (button and sensor driver over the plaintext API, also used for the BLE MIDI boards), `dfrobot_sen0395/` (API driver and case runner), `homeassistant_light/` (direct bulb driver, held-report case driver), `usb_audio/` (URL player), `speaker_media_player/` (API player driver, pipeline task case runner), `web_server/` (SSE client, request mix, SSE and HTTPD case runners), `mqtt/` (broker config with TLS, client-certificate and WebSocket listeners, test CA with server and client certificates, transport case runner, flash-and-drive runner, CLI TLS check without a board), `udp/` (datagram recorder, `udp.write` payload checker and case driver), `entity_icons/` (icon and device class readback over the API, MQTT discovery, web_server and dump_config, with a comparer).
 
 ## Templates in `$SKILL/templates`
 
@@ -132,7 +132,10 @@ capture decoder), `api_outgoing/` (wake cycle and Wi-Fi drop timing readers), `l
   `globals-storage-dut.yaml`, `usb-audio-waveshare-s3-eth-dut.yaml`, `usb-audio-sendspin-s3-eth-dut.yaml`,
   `cast-pro-1-sendspin-control.yaml`, `aux-2-preprod-stock-dut.yaml`, `aux-2-preprod-usb-audio-dut.yaml`,
   `dfrobot-sen0395-dut.yaml`, `aux-2-preprod-speaker-player-dut.yaml`, `web-server-sse-dut.yaml`,
-  `mqtt-transport-dut.yaml`, `mqtt-tls-dut.yaml`, `udp-write-dut.yaml`, `entity-icon-dut.yaml`.
+  `mqtt-transport-dut.yaml`, `mqtt-tls-dut.yaml`, `udp-write-dut.yaml`, `entity-icon-dut.yaml`,
+  and the directories `store_yaml/` (package with secrets one directory up, per-board files),
+  `http_request_update/` (manifest URL setter shapes, per-board files), `modem/` (modem only and modem plus
+  Wi-Fi boot checks) and `ble_midi/` (fake BLE MIDI instrument and the client).
 
 ## When something looks wrong
 

.agents/skills/hardware-test/reference/boards.md

@@ -7,6 +7,9 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
 
 - Opening the port usually resets the board through DTR, but not always; `serial_capture.py --reset`
   pulses RTS to capture from boot. 74880 baud shows the ROM boot messages (`rst cause`, `boot mode`).
+- UART0 can be looped back onto itself (`USC0(0) |= (1 << UCLBE)` in an `on_boot` lambda) so a UART
+  component is testable without its device: frames written with `uart.write` arrive on RX. Log over the
+  API with `logger: baud_rate: 0`, since the serial port carries the component's bytes.
 - `esphome logs` on some CH340s emits thousands of duplicated garbage lines right after the RTS reset;
   a plain pyserial capture at 115200 is reliable.
 - A failed esptool write can wedge the adapter (`termios` error 22, or an open that hangs) until replug.

.agents/skills/hardware-test/reference/recipes/README.md

@@ -4,13 +4,17 @@ Each flow names the pull requests it was used on, so their result tables show wh
 
 One file per component, named after it:
 
-- [`api.md`](api.md): noise handshake and OTA encryption on the ESP8266, outgoing connection wake timing on deep sleep and after a Wi-Fi drop
+- [`api.md`](api.md): noise handshake and OTA encryption on the ESP8266, outgoing connection wake timing on deep sleep and after a Wi-Fi drop, user defined action listing and execution with a raw plaintext client, store_yaml recovery over Noise or plaintext
+- [`ble_midi.md`](ble_midi.md): BLE MIDI client against a fake ESP32 instrument, every packet shape and the send actions
 - [`captive_portal.md`](captive_portal.md): fallback AP and /wifisave hammer
 - [`cse7766.md`](cse7766.md): Sonoff S31 parser check over the API
 - [`espnow.md`](espnow.md): ESP8266 broadcast receive
 - [`hdmi_cec.md`](hdmi_cec.md): two-board wire
-- [`ld2450.md`](ld2450.md): polygon zones, zone number round trip through the radar's readback
+- [`http_request.md`](http_request.md): update manifest URL changed at run time, every setter shape, a swap under a running check
+- [`ld2450.md`](ld2450.md): polygon zones, zone number round trip through the radar's readback, ESP8266 loopback harness without a radar
+- [`ld2412.md`](ld2412.md): output pin level through the basic configuration command, held back writes
 - [`libretiny.md`](libretiny.md): rtc preference emulation, BK72xx crash report on the next boot
+- [`modem.md`](modem.md): PPPoS modem component boot check with no modem attached, loop blocking and disable timing
 - [`mqtt.md`](mqtt.md): broker bench, QoS, reconnect, crash log over MQTT, WebSocket transports with a local and a public broker, TLS trust sources (own CA, client certificate, certificate bundle, no verification) with the CLI check
 - [`nrf52.md`](nrf52.md): dongle board support
 - [`online_image.md`](online_image.md): stalled and malformed downloads
@@ -20,7 +24,7 @@ One file per component, named after it:
 - [`scheduler.md`](scheduler.md): loop wake A/B
 - [`udp.md`](udp.md): datagrams, multicast, sockets, `udp.write` payload shapes
 - [`usb_cdc_acm.md`](usb_cdc_acm.md): nRF52840 dongle host driver
-- [`wifi.md`](wifi.md): reboot_timeout with a fallback AP, DHCP lease cache, Easy Connect (DPP)
+- [`wifi.md`](wifi.md): reboot_timeout with a fallback AP, DHCP lease cache, Easy Connect (DPP), WISP bridge with an ethernet upstream
 - [`zephyr.md`](zephyr.md): preferences on the nRF52840 dongle
 - [`zephyr_coredump.md`](zephyr_coredump.md): crash and decode on nRF52 boards
 - [`zwave_proxy.md`](zwave_proxy.md): frame checksums on a live proxy

.agents/skills/hardware-test/reference/recipes/api.md

@@ -28,3 +28,31 @@ connected first, and the loop-time maxima. For the loop cost of polling, repeat
 so after a drop every dial is closed and HA's incoming reconnect wins 11 to 33 s later; the measurable effect is the
 first dial landing in the loop the network flag flips.
 Results: https://github.com/esphome/esphome/pull/21085#issuecomment-6254742791
+
+## User defined action listing and execution without a client library (#18882)
+
+`scripts/api/rawactions.py HOST list` speaks the plaintext native API over a raw socket and decodes every
+`ListEntitiesServicesResponse` by field number (argument fields 1 name, 2 type, 3 description, 4 example, 5 optional,
+6 default_value), so new wire fields show up without waiting for the client library. `rawactions.py HOST exec ACTION
+k=v ...` sends `ExecuteServiceRequest` with `sint32` ints (field 5, not the legacy int32 field 2), fixed32 floats,
+length delimited strings and `int[]` as repeated sint32 (field 7); `ALLOW_MISSING=1` leaves arguments out on purpose
+(the device then drops the call). `templates/api-actions-dut.yaml` (D1 mini, three actions, optional variables with
+defaults) and `templates/api-actions-strings-dut.yaml` (required strings) log what arrived. String arguments are
+`StringRef`s that are not null terminated: copy them with `snprintf("%.*s", size, c_str())` into a buffer before
+logging, and do not pass `%.*s` to `logger.log`, whose validator counts it as one pattern.
+
+## store_yaml recovery over the native API (#16445)
+
+`scripts/api/syrecover.py HOST KEY OUTDIR [ORIGDIR]` (KEY `-` for plaintext) builds the client library's
+`APINoiseFrameHelper` around a stub `APIConnection` subclass (the compiled helper type checks the connection, and
+`ConnectionParams` needs every field), sends Hello, Authentication (never answered without a password) and
+`DeviceCapabilitiesRequest`, then `GetYamlRequest` (161), collects `GetYamlResponse` (162) frames by field number
+(1 data, 2 done, 3 total_size, 4 encoding) until done, requests again, decompresses with `compression.zstd` (Python 3.14, or the `zstandard` package) and
+unpacks the envelope with the tree's `unpack_envelope` (run with `PYTHONPATH` on that tree). Configs in
+`templates/store_yaml/`: entry files in `boards/`, a package one directory above them with `!secret` and an inline
+OTA password,
+so the redaction and the `..` paths are exercised. Repetitive YAML compresses into one chunk even at 22 KB; a 6 KB
+include of random base64 lines with `include_secrets: true` gives four chunks (1390 byte packets). Rough edge at
+0bd3738430: `include_secrets: true` fails the build when a package in another directory uses `!secret` and has no
+`secrets.yaml` beside it; a copy next to the package works around it.
+Results: https://github.com/esphome/esphome/pull/16445#issuecomment-6335435397

.agents/skills/hardware-test/reference/recipes/ble_midi.md

@@ -0,0 +1,19 @@
+# ble_midi
+
+## BLE MIDI client against a fake instrument (#18508)
+
+No MIDI hardware needed: `templates/ble_midi/midiperi.yaml` turns a second ESP32 (an S3 with ethernet, so the
+API stays reachable while BLE is busy) into a BLE MIDI peripheral with `esp32_ble_server`: the MIDI service
+advertised, the MIDI characteristic with read, write, write without response and notify, an `on_write` that logs
+the bytes, buttons that notify hand built packets (channel messages, two messages in one packet, running status,
+SysEx in one packet, split over two, oversize, cut short, clock, aftertouch, orphan data bytes, a 50 packet burst)
+and a restart button for the disconnect test. `midicli.yaml` is the component test config on a classic devkit with
+`wifi:`, `api:`, the peripheral's BLE address in the `peri_mac` substitution, given on the command line with
+`-s peri_mac <mac>` (the base MAC plus 2, printed by `esp32_ble` in `dump_config`), `on_sysex` and `on_message` lambdas that print the bytes, debug sensors and out of range send
+buttons. Drive both over the plaintext API with `scripts/modem/mdrive.py HOST LOGFILE press:NAME wait:S` 3 s
+apart and compare the peripheral's `TX` and `RX` lines with the client's decoded lines. Gotcha:
+`ble_server.characteristic.set_value` latches the value of its first play and re-applies it before every notify,
+so the peripheral script sets the value from a lambda (`id(midi_io).set_value(std::vector<uint8_t>(pkt));
+id(midi_io).notify();`). At VERBOSE the client logs four lines per message, so a burst shows an
+`esp32_ble took a long time` of a couple of seconds that is the serial port, not the parser.
+Results: https://github.com/esphome/esphome/pull/18508#issuecomment-6348272717

.agents/skills/hardware-test/reference/recipes/http_request.md

@@ -0,0 +1,18 @@
+# http_request
+
+## Update manifest URL changed at run time (#21373)
+
+`scripts/http_request/manifest_server.py PORT [DELAY]` serves `stable.json`, `beta.json` and `slow.json` (answered
+after DELAY s) with both chip families and logs every request. `templates/http_request_update/upd-common.yaml`
+(secret `manifest_base` is the server URL) has the update entity on the stable manifest, buttons for every
+`set_source_url` shape (`std::string` local, literal, temporary, `.c_str()` of a local, the current URL back in),
+`Check Then Swap` (ESP32 task path: check the slow manifest and replace the URL in the same lambda), `Arm Swap In
+Check` plus a `logger: on_message` lambda that replaces the URL from inside the inline check (ESP8266; the log line
+from inside `on_message` is swallowed, judge by the next check's result), and a `Heap` button. `upd-base-common.yaml`
+keeps only the shapes that compile on a tree with the bare pointer setter (for the base build, copy a board file
+and point its `common` include at `../upd-base-common.yaml` with a different `name:`); `boards/upd8266.yaml` and `boards/upd32.yaml` are the
+per-board files, one directory below the package their `../` include points at. Drive with `scripts/http_request/updrive.py HOST KEY LOGFILE press:NAME wait:S`, which prints every
+update state (latest version, summary). The ESP8266 Arduino client gets `Error reading manifest: -1` on roughly a
+quarter of the fetches from this Python server on every build, so count checks against the base before blaming a
+PR. `http_request` on the ESP8266 needs `verify_ssl: false` even for plain http URLs.
+Results: https://github.com/esphome/esphome/pull/21373#issuecomment-6337544933

.agents/skills/hardware-test/reference/recipes/ld2412.md

@@ -0,0 +1,13 @@
+# ld2412
+
+## Output pin level and the basic configuration command (#21353)
+
+`templates/ld2412-select-only-dut.yaml` (ESP32-S3, the module on GPIO43 and GPIO44 at 115200, only the output pin
+level select, the module's OUT pin on GPIO38 as a binary sensor plus the presence sensor) with `uart: debug:
+direction: BOTH`. Drive the select with `scripts/ld2450/lddrive.py HOST KEY LOGFILE sel:NAME=OPTION` and read the TX
+dump for command `02` carrying the level byte, then the OUT pin binary sensor against presence: with level high the
+pin follows presence, with level low it is inverted. A module that never answers the boot query (no `<<<` lines)
+only shows the held back path: `Command 02 held back until the module reports its settings`, a query `12`, and after
+2 s `Command 02 not sent, the module did not report its settings` with the select republished to the last known
+level. With the full set of numbers configured a select change also needs every number to have a state, so wait
+for the boot query answer before judging.

.agents/skills/hardware-test/reference/recipes/ld2450.md

@@ -13,3 +13,30 @@ selects over the API and prints every LD2450 state update. After each set the hu
 the radar and republishes all twelve coordinates from the answer, so set each coordinate of each zone to a distinct
 value and check the readbacks; no target is needed. Readbacks can arrive late over Wi-Fi, so match them by content.
 Results: https://github.com/esphome/esphome/pull/21146#issuecomment-6278026922
+
+## ESP8266 loopback harness, no radar needed (#21349)
+
+`templates/ld2450-loopback.yaml` (package; substitutions `name` and `baud`) runs the hub on UART0 (GPIO1 and GPIO3)
+with `logger: baud_rate: 0` and sets the UART0 loopback bit in `on_boot` (`USC0(0) |= (1 << UCLBE)`), so everything
+the hub or a `uart.write` action sends comes back on RX. Template buttons inject periodic frames (all four direction
+strings, targets 2 and 3), query zone acks (zone type 0, 1 and 2 for the select readback) and call the name based
+setters with a valid and a bogus name. `uart: debug: direction: TX` delimited on the command footer dumps every
+command the hub sends. Drive it with `scripts/ld2450/lddrive.py HOST KEY LOGFILE press:NAME sel:NAME=OPTION wait:S`
+(logs over the API at VERBOSE, 2 s between steps because the API log stream drops lines while `send_command_`
+blocks), then `txsum.py LOGFILE` lists the TX frames per step; diff the summaries of the two builds. The hub reads its
+own commands back and logs `Invalid status` for each, which is harmless. The boot readback of the baud rate select
+comes from the UART setting, so a second build at `baud: "9600"` checks the flash table lookup.
+Results: https://github.com/esphome/esphome/pull/21349#issuecomment-6332320026
+
+## Frame splitter collisions (#21357)
+
+The loopback template also carries the zone 1 numbers and seven collision buttons: a periodic frame with the
+command footer inside target 1, zone acks with `55 CC` and with `04 03 02 01` inside the coordinates, a periodic
+frame cut after 12 bytes followed by a zone ack, a frame missing its last byte followed by a complete one, a bogus
+255 byte length then a frame, and garbage then a frame. Judge by the state updates plus the `Handling Periodic` and
+`Handling Ack` lines. Through a real radar the set zone ack is sometimes corrupted by the radar itself (its tail
+replaced by the periodic frame it was sending, for example `04 03 03 03 00 ... 55 CC`), so count readbacks over at
+least 24 selects per build and read the raw bytes with `uart: debug: direction: RX` (`!extend` the package's uart
+id) before blaming the parser; the API log stream drops lines under that dump volume, so some misses stay
+unclassified.
+Results: https://github.com/esphome/esphome/pull/21357#issuecomment-6333244886

.agents/skills/hardware-test/reference/recipes/modem.md

@@ -0,0 +1,18 @@
+# modem
+
+## PPPoS modem component with no modem attached (#6721)
+
+A boot check on a classic ESP32 devkit with the modem UART pins left open. `templates/modem/modem-common.yaml` is
+the package (`api:`, debug `loop_time` and `free` sensors, uptime, buttons for `modem.enable`, `modem.disable` and
+`modem.send_at`, a 20 s alive log); `modemo.yaml` is the modem only build with `reboot_timeout: 2min` and the
+component test config's `on_boot` block at `priority: -100` (earlier, `modem.send_at` runs before the modem's
+`setup()` and logs `Modem DCE not ready`); `modemw.yaml` adds `wifi:` with `reboot_timeout: 0s` so the API stays
+reachable. Expect `Modem not responding at 115200 baud` once per pass with each pass blocking the loop about 1 s,
+the reboot at the configured timeout (`SW_CPU_RESET`), and a `modem.disable` with no modem answering to block
+the loop about 37 s (`Failed to leave data mode`, then the radio off timeout) without tripping the 30 s watchdog
+floor because the component feeds it in between. Drive the Wi-Fi build with
+`scripts/modem/mdrive.py HOST LOGFILE list press:NAME wait:S` (plaintext API; prints sensor and text sensor
+states, saves the device log). Before 8cc8df4a1f a modem only config with `api:` failed validation because a
+config dependent `AUTO_LOAD` added `network` after the dependency check; an explicit `network:` block was the
+workaround. Results: https://github.com/esphome/esphome/pull/6721#issuecomment-6347395159 and
+https://github.com/esphome/esphome/pull/6721#issuecomment-6348520416

.agents/skills/hardware-test/reference/recipes/wifi.md

@@ -23,3 +23,17 @@ Only an Android phone configures: Settings, network details, Add device, Share W
 QR scanner makes the phone an enrollee). Render the URI with the `qrcode` module and open the PNG.
 `esp32: framework: log_level: DEBUG` plus `sdkconfig_options: CONFIG_WPA_DEBUG_PRINT: y` prints the
 supplicant state machine.
+
+## WISP bridge with an ethernet upstream (#7147)
+
+`templates/wisp-ethernet-dut.yaml` (ESP32-S3 with a W5500, `wifi: ap:` with `ap_mode: WISP` and no station) and
+`templates/wisp-client.yaml` (D1 mini joining the bridge, `http_request` to a web server on the wired LAN and to
+`http://example.com/` every 15 s, `time: sntp`). Secrets: `wisp_psk` and `lan_http` (serve a text file on the host
+with `python -m http.server 8787 --bind 0.0.0.0` from a scratch directory). Judge by the client's `GET status 200`
+lines, the web server log showing the device's ethernet address as the source (NAT), the client's DHCP info (DNS1 is
+the LAN resolver) and `SNTP synced`. The device logs `Starting AP` and `DHCP DNS server: <resolver>` on its USB
+console; flashing over the air reboots it for repeat boots. Before the AP address and DHCP server moved ahead of the
+AP start (the fix in that PR), the first AP start failed on every boot with `esp_netif_dhcps_option failed: 20484`
+(DHCP server already started by the AP start event) and `Failed to enable NAT`, and the bridge only came up on the
+retry 90 s later; a client that cannot find the SSID for the first minute on an older build is that. With the fix
+the bridge is up 6 s after boot. Any change to the ESP-IDF AP start should also rerun the captive portal hammer.

.agents/skills/hardware-test/scripts/api/rawactions.py

@@ -0,0 +1,211 @@
+"""Plaintext native API client that lists user actions with their raw argument fields and executes one.
+
+usage: rawactions.py HOST list
+       rawactions.py HOST exec ACTION key=value [...]   (every argument must be given; types from the listing)
+Fields of ListEntitiesServicesArgument: 1 name, 2 type, 3 description, 4 example, 5 optional, 6 default_value.
+"""
+
+import os
+import socket
+import struct
+import sys
+
+HOST = sys.argv[1]
+CMD = sys.argv[2]
+ARGS = sys.argv[3:]
+TYPE_NAMES = {
+    0: "bool",
+    1: "int",
+    2: "float",
+    3: "string",
+    4: "bool[]",
+    5: "int[]",
+    6: "float[]",
+    7: "string[]",
+}
+
+
+def varint(v: int) -> bytes:
+    out = bytearray()
+    while True:
+        b = v & 0x7F
+        v >>= 7
+        if v:
+            out.append(b | 0x80)
+        else:
+            out.append(b)
+            return bytes(out)
+
+
+def svarint(v: int) -> bytes:
+    return varint((v << 1) ^ (v >> 63))
+
+
+def decode_varint(buf: bytes, pos: int) -> tuple[int, int]:
+    value = shift = 0
+    while True:
+        b = buf[pos]
+        pos += 1
+        value |= (b & 0x7F) << shift
+        if not b & 0x80:
+            return value, pos
+        shift += 7
+
+
+def fields(payload: bytes) -> list[tuple[int, int, object]]:
+    out = []
+    pos = 0
+    while pos < len(payload):
+        key, pos = decode_varint(payload, pos)
+        fnum, wt = key >> 3, key & 7
+        if wt == 0:
+            v, pos = decode_varint(payload, pos)
+        elif wt == 2:
+            ln, pos = decode_varint(payload, pos)
+            v = payload[pos : pos + ln]
+            pos += ln
+        elif wt == 5:
+            v = payload[pos : pos + 4]  # fixed32, caller unpacks
+            pos += 4
+        else:
+            raise ValueError(f"wire type {wt}")
+        out.append((fnum, wt, v))
+    return out
+
+
+def frame(mtype: int, payload: bytes) -> bytes:
+    return b"\x00" + varint(len(payload)) + varint(mtype) + payload
+
+
+def field_bytes(fnum: int, data: bytes) -> bytes:
+    return varint((fnum << 3) | 2) + varint(len(data)) + data
+
+
+def field_varint(fnum: int, v: int) -> bytes:
+    return varint((fnum << 3) | 0) + varint(v)
+
+
+def recv_frames(
+    sock: socket.socket, until: set[int], limit: float = 5.0
+) -> list[tuple[int, bytes]]:
+    sock.settimeout(limit)
+    buf = bytearray()
+    frames = []
+    while True:
+        try:
+            chunk = sock.recv(4096)
+        except TimeoutError:
+            return frames
+        if not chunk:
+            return frames
+        buf += chunk
+        while True:
+            if len(buf) < 3:
+                break
+            if buf[0] != 0:
+                raise ValueError("not plaintext")
+            try:
+                ln, p = decode_varint(buf, 1)
+                mt, p = decode_varint(buf, p)
+            except IndexError:
+                break
+            if len(buf) < p + ln:
+                break
+            frames.append((mt, bytes(buf[p : p + ln])))
+            del buf[: p + ln]
+            if mt in until:
+                return frames
+
+
+def main() -> None:
+    sock = socket.create_connection((HOST, 6053), timeout=5)
+    sock.sendall(
+        frame(
+            1, field_bytes(1, b"rawactions") + field_varint(2, 1) + field_varint(3, 10)
+        )
+    )  # HelloRequest
+    recv_frames(sock, {2})
+    sock.sendall(frame(3, b""))  # ConnectRequest, no password
+    recv_frames(sock, {4})
+    sock.sendall(frame(11, b""))  # ListEntitiesRequest
+    frames = recv_frames(sock, {19})
+    services = {}
+    for mt, payload in frames:
+        if mt != 41:
+            continue
+        name = key = None
+        args = []
+        for fnum, _, v in fields(payload):
+            if fnum == 1:
+                name = v.decode()
+            elif fnum == 2:
+                key = struct.unpack("<I", v)[0]
+            elif fnum == 3:
+                a = {
+                    "name": None,
+                    "type": 0,
+                    "description": None,
+                    "example": None,
+                    "optional": None,
+                    "default": None,
+                }
+                for af, _, av in fields(v):
+                    if af == 1:
+                        a["name"] = av.decode()
+                    elif af == 2:
+                        a["type"] = av
+                    elif af == 3:
+                        a["description"] = av.decode()
+                    elif af == 4:
+                        a["example"] = av.decode()
+                    elif af == 5:
+                        a["optional"] = bool(av)
+                    elif af == 6:
+                        a["default"] = av.decode()
+                    else:
+                        a[f"field{af}"] = av
+                args.append(a)
+        services[name] = (key, args)
+    if CMD == "list":
+        for name, (key, args) in services.items():
+            print(f"action {name} key={key}")
+            for a in args:
+                extra = {
+                    k: v
+                    for k, v in a.items()
+                    if k not in ("name", "type") and v is not None
+                }
+                print(f"  {a['name']}: {TYPE_NAMES.get(a['type'], a['type'])} {extra}")
+        return
+    name = ARGS[0]
+    key, args = services[name]
+    payload = varint((1 << 3) | 5) + struct.pack("<I", key)
+    given = dict(kv.split("=", 1) for kv in ARGS[1:])
+    for a in args:
+        if a["name"] not in given:
+            if os.environ.get("ALLOW_MISSING"):
+                continue  # leave the argument out of the request on purpose
+            sys.exit(f"missing {a['name']}")
+        raw = given[a["name"]]
+        t = a["type"]
+        if t == 0:
+            av = field_varint(1, 1 if raw.lower() == "true" else 0)
+        elif t == 1:
+            av = varint((5 << 3) | 0) + svarint(int(raw))  # sint32 int_
+        elif t == 2:
+            av = varint((3 << 3) | 5) + struct.pack("<f", float(raw))
+        elif t == 3:
+            av = field_bytes(4, raw.encode())
+        elif t == 5:
+            av = b"".join(
+                varint((7 << 3) | 0) + svarint(int(x)) for x in raw.split(",") if x
+            )  # repeated sint32 int_array
+        else:
+            sys.exit(f"type {t} not supported here")
+        payload += field_bytes(2, av)
+    sock.sendall(frame(42, payload))  # ExecuteServiceRequest
+    print(f"sent {name} with {given}")
+    sock.close()
+
+
+main()

.agents/skills/hardware-test/scripts/api/syrecover.py

@@ -0,0 +1,221 @@
+"""Pull the store_yaml blob off a device over the native API (plaintext or Noise) and unpack it.
+
+usage: syrecover.py HOST KEY OUTDIR [ORIGDIR]   (KEY of - means a plaintext API)
+Prints the capability flag, chunk count, advertised and received sizes, encoding, the envelope's files, and
+when ORIGDIR is given compares each recovered file with ORIGDIR/<path>.
+Run with PYTHONPATH pointing at the esphome tree that has store_yaml (for unpack_envelope). Needs Python 3.14
+(compression.zstd) or the zstandard package.
+"""
+
+import asyncio
+from pathlib import Path
+import sys
+import time
+
+from aioesphomeapi import api_pb2
+from aioesphomeapi._frame_helper.noise import APINoiseFrameHelper
+from aioesphomeapi._frame_helper.plain_text import APIPlaintextFrameHelper
+from aioesphomeapi.connection import APIConnection, ConnectionParams
+from aioesphomeapi.zeroconf import ZeroconfManager
+
+from esphome.components.store_yaml import unpack_envelope
+
+try:
+    from compression import zstd
+except ImportError:
+    try:
+        import zstandard as zstd
+    except ImportError:
+        sys.exit("needs Python 3.14 (compression.zstd) or the zstandard package")
+
+HOST, KEY, OUT = sys.argv[1], sys.argv[2], Path(sys.argv[3])
+ORIG = Path(sys.argv[4]) if len(sys.argv) > 4 else None
+HELLO, HELLO_RESP, CONNECT, CONNECT_RESP = 1, 2, 3, 4
+DISCONNECT_REQ = 5
+FATAL = -1  # queued by report_fatal_error so a waiting expect() stops at once
+CAPS_REQ, CAPS_RESP = 149, 150
+GET_YAML_REQ, GET_YAML_RESP = 161, 162
+
+
+def decode_varint(buf: bytes, pos: int) -> tuple[int, int]:
+    value = shift = 0
+    while True:
+        b = buf[pos]
+        pos += 1
+        value |= (b & 0x7F) << shift
+        if not b & 0x80:
+            return value, pos
+        shift += 7
+
+
+def fields(payload: bytes) -> dict[int, list]:
+    out: dict[int, list] = {}
+    pos = 0
+    while pos < len(payload):
+        key, pos = decode_varint(payload, pos)
+        fnum, wt = key >> 3, key & 7
+        if wt == 0:
+            v, pos = decode_varint(payload, pos)
+        elif wt == 2:
+            ln, pos = decode_varint(payload, pos)
+            v = payload[pos : pos + ln]
+            pos += ln
+        elif wt == 5:
+            v = payload[pos : pos + 4]
+            pos += 4
+        else:
+            raise ValueError(f"wire type {wt}")
+        out.setdefault(fnum, []).append(v)
+    return out
+
+
+async def main() -> None:
+    loop = asyncio.get_running_loop()
+    queue: asyncio.Queue[tuple[int, bytes]] = asyncio.Queue()
+    errors: list[Exception] = []
+
+    class Shim(APIConnection):
+        """Only the two callbacks the frame helper uses; the real connection logic is bypassed."""
+
+        def process_packet(self, msg_type_proto, data) -> None:
+            queue.put_nowait((msg_type_proto, bytes(data)))
+
+        def report_fatal_error(self, err: Exception) -> None:
+            errors.append(err)
+            queue.put_nowait((FATAL, b""))
+
+    params = ConnectionParams(
+        addresses=[HOST],
+        port=6053,
+        password=None,
+        client_info="syrecover",
+        keepalive=15,
+        zeroconf_manager=ZeroconfManager(),
+        noise_psk=None if KEY == "-" else KEY,
+        expected_name=None,
+        expected_mac=None,
+        timezone=None,
+        provide_time=True,
+    )
+    shim = Shim(params, None, False, HOST)
+    if KEY == "-":
+        helper = APIPlaintextFrameHelper(
+            connection=shim, client_info="syrecover", log_name=HOST
+        )
+    else:
+        helper = APINoiseFrameHelper(
+            connection=shim,
+            noise_psk=KEY,
+            expected_name=None,
+            expected_mac=None,
+            client_info="syrecover",
+            log_name=HOST,
+        )
+    await loop.create_connection(lambda: helper, HOST, 6053)
+    try:
+        await asyncio.wait_for(helper.ready_future, 10)
+    except Exception as exc:  # noqa: BLE001
+        sys.exit(f"handshake failed: {exc!r} {errors}")
+    print(f"transport {'plaintext' if KEY == '-' else 'noise'}: handshake done")
+
+    async def expect(msg_type: int, timeout: float = 10) -> bytes:
+        while True:
+            t, d = await asyncio.wait_for(queue.get(), timeout)
+            if t == msg_type:
+                return d
+            if t == FATAL:
+                sys.exit(
+                    f"transport error while waiting for message {msg_type}: {errors}"
+                )
+            if t == DISCONNECT_REQ:
+                sys.exit(
+                    f"device closed the connection while waiting for message {msg_type}"
+                )
+            print(f"skipping message type {t} while waiting for {msg_type}")
+
+    hello = api_pb2.HelloRequest(
+        client_info="syrecover", api_version_major=1, api_version_minor=10
+    )
+    helper.write_packets([(HELLO, hello.SerializeToString())], False)
+    await expect(HELLO_RESP)
+    # Sent like the client library does; a device without a password never answers it
+    helper.write_packets(
+        [(CONNECT, api_pb2.AuthenticationRequest().SerializeToString())], False
+    )
+    helper.write_packets(
+        [(CAPS_REQ, api_pb2.DeviceCapabilitiesRequest().SerializeToString())], False
+    )
+    caps = fields(await expect(CAPS_RESP))
+    supported = None
+    if 7 in caps:
+        supported = fields(caps[7][0]).get(1) == [1]
+    print(f"capabilities: store_yaml field present={7 in caps} supported={supported}")
+
+    t0 = time.monotonic()
+    helper.write_packets([(GET_YAML_REQ, b"")], False)
+    chunks: list[bytes] = []
+    total = encoding = None
+    done = False
+    while not done:
+        f = fields(await expect(GET_YAML_RESP, 20))
+        if 1 in f:
+            chunks.append(f[1][0])
+        done = f.get(2) == [1]
+        if 3 in f:
+            total = f[3][0]
+        if 4 in f:
+            encoding = f[4][0].decode()
+    dt = time.monotonic() - t0
+    compressed = b"".join(chunks)
+    print(f"chunks {len(chunks)} sizes {[len(c) for c in chunks]}")
+    print(
+        f"received {len(compressed)} bytes, advertised {total}, encoding {encoding!r}, {dt:.2f} s"
+    )
+    # a second request right after: the device must answer again, not stay stuck
+    helper.write_packets([(GET_YAML_REQ, b"")], False)
+    again = 0
+    done = False
+    while not done:
+        f = fields(await expect(GET_YAML_RESP, 20))
+        again += len(f.get(1, [b""])[0])
+        done = f.get(2) == [1]
+    print(f"second request: {again} bytes")
+    helper.close()
+    if errors:
+        sys.exit(f"transport errors: {errors}")
+    if encoding != "zstd":
+        sys.exit(f"unexpected encoding {encoding!r}, expected 'zstd'")
+    if total is not None and len(compressed) != total:
+        sys.exit(f"received {len(compressed)} bytes but the device advertised {total}")
+    if again != len(compressed):
+        sys.exit(
+            f"the second request returned {again} bytes, the first {len(compressed)}"
+        )
+    envelope = zstd.decompress(compressed)
+    files = unpack_envelope(envelope)
+    print(
+        f"envelope {len(envelope)} bytes, {len(files)} files, ratio {len(compressed) / len(envelope):.2f}"
+    )
+    OUT.mkdir(parents=True, exist_ok=True)
+    for rel, content in files.items():
+        target = OUT / rel.replace("../", "up_/")
+        if not target.resolve().is_relative_to(OUT.resolve()):
+            print("skipping a path outside the output directory:", rel)
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(content)
+        note = ""
+        if ORIG is not None:
+            orig = (ORIG / rel).resolve()
+            if orig.exists():
+                note = (
+                    "IDENTICAL to original"
+                    if orig.read_bytes() == content
+                    else f"DIFFERS from original ({orig.stat().st_size} bytes)"
+                )
+            else:
+                note = "no original"
+        print(f"  {rel}: {len(content)} bytes {note}")
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/http_request/manifest_server.py

@@ -0,0 +1,58 @@
+"""Serve update manifests: stable.json, beta.json and slow.json (answered after a delay); logs every request."""
+
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import sys
+import time
+
+PORT = int(sys.argv[1])
+DELAY = float(sys.argv[2]) if len(sys.argv) > 2 else 4.0
+
+
+def manifest(name: str, version: str) -> bytes:
+    builds = [
+        {
+            "chipFamily": fam,
+            "ota": {
+                "path": f"/{name}.bin",
+                "md5": "d41d8cd98f00b204e9800998ecf8427e",
+                "summary": f"{name} channel",
+            },
+        }
+        for fam in ("ESP8266", "ESP32")
+    ]
+    return json.dumps(
+        {"name": f"Bench {name}", "version": version, "builds": builds}
+    ).encode()
+
+
+DOCS = {
+    "/stable.json": manifest("stable", "1.0.0"),
+    "/beta.json": manifest("beta", "2.0.0-beta1"),
+    "/slow.json": manifest("slow", "3.0.0-slow"),
+}
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:  # noqa: N802
+        body = DOCS.get(self.path)
+        print(
+            f"{time.strftime('%H:%M:%S')} {self.client_address[0]} GET {self.path} -> {404 if body is None else 200}",
+            flush=True,
+        )
+        if body is None:
+            self.send_error(404)
+            return
+        if self.path == "/slow.json":
+            time.sleep(DELAY)
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *args) -> None:  # quiet default log
+        return
+
+
+ThreadingHTTPServer(("0.0.0.0", PORT), Handler).serve_forever()

.agents/skills/hardware-test/scripts/http_request/updrive.py

@@ -0,0 +1,129 @@
+"""Drive the http_request update harness over the API: press buttons, print every update state and save the log.
+usage: updrive.py HOST KEY(- for plaintext) LOGFILE OP [OP ...]
+  OP: list | press:NAME | set:NAME=VALUE | sel:NAME=OPTION | wait:SECONDS
+"""
+
+import asyncio
+import pathlib
+import sys
+import time
+
+from aioesphomeapi import (
+    APIClient,
+    BinarySensorState,
+    ButtonInfo,
+    LogLevel,
+    NumberInfo,
+    NumberState,
+    SelectInfo,
+    SelectState,
+    SensorInfo,
+    SensorState,
+    TextSensorInfo,
+    TextSensorState,
+    UpdateState,
+)
+
+HOST, KEY, LOGFILE = sys.argv[1], sys.argv[2], sys.argv[3]
+OPS = sys.argv[4:]
+T0 = time.time()
+
+
+def stamp() -> str:
+    return f"{time.time() - T0:7.3f}"
+
+
+async def main() -> None:
+    with pathlib.Path(LOGFILE).open("w", encoding="utf-8") as log:
+        c = APIClient(HOST, 6053, None, noise_psk=None if KEY == "-" else KEY)
+        await c.connect(login=True)
+        info = await c.device_info()
+        print(
+            f"device {info.name} esphome {info.esphome_version} compiled {info.compilation_time}"
+        )
+        ents, _ = await c.list_entities_services()
+        by_key = {e.key: e for e in ents}
+        buttons = {e.name: e for e in ents if isinstance(e, ButtonInfo)}
+        selects = {e.name: e for e in ents if isinstance(e, SelectInfo)}
+
+        def on_state(s) -> None:
+            e = by_key.get(s.key)
+            if e is None:
+                return
+            if isinstance(s, TextSensorState):
+                print(
+                    f"{stamp()} TXT {e.name} = {s.state!r}{' (missing)' if s.missing_state else ''}",
+                    flush=True,
+                )
+            elif isinstance(s, UpdateState):
+                print(
+                    f"{stamp()} UPD {e.name} latest={s.latest_version!r} title={s.title!r} summary={s.release_summary!r} in_progress={s.in_progress}{' (missing)' if s.missing_state else ''}",
+                    flush=True,
+                )
+            elif isinstance(s, BinarySensorState):
+                print(
+                    f"{stamp()} BIN {e.name} = {s.state}{' (missing)' if s.missing_state else ''}",
+                    flush=True,
+                )
+            elif isinstance(s, NumberState):
+                print(
+                    f"{stamp()} NUM {e.name} = {s.state:.0f}{' (missing)' if s.missing_state else ''}",
+                    flush=True,
+                )
+            elif isinstance(s, SelectState):
+                print(
+                    f"{stamp()} SEL {e.name} = {s.state!r}{' (missing)' if s.missing_state else ''}",
+                    flush=True,
+                )
+            elif isinstance(s, SensorState) and isinstance(e, SensorInfo):
+                print(f"{stamp()} SEN {e.name} = {s.state:.0f}", flush=True)
+
+        def on_log(msg) -> None:
+            log.write(f"{stamp()} {msg.message.decode(errors='replace')}\n")
+
+        c.subscribe_states(on_state)
+        c.subscribe_logs(on_log, log_level=LogLevel.LOG_LEVEL_VERBOSE)
+        await asyncio.sleep(1.5)
+        for op in OPS:
+            if op == "list":
+                for n in sorted(buttons):
+                    print("button:", n)
+                for n in sorted(selects):
+                    print("select:", n, selects[n].options)
+                for e in ents:
+                    if isinstance(e, TextSensorInfo):
+                        print("text_sensor:", e.name)
+                continue
+            kind, _, rest = op.partition(":")
+            if kind == "wait":
+                await asyncio.sleep(float(rest))
+                continue
+            if kind == "press":
+                if rest not in buttons:
+                    sys.exit(f"no button named {rest!r}; have {sorted(buttons)}")
+                print(f"{stamp()} >>> press {rest}", flush=True)
+                log.write(f"{stamp()} >>> press {rest}\n")
+                c.button_command(buttons[rest].key)
+            elif kind == "set":
+                name, _, value = rest.partition("=")
+                numbers = {e.name: e for e in ents if isinstance(e, NumberInfo)}
+                if name not in numbers:
+                    sys.exit(f"no number named {name!r}")
+                print(f"{stamp()} >>> set {name} = {value}", flush=True)
+                log.write(f"{stamp()} >>> set {name} = {value}\n")
+                c.number_command(numbers[name].key, float(value))
+            elif kind == "sel":
+                name, _, value = rest.partition("=")
+                if name not in selects:
+                    sys.exit(f"no select named {name!r}; have {sorted(selects)}")
+                print(f"{stamp()} >>> select {name} = {value}", flush=True)
+                log.write(f"{stamp()} >>> select {name} = {value}\n")
+                c.select_command(selects[name].key, value)
+            else:
+                sys.exit(f"unknown op {op!r}")
+            await asyncio.sleep(2.0)
+        await asyncio.sleep(1)
+        await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/ld2450/lddrive.py

@@ -0,0 +1,123 @@
+"""Drive an LD24xx harness over the API: press buttons, set selects and numbers, print state updates, save the log.
+
+usage: lddrive.py HOST KEY LOGFILE OP [OP ...]   (KEY of - means a plaintext API)
+  OP: list | press:NAME | sel:NAME=OPTION | set:NAME=VALUE | wait:SECONDS
+Steps are 2 s apart: the API log stream drops lines while the hub blocks in send_command_.
+"""
+
+import asyncio
+from pathlib import Path
+import sys
+import time
+
+from aioesphomeapi import (
+    APIClient,
+    BinarySensorState,
+    ButtonInfo,
+    LogLevel,
+    NumberInfo,
+    NumberState,
+    SelectInfo,
+    SelectState,
+    SensorInfo,
+    SensorState,
+    TextSensorInfo,
+    TextSensorState,
+)
+
+HOST, KEY, LOGFILE = sys.argv[1], sys.argv[2], sys.argv[3]
+OPS = sys.argv[4:]
+T0 = time.time()
+STEP_GAP_S = 2.0
+
+
+def stamp() -> str:
+    return f"{time.time() - T0:7.3f}"
+
+
+async def run(c: APIClient, log) -> None:
+    info = await c.device_info()
+    print(
+        f"device {info.name} esphome {info.esphome_version} compiled {info.compilation_time}"
+    )
+    ents, _ = await c.list_entities_services()
+    by_key = {e.key: e for e in ents}
+    buttons = {e.name: e for e in ents if isinstance(e, ButtonInfo)}
+    selects = {e.name: e for e in ents if isinstance(e, SelectInfo)}
+    numbers = {e.name: e for e in ents if isinstance(e, NumberInfo)}
+
+    def on_state(s) -> None:
+        e = by_key.get(s.key)
+        if e is None:
+            return
+        missing = " (missing)" if getattr(s, "missing_state", False) else ""
+        if isinstance(s, TextSensorState):
+            print(f"{stamp()} TXT {e.name} = {s.state!r}{missing}", flush=True)
+        elif isinstance(s, BinarySensorState):
+            print(f"{stamp()} BIN {e.name} = {s.state}{missing}", flush=True)
+        elif isinstance(s, NumberState):
+            print(f"{stamp()} NUM {e.name} = {s.state:.0f}{missing}", flush=True)
+        elif isinstance(s, SelectState):
+            print(f"{stamp()} SEL {e.name} = {s.state!r}{missing}", flush=True)
+        elif (
+            isinstance(s, SensorState)
+            and isinstance(e, SensorInfo)
+            and "Count" in e.name
+        ):
+            print(f"{stamp()} CNT {e.name} = {s.state:.0f}", flush=True)
+
+    def on_log(msg) -> None:
+        log.write(f"{stamp()} {msg.message.decode(errors='replace')}\n")
+
+    c.subscribe_states(on_state)
+    c.subscribe_logs(on_log, log_level=LogLevel.LOG_LEVEL_VERBOSE)
+    await asyncio.sleep(1.5)
+    for op in OPS:
+        if op == "list":
+            for n in sorted(buttons):
+                print("button:", n)
+            for n in sorted(selects):
+                print("select:", n, selects[n].options)
+            for e in ents:
+                if isinstance(e, TextSensorInfo):
+                    print("text_sensor:", e.name)
+            continue
+        kind, _, rest = op.partition(":")
+        if kind == "wait":
+            await asyncio.sleep(float(rest))
+            continue
+        if kind == "press":
+            if rest not in buttons:
+                sys.exit(f"no button named {rest!r}; have {sorted(buttons)}")
+            print(f"{stamp()} >>> press {rest}", flush=True)
+            log.write(f"{stamp()} >>> press {rest}\n")
+            c.button_command(buttons[rest].key)
+        elif kind == "set":
+            name, _, value = rest.partition("=")
+            if name not in numbers:
+                sys.exit(f"no number named {name!r}; have {sorted(numbers)}")
+            print(f"{stamp()} >>> set {name} = {value}", flush=True)
+            log.write(f"{stamp()} >>> set {name} = {value}\n")
+            c.number_command(numbers[name].key, float(value))
+        elif kind == "sel":
+            name, _, value = rest.partition("=")
+            if name not in selects:
+                sys.exit(f"no select named {name!r}; have {sorted(selects)}")
+            print(f"{stamp()} >>> select {name} = {value}", flush=True)
+            log.write(f"{stamp()} >>> select {name} = {value}\n")
+            c.select_command(selects[name].key, value)
+        else:
+            sys.exit(f"unknown op {op!r}")
+        await asyncio.sleep(STEP_GAP_S)
+    await asyncio.sleep(1)
+
+
+async def main() -> None:
+    c = APIClient(HOST, 6053, None, noise_psk=None if KEY == "-" else KEY)
+    await c.connect(login=True)
+    with Path(LOGFILE).open("w", encoding="utf-8") as log:
+        await run(c, log)
+    await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/ld2450/txsum.py

@@ -0,0 +1,33 @@
+"""Summarize an lddrive.py log: for each step, the LD2450 TX frames, commands and publishes.
+
+usage: txsum.py LOGFILE   (diff the output of two builds)
+"""
+
+from pathlib import Path
+import re
+import sys
+
+ANSI = re.compile(r"\x1b\[[0-9;]*m")
+out: list[str] = []
+with Path(sys.argv[1]).open(encoding="utf-8", errors="replace") as log:
+    for raw in log:
+        line = ANSI.sub("", raw.rstrip("\n"))
+        m = re.match(r"\s*[\d.]+ (.*)", line)
+        if not m:
+            continue
+        text = m.group(1)
+        if text.startswith(">>>"):
+            out.append(f"\n# {text[4:]}")
+        elif "[uart_debug" in text:
+            out.append(f"  TX {text.split('>>> ')[1]}")
+        elif "[ld2450" in text and (
+            "Sending COMMAND" in text
+            or "zone type" in text.lower()
+            or "Query zone" in text
+        ):
+            out.append(f"  LOG {text.split(']: ', 1)[1]}")
+        elif "[select:" in text and ">>" in text:
+            out.append(f"  SEL {text.split(']: ', 1)[1]}")
+        elif "[text_sensor:098]" in text:
+            out.append(f"  TXT {text.split(']: ', 1)[1]}")
+print("\n".join(out))

.agents/skills/hardware-test/scripts/modem/mdrive.py

@@ -0,0 +1,86 @@
+"""Drive the modem test build over the API: press buttons, print sensor states, save the device log.
+usage: mdrive.py HOST LOGFILE OP [OP ...]
+  OP: list | press:NAME | wait:SECONDS
+"""
+
+import asyncio
+import pathlib
+import sys
+import time
+
+from aioesphomeapi import (
+    APIClient,
+    ButtonInfo,
+    LogLevel,
+    SensorInfo,
+    SensorState,
+    TextSensorInfo,
+    TextSensorState,
+)
+
+HOST, LOGFILE = sys.argv[1], sys.argv[2]
+OPS = sys.argv[3:]
+T0 = time.time()
+
+
+def stamp() -> str:
+    return f"{time.time() - T0:7.3f}"
+
+
+async def main() -> None:
+    with pathlib.Path(LOGFILE).open("w", encoding="utf-8") as log:
+        c = APIClient(HOST, 6053, None)
+        await c.connect(login=True)
+        info = await c.device_info()
+        print(
+            f"device {info.name} esphome {info.esphome_version} compiled {info.compilation_time}"
+        )
+        ents, _ = await c.list_entities_services()
+        by_key = {e.key: e for e in ents}
+        buttons = {e.name: e for e in ents if isinstance(e, ButtonInfo)}
+
+        def on_state(s) -> None:
+            e = by_key.get(s.key)
+            if e is None:
+                return
+            if isinstance(s, TextSensorState):
+                print(
+                    f"{stamp()} TXT {e.name} = {s.state!r}{' (missing)' if s.missing_state else ''}",
+                    flush=True,
+                )
+            elif isinstance(s, SensorState) and isinstance(e, SensorInfo):
+                print(f"{stamp()} SEN {e.name} = {s.state:.1f}", flush=True)
+
+        def on_log(msg) -> None:
+            log.write(f"{stamp()} {msg.message.decode(errors='replace')}\n")
+            log.flush()
+
+        c.subscribe_states(on_state)
+        c.subscribe_logs(on_log, log_level=LogLevel.LOG_LEVEL_DEBUG)
+        await asyncio.sleep(1.5)
+        for op in OPS:
+            if op == "list":
+                for n in sorted(buttons):
+                    print("button:", n)
+                for e in ents:
+                    if isinstance(e, (TextSensorInfo, SensorInfo)):
+                        print("entity:", type(e).__name__, e.name)
+                continue
+            kind, _, rest = op.partition(":")
+            if kind == "wait":
+                await asyncio.sleep(float(rest))
+                continue
+            if kind == "press":
+                if rest not in buttons:
+                    sys.exit(f"no button named {rest!r}; have {sorted(buttons)}")
+                print(f"{stamp()} >>> press {rest}", flush=True)
+                log.write(f"{stamp()} >>> press {rest}\n")
+                c.button_command(buttons[rest].key)
+            else:
+                sys.exit(f"unknown op {op!r}")
+            await asyncio.sleep(2.0)
+        await asyncio.sleep(1)
+        await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/templates/api-actions-dut.yaml

@@ -0,0 +1,65 @@
+esphome:
+  name: ${name}
+
+esp8266:
+  board: d1_mini
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+logger:
+  level: DEBUG
+
+api:
+  reboot_timeout: 0s
+  actions:
+    - action: play_buzzer
+      description: Play a song or build one from parts
+      variables:
+        song_str:
+          type: string
+          description: Full RTTTL string
+          example: "scale:d=4,o=5,b=100:c,d,e"
+          required: false
+        notes:
+          type: string
+          required: false
+        octave:
+          type: int
+          default: 5
+        bpm:
+          type: int
+          default: 100
+        tempo:
+          type: float
+          default: 1.5
+        loud:
+          type: bool
+          default: true
+        label:
+          type: string
+          default: ""
+      then:
+        - lambda: |-
+            char s[40], n[40], l[40];
+            snprintf(s, sizeof(s), "%.*s", (int) song_str.size(), song_str.c_str());
+            snprintf(n, sizeof(n), "%.*s", (int) notes.size(), notes.c_str());
+            snprintf(l, sizeof(l), "%.*s", (int) label.size(), label.c_str());
+            ESP_LOGD("main", "play_buzzer song=%s(%d) notes=%s(%d) octave=%d bpm=%d tempo=%.1f loud=%d label=%s(%d)", s,
+                     (int) song_str.size(), n, (int) notes.size(), octave, bpm, tempo, loud, l, (int) label.size());
+    - action: plain_action
+      variables:
+        value: int
+      then:
+        - logger.log:
+            format: "plain_action value=%d"
+            args: ["value"]
+    - action: list_action
+      variables:
+        values: int[]
+      then:
+        - logger.log:
+            format: "list_action n=%d"
+            args: ["values.size()"]

.agents/skills/hardware-test/templates/api-actions-strings-dut.yaml

@@ -0,0 +1,28 @@
+esphome:
+  name: ${name}
+
+esp8266:
+  board: d1_mini
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+logger:
+  level: DEBUG
+
+api:
+  reboot_timeout: 0s
+  actions:
+    - action: str_action
+      variables:
+        song_str: string
+        notes: string
+        octave: int
+      then:
+        - lambda: |-
+            char s[40], n[40];
+            snprintf(s, sizeof(s), "%.*s", (int) song_str.size(), song_str.c_str());
+            snprintf(n, sizeof(n), "%.*s", (int) notes.size(), notes.c_str());
+            ESP_LOGD("main", "str_action song=%s(%d) notes=%s(%d) octave=%d", s, (int) song_str.size(), n, (int) notes.size(), octave);

.agents/skills/hardware-test/templates/ble_midi/midicli.yaml

@@ -0,0 +1,150 @@
+substitutions:
+  # the fake instrument's BLE address; pass it with `-s peri_mac AA:BB:CC:DD:EE:FF`
+  peri_mac: "00:00:00:00:00:00"
+
+esphome:
+  name: midicli
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+logger:
+  level: VERBOSE
+  logs:
+    esp32_ble_tracker: DEBUG
+    ble_client: DEBUG
+    esp32_ble: DEBUG
+    api: DEBUG
+    scheduler: DEBUG
+    sensor: DEBUG
+    wifi: DEBUG
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+api:
+  reboot_timeout: 0s
+
+esp32_ble_tracker:
+
+ble_client:
+  - mac_address: ${peri_mac}
+    id: midi_client
+
+ble_midi:
+  id: test_midi
+  ble_client_id: midi_client
+  max_sysex_size: 64
+  pair: false
+  on_connect:
+    - logger.log: "MIDI device connected"
+    - ble_midi.send_program_change:
+        id: test_midi
+        program: 0
+  on_disconnect:
+    - logger.log: "MIDI device disconnected"
+  on_note_on:
+    - logger.log:
+        format: "Note on %u velocity %u channel %u"
+        args: [note, velocity, channel]
+  on_note_off:
+    - logger.log:
+        format: "Note off %u channel %u"
+        args: [note, channel]
+  on_control_change:
+    - logger.log:
+        format: "CC %u = %u on channel %u"
+        args: [control_number, value, channel]
+  on_program_change:
+    - logger.log:
+        format: "Program %u on channel %u"
+        args: [program, channel]
+  on_pitch_bend:
+    - logger.log:
+        format: "Pitch bend %d on channel %u"
+        args: [value, channel]
+  on_sysex:
+    - lambda: |-
+        ESP_LOGI("midi", "SysEx of %u bytes: %s", (unsigned) data.size(), format_hex_pretty(data.data(), data.size()).c_str());
+  on_message:
+    - lambda: |-
+        ESP_LOGI("midi", "Raw message of %u bytes: %s", (unsigned) data.size(), format_hex_pretty(data.data(), data.size()).c_str());
+
+sensor:
+  - platform: debug
+    free:
+      name: Heap Free
+    loop_time:
+      name: Loop Time
+
+debug:
+  update_interval: 30s
+
+button:
+  - platform: template
+    name: "MIDI send tests"
+    on_press:
+      - ble_midi.send_note_on:
+          id: test_midi
+          note: 60
+      - ble_midi.send_note_on:
+          id: test_midi
+          note: !lambda "return 60;"
+          velocity: !lambda "return 100;"
+          channel: !lambda "return 1;"
+      - ble_midi.send_note_off:
+          id: test_midi
+          note: 60
+          velocity: 0
+          channel: 1
+      - ble_midi.send_control_change:
+          id: test_midi
+          control_number: 7
+          value: 64
+      - ble_midi.send_pitch_bend:
+          id: test_midi
+          value: -8192
+      - ble_midi.send_sysex:
+          id: test_midi
+          payload: [0x7E, 0x7F, 0x06, 0x01]
+      - ble_midi.send_raw:
+          id: test_midi
+          data: !lambda "return std::vector<uint8_t>{0x90, 0x3C, 0x40};"
+      - if:
+          condition:
+            ble_midi.connected:
+              id: test_midi
+          then:
+            - logger.log: "Still connected"
+          else:
+            - logger.log: "Not connected"
+  - platform: template
+    name: "MIDI send out of range"
+    on_press:
+      - ble_midi.send_note_on:
+          id: test_midi
+          note: !lambda "return 200;"
+      - ble_midi.send_control_change:
+          id: test_midi
+          control_number: 1
+          value: 1
+          channel: !lambda "return 16;"
+      - ble_midi.send_pitch_bend:
+          id: test_midi
+          value: 8191
+      - ble_midi.send_sysex:
+          id: test_midi
+          payload: [0xF0, 0x7E, 0x7F, 0x09, 0x01, 0xF7]
+      - ble_midi.send_raw:
+          id: test_midi
+          data: !lambda "return std::vector<uint8_t>(140, 0x00);"
+  - platform: template
+    name: "MIDI send long sysex"
+    on_press:
+      - ble_midi.send_sysex:
+          id: test_midi
+          payload: !lambda "return std::vector<uint8_t>(100, 0x11);"

.agents/skills/hardware-test/templates/ble_midi/midiperi.yaml

@@ -0,0 +1,177 @@
+esphome:
+  name: midiperi
+
+esp32:
+  board: esp32-s3-devkitc-1
+  variant: esp32s3
+  flash_size: 16MB
+  framework:
+    type: esp-idf
+
+logger:
+  hardware_uart: USB_SERIAL_JTAG
+  level: DEBUG
+
+api:
+  reboot_timeout: 0s
+
+ota:
+  - platform: esphome
+
+ethernet:
+  type: W5500
+  clk_pin: GPIO13
+  mosi_pin: GPIO11
+  miso_pin: GPIO12
+  cs_pin: GPIO14
+  interrupt_pin: GPIO10
+  reset_pin: GPIO9
+
+esp32_ble_server:
+  id: ble_server
+  manufacturer: FakeMIDI
+  on_connect:
+    - lambda: ESP_LOGI("peri", "central connected %d", id);
+  on_disconnect:
+    - lambda: ESP_LOGI("peri", "central disconnected %d", id);
+  services:
+    - uuid: 03B80E5A-EDE8-4B33-A751-6CE34EC4C700
+      advertise: true
+      characteristics:
+        - id: midi_io
+          uuid: 7772E5DB-3868-4112-A1A9-F2669D106BF3
+          read: true
+          write: true
+          write_no_response: true
+          notify: true
+          on_write:
+            - lambda: |-
+                ESP_LOGI("peri", "RX %u bytes: %s", (unsigned) x.size(), format_hex_pretty(x.data(), x.size()).c_str());
+
+script:
+  - id: emit
+    parameters:
+      pkt: std::vector<uint8_t>
+    then:
+      - lambda: |-
+          ESP_LOGI("peri", "TX %u bytes: %s", (unsigned) pkt.size(), format_hex_pretty(pkt.data(), pkt.size()).c_str());
+          id(midi_io).set_value(std::vector<uint8_t>(pkt));
+          id(midi_io).notify();
+
+button:
+  - platform: restart
+    name: P Restart
+  - platform: template
+    name: P Note On
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0x90, 0x3C, 0x64};'
+  - platform: template
+    name: P Note Off
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0x80, 0x3C, 0x00};'
+  - platform: template
+    name: P Control Change
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xB0, 0x07, 0x40};'
+  - platform: template
+    name: P Program Change
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xC5, 0x05};'
+  - platform: template
+    name: P Pitch Bend
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xE0, 0x7F, 0x7F};'
+  - platform: template
+    name: P Two Notes One Packet
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0x90, 0x3C, 0x64, 0x81, 0x91, 0x3E, 0x50};'
+  - platform: template
+    name: P Running Status
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0x90, 0x40, 0x64, 0x41, 0x64};'
+  - platform: template
+    name: P Sysex One Packet
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xF0, 0x7E, 0x7F, 0x06, 0x01, 0x80, 0xF7};'
+  - platform: template
+    name: P Sysex Split
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xF0, 0x41, 0x10, 0x42};'
+      - delay: 200ms
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x12, 0x00, 0x40, 0x80, 0xF7};'
+  - platform: template
+    name: P Sysex Oversize
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'std::vector<uint8_t> v{0x80, 0x80, 0xF0}; for (int i = 0; i < 17; i++) v.push_back(i); return v;'
+      - delay: 200ms
+      - script.execute:
+          id: emit
+          pkt: !lambda 'std::vector<uint8_t> v{0x80}; for (int i = 0; i < 19; i++) v.push_back(0x20 + i); return v;'
+      - delay: 200ms
+      - script.execute:
+          id: emit
+          pkt: !lambda 'std::vector<uint8_t> v{0x80}; for (int i = 0; i < 19; i++) v.push_back(0x40 + i); return v;'
+      - delay: 200ms
+      - script.execute:
+          id: emit
+          pkt: !lambda 'std::vector<uint8_t> v{0x80}; for (int i = 0; i < 19; i++) v.push_back(0x60 + i); return v;'
+      - delay: 200ms
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xF7};'
+  - platform: template
+    name: P Sysex Cut Short
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xF0, 0x41, 0x10, 0x80, 0x90, 0x3C, 0x64};'
+  - platform: template
+    name: P Clock
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xF8};'
+  - platform: template
+    name: P Aftertouch
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0xD3, 0x45};'
+  - platform: template
+    name: P Orphan Data Byte
+    on_press:
+      - script.execute:
+          id: emit
+          pkt: !lambda 'return {0x80, 0x80, 0x3C, 0x64};'
+  - platform: template
+    name: P Burst
+    on_press:
+      - repeat:
+          count: 50
+          then:
+            - script.execute:
+                id: emit
+                pkt: !lambda 'return {0x80, 0x80, 0x90, 0x30, 0x40, 0x80, 0x80, 0x30, 0x00};'
+            - delay: 20ms

.agents/skills/hardware-test/templates/http_request_update/boards/upd32.yaml

@@ -0,0 +1,10 @@
+esphome:
+  name: upd32
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+packages:
+  common: !include ../upd-common.yaml

.agents/skills/hardware-test/templates/http_request_update/boards/upd8266.yaml

@@ -0,0 +1,8 @@
+esphome:
+  name: upd8266
+
+esp8266:
+  board: d1_mini
+
+packages:
+  common: !include ../upd-common.yaml

.agents/skills/hardware-test/templates/http_request_update/upd-base-common.yaml

@@ -0,0 +1,52 @@
+substitutions:
+  base: !secret manifest_base
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+logger:
+  level: DEBUG
+api:
+  reboot_timeout: 0s
+
+http_request:
+  verify_ssl: false
+  timeout: 10s
+
+ota:
+  - platform: http_request
+    id: ota_http
+
+update:
+  - platform: http_request
+    id: upd
+    name: Firmware
+    source: ${base}/stable.json
+    update_interval: 1h
+
+button:
+  - platform: template
+    name: Check
+    on_press:
+      - lambda: id(upd).check();
+  - platform: template
+    name: URL Slow Cstr
+    on_press:
+      - lambda: |-
+          std::string url = "${base}/slow.json";
+          id(upd).set_source_url(url.c_str());
+  - platform: template
+    name: URL Stable Literal
+    on_press:
+      - lambda: id(upd).set_source_url("${base}/stable.json");
+  - platform: template
+    name: Heap
+    on_press:
+      - lambda: |-
+          #ifdef USE_ESP8266
+          ESP_LOGI("harness", "heap free %u", ESP.getFreeHeap());
+          #else
+          ESP_LOGI("harness", "heap free %u", (unsigned) heap_caps_get_free_size(MALLOC_CAP_INTERNAL));
+          #endif

.agents/skills/hardware-test/templates/http_request_update/upd-common.yaml

@@ -0,0 +1,95 @@
+substitutions:
+  base: !secret manifest_base
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+logger:
+  level: DEBUG
+  on_message:
+    - level: DEBUG
+      then:
+        - lambda: |-
+            // Inline check path: replace the URL from inside the check (ESP8266 runs the check on the main loop)
+            if (id(swap_in_check) && strstr(message, "Content-Length") != nullptr) {
+              id(swap_in_check) = false;
+              std::string url = "${base}/beta.json";
+              id(upd).set_source_url(url);
+              ESP_LOGI("harness", "URL replaced from inside the check");
+            }
+
+api:
+  reboot_timeout: 0s
+
+http_request:
+  verify_ssl: false
+  timeout: 10s
+
+ota:
+  - platform: http_request
+    id: ota_http
+
+update:
+  - platform: http_request
+    id: upd
+    name: Firmware
+    source: ${base}/stable.json
+    update_interval: 1h
+
+globals:
+  - id: swap_in_check
+    type: bool
+    initial_value: "false"
+
+button:
+  - platform: template
+    name: Check
+    on_press:
+      - lambda: id(upd).check();
+  - platform: template
+    name: URL Beta String
+    on_press:
+      - lambda: |-
+          std::string url = "${base}/beta.json";
+          id(upd).set_source_url(url);
+  - platform: template
+    name: URL Slow Cstr
+    on_press:
+      - lambda: |-
+          std::string url = "${base}/slow.json";
+          id(upd).set_source_url(url.c_str());
+  - platform: template
+    name: URL Stable Literal
+    on_press:
+      - lambda: id(upd).set_source_url("${base}/stable.json");
+  - platform: template
+    name: URL Temporary
+    on_press:
+      - lambda: id(upd).set_source_url(std::string("${base}/beta.json"));
+  - platform: template
+    name: Same URL Back
+    on_press:
+      - lambda: id(upd).set_source_url(id(upd).get_source_url());
+  - platform: template
+    name: Check Then Swap
+    on_press:
+      - lambda: |-
+          // ESP32: the check task reads slow.json while the URL is replaced under it
+          id(upd).check();
+          std::string url = "${base}/beta.json";
+          id(upd).set_source_url(url);
+  - platform: template
+    name: Arm Swap In Check
+    on_press:
+      - lambda: id(swap_in_check) = true;
+  - platform: template
+    name: Heap
+    on_press:
+      - lambda: |-
+          #ifdef USE_ESP8266
+          ESP_LOGI("harness", "heap free %u", ESP.getFreeHeap());
+          #else
+          ESP_LOGI("harness", "heap free %u", (unsigned) heap_caps_get_free_size(MALLOC_CAP_INTERNAL));
+          #endif

.agents/skills/hardware-test/templates/ld2412-select-only-dut.yaml

@@ -0,0 +1,57 @@
+substitutions:
+  name: ld2412sel
+
+esphome:
+  name: ${name}
+
+esp32:
+  variant: esp32s3
+  board: esp32-s3-devkitc-1
+  flash_size: 8MB
+  framework:
+    type: esp-idf
+
+logger:
+  level: VERBOSE
+
+api:
+  reboot_timeout: 0s
+
+ota:
+  - platform: esphome
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+uart:
+  - id: uart_ld2412
+    tx_pin: GPIO43
+    rx_pin: GPIO44
+    baud_rate: 115200
+    debug:
+      direction: BOTH
+      dummy_receiver: false
+      after:
+        timeout: 10ms
+        bytes: 120
+
+ld2412:
+  id: ld2412_radar
+  uart_id: uart_ld2412
+
+select:
+  - platform: ld2412
+    ld2412_id: ld2412_radar
+    out_pin_level:
+      name: "LD2412 Hardware output pin level"
+
+binary_sensor:
+  - platform: gpio
+    name: "LD2412 Out Pin"
+    pin: GPIO38
+  - platform: ld2412
+    ld2412_id: ld2412_radar
+    has_target:
+      name: "LD2412 Presence"

.agents/skills/hardware-test/templates/ld2450-loopback.yaml

@@ -0,0 +1,258 @@
+esphome:
+  name: ${name}
+  on_boot:
+    priority: -100
+    then:
+      - lambda: |-
+          // UART0 TX looped back into its own RX so injected frames reach the hub
+          USC0(0) |= (1 << UCLBE);
+          ESP_LOGI("harness", "UART0 loopback on");
+
+esp8266:
+  board: d1_mini
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+api:
+  reboot_timeout: 0s
+
+logger:
+  baud_rate: 0
+  level: VERBOSE
+
+uart:
+  id: radar_uart
+  tx_pin: GPIO1
+  rx_pin: GPIO3
+  baud_rate: ${baud}
+  debug:
+    direction: TX
+    dummy_receiver: false
+    after:
+      delimiter: [0x04, 0x03, 0x02, 0x01]
+
+ld2450:
+  id: radar
+  uart_id: radar_uart
+
+select:
+  - platform: ld2450
+    baud_rate:
+      name: Baud Rate
+    zone_type:
+      name: Zone Type
+
+text_sensor:
+  - platform: ld2450
+    version:
+      name: Radar Version
+    target_1:
+      direction:
+        name: T1 Direction
+    target_2:
+      direction:
+        name: T2 Direction
+    target_3:
+      direction:
+        name: T3 Direction
+
+sensor:
+  - platform: ld2450
+    target_count:
+      name: Target Count
+
+button:
+  # periodic frames: header, 3 x (x, y, speed, resolution), footer
+  - platform: template
+    name: Frame Approach
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0xE8, 0x83, 0x14, 0x00, 0x64, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55, 0xCC]
+  - platform: template
+    name: Frame Away
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0xE8, 0x83, 0x14, 0x80, 0x64, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55, 0xCC]
+  - platform: template
+    name: Frame Stationary
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0xE8, 0x83, 0x00, 0x00, 0x64, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55, 0xCC]
+  - platform: template
+    name: Frame None
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55, 0xCC]
+  - platform: template
+    name: Frame T2 T3
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0xF4, 0x81, 0x20, 0x83, 0x1E, 0x00, 0x64, 0x00,
+                 0x2C, 0x01, 0xB0, 0x84, 0x0A, 0x80, 0x64, 0x00,
+                 0x55, 0xCC]
+  # query zone acks: header, length, command C1, status 01, 00 00, zone type, 00, 24 coordinate bytes, footer
+  - platform: template
+    name: Zone Ack Disabled
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xFD, 0xFC, 0xFB, 0xFA, 0x1E, 0x00, 0xC1, 0x01, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x04, 0x03, 0x02, 0x01]
+  - platform: template
+    name: Zone Ack Detection
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xFD, 0xFC, 0xFB, 0xFA, 0x1E, 0x00, 0xC1, 0x01, 0x00, 0x00, 0x01, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x04, 0x03, 0x02, 0x01]
+  - platform: template
+    name: Zone Ack Filter
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xFD, 0xFC, 0xFB, 0xFA, 0x1E, 0x00, 0xC1, 0x01, 0x00, 0x00, 0x02, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x04, 0x03, 0x02, 0x01]
+  # name based setters, the path lambdas use
+  - platform: template
+    name: Set Zone Filter By Name
+    on_press:
+      - lambda: id(radar).set_zone_type("Filter");
+  - platform: template
+    name: Set Zone Bogus By Name
+    on_press:
+      - lambda: id(radar).set_zone_type("Bogus");
+  - platform: template
+    name: Set Baud 57600 By Name
+    on_press:
+      - lambda: id(radar).set_baud_rate("57600");
+  - platform: template
+    name: Set Baud Bogus By Name
+    on_press:
+      - lambda: id(radar).set_baud_rate("Bogus");
+  # target 1 at x 772, y 258: bytes 04 03 02 01 are the command footer
+  - platform: template
+    name: Frame CmdFooter In Payload
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xAA, 0xFF, 0x03, 0x00,
+                 0x04, 0x03, 0x02, 0x01, 0x00, 0x00, 0x64, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55, 0xCC]
+  # zone ack, type Detection, zone 1 x1 = 0xCC55: bytes 55 CC are the periodic footer
+  - platform: template
+    name: Zone Ack DataFooter In Payload
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xFD, 0xFC, 0xFB, 0xFA, 0x1E, 0x00, 0xC1, 0x01, 0x00, 0x00, 0x01, 0x00,
+                 0x55, 0xCC, 0xC8, 0x00, 0xDC, 0x05, 0xB8, 0x0B, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x04, 0x03, 0x02, 0x01]
+  # zone ack, type Filter, zone 1 x1 = 0x0304 and y1 = 0x0102: bytes 04 03 02 01 are the command footer
+  - platform: template
+    name: Zone Ack CmdFooter In Payload
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xFD, 0xFC, 0xFB, 0xFA, 0x1E, 0x00, 0xC1, 0x01, 0x00, 0x00, 0x02, 0x00,
+                 0x04, 0x03, 0x02, 0x01, 0xDC, 0x05, 0xB8, 0x0B, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x04, 0x03, 0x02, 0x01]
+  # a periodic frame cut after 12 bytes, then a complete zone ack (type Disabled, zeros)
+  - platform: template
+    name: Cut Frame Then Zone Ack
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xAA, 0xFF, 0x03, 0x00, 0x00, 0x00, 0xE8, 0x83, 0x14, 0x00, 0x64, 0x00,
+                 0xFD, 0xFC, 0xFB, 0xFA, 0x1E, 0x00, 0xC1, 0x01, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x04, 0x03, 0x02, 0x01]
+  # a periodic frame missing its last byte, then a complete one (target 1 moving away)
+  - platform: template
+    name: Cut Frame Then Frame
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0xE8, 0x83, 0x14, 0x00, 0x64, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55,
+                 0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0xE8, 0x83, 0x14, 0x80, 0x64, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55, 0xCC]
+  # a command header claiming a 255 byte payload, then a complete periodic frame (target 1 stationary)
+  - platform: template
+    name: Bogus Length Then Frame
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0xFD, 0xFC, 0xFB, 0xFA, 0xFF, 0x00,
+                 0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0xE8, 0x83, 0x00, 0x00, 0x64, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55, 0xCC]
+  # five garbage bytes, then a complete periodic frame (target 1 approaching)
+  - platform: template
+    name: Garbage Then Frame
+    on_press:
+      - uart.write:
+          id: radar_uart
+          data: [0x01, 0x02, 0x03, 0x42, 0x99,
+                 0xAA, 0xFF, 0x03, 0x00,
+                 0x00, 0x00, 0xE8, 0x83, 0x14, 0x00, 0x64, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+                 0x55, 0xCC]
+
+number:
+  - platform: ld2450
+    presence_timeout:
+      name: Presence Timeout
+    zone_1:
+      x1:
+        name: Z1 X1
+      y1:
+        name: Z1 Y1
+      x2:
+        name: Z1 X2
+      y2:
+        name: Z1 Y2

.agents/skills/hardware-test/templates/modem/modem-common.yaml

@@ -0,0 +1,65 @@
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+  watchdog_timeout: 30s
+
+logger:
+  level: DEBUG
+
+api:
+  reboot_timeout: 0s
+
+modem:
+  id: atmodem
+  rx_pin: GPIO26
+  tx_pin: GPIO27
+  baud_rate: 115200
+  model: SIM7600
+  apn: internet
+  pin_code: "0000"
+  init_at:
+    - ATI
+  urc:
+    name: Modem URC
+  reboot_timeout: ${modem_reboot_timeout}
+  on_connect:
+    logger.log: "modem connected"
+  on_disconnect:
+    logger.log: "modem disconnected"
+  on_sync:
+    logger.log: "modem synced"
+
+sensor:
+  - platform: uptime
+    name: Uptime
+    update_interval: 30s
+  - platform: debug
+    free:
+      name: Heap Free
+    loop_time:
+      name: Loop Time
+
+debug:
+  update_interval: 30s
+
+button:
+  - platform: template
+    name: Modem Enable
+    on_press:
+      - modem.enable
+  - platform: template
+    name: Modem Disable
+    on_press:
+      - modem.disable
+  - platform: template
+    name: Modem Send AT
+    on_press:
+      - modem.send_at: "AT+CGSN"
+
+interval:
+  - interval: 20s
+    then:
+      - lambda: |-
+          ESP_LOGI("alive", "uptime %u s enabled=%d connected=%d", (unsigned) (millis() / 1000),
+                   id(atmodem).is_enabled(), id(atmodem).is_connected());

.agents/skills/hardware-test/templates/modem/modemo.yaml

@@ -0,0 +1,26 @@
+substitutions:
+  modem_reboot_timeout: 2min
+
+esphome:
+  name: modemo
+  on_boot:
+    priority: -100
+    then:
+      - modem.disable
+      - modem.enable
+      - if:
+          condition:
+            modem.enabled:
+          then:
+            modem.send_at: "AT+CGSN"
+          else:
+            modem.enable:
+      - if:
+          condition:
+            not:
+              modem.connected:
+          then:
+            logger.log: modem not connected at boot
+
+packages:
+  common: !include modem-common.yaml

.agents/skills/hardware-test/templates/modem/modemw.yaml

@@ -0,0 +1,12 @@
+substitutions:
+  modem_reboot_timeout: 0s
+
+esphome:
+  name: modemw
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+packages:
+  common: !include modem-common.yaml

.agents/skills/hardware-test/templates/store_yaml/boards/sy8266.yaml

@@ -0,0 +1,15 @@
+esphome:
+  name: sy8266
+
+esp8266:
+  board: d1_mini
+
+api:
+  encryption:
+    key: !secret api_key
+  reboot_timeout: 0s
+
+packages:
+  common: !include ../sy-common.yaml
+
+store_yaml:

.agents/skills/hardware-test/templates/store_yaml/boards/sy8266s.yaml

@@ -0,0 +1,16 @@
+esphome:
+  name: sy8266s
+
+esp8266:
+  board: d1_mini
+
+api:
+  encryption:
+    key: !secret api_key
+  reboot_timeout: 0s
+
+packages:
+  common: !include ../sy-common.yaml
+
+store_yaml:
+  include_secrets: true

.agents/skills/hardware-test/templates/store_yaml/sy-common.yaml

@@ -0,0 +1,24 @@
+# shared package for the store_yaml hardware test
+substitutions:
+  greeting: "hello from the package"
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+logger:
+  level: DEBUG
+
+ota:
+  - platform: esphome
+    password: recoverme123
+
+sensor:
+  - platform: template
+    name: Package Sensor
+    lambda: return 42.0;
+    update_interval: 60s
+
+packages:
+  extra: !include sy-extra.yaml

.agents/skills/hardware-test/templates/store_yaml/sy-extra.yaml

@@ -0,0 +1,6 @@
+# second level include
+text_sensor:
+  - platform: template
+    name: Greeting
+    lambda: return std::string("${greeting}");
+    update_interval: 60s

.agents/skills/hardware-test/templates/wisp-client.yaml

@@ -0,0 +1,57 @@
+substitutions:
+  name: wispcli
+  ap_ssid: wisp-bridge
+
+esphome:
+  name: ${name}
+
+esp8266:
+  board: d1_mini
+
+logger:
+  level: DEBUG
+
+wifi:
+  ssid: ${ap_ssid}
+  password: !secret wisp_psk
+  power_save_mode: none
+  reboot_timeout: 0s
+
+http_request:
+  esp8266_disable_ssl_support: true
+  timeout: 8s
+
+time:
+  - platform: sntp
+    id: sntp_time
+    on_time_sync:
+      - logger.log:
+          format: "SNTP synced"
+          level: INFO
+
+interval:
+  - interval: 15s
+    then:
+      - http_request.get:
+          url: !secret lan_http
+          capture_response: true
+          on_response:
+            - logger.log:
+                format: "LAN GET status %d body %s"
+                args: ["response->status_code", "body.c_str()"]
+                level: INFO
+          on_error:
+            - logger.log:
+                format: "LAN GET failed"
+                level: WARN
+      - http_request.get:
+          url: http://example.com/
+          on_response:
+            - logger.log:
+                format: "WAN GET status %d"
+                args: ["response->status_code"]
+                level: INFO
+          on_error:
+            - logger.log:
+                format: "WAN GET failed"
+                level: WARN

.agents/skills/hardware-test/templates/wisp-ethernet-dut.yaml

@@ -0,0 +1,40 @@
+substitutions:
+  name: wispeth
+  ap_ssid: wisp-bridge
+
+esphome:
+  name: ${name}
+
+esp32:
+  board: esp32-s3-devkitc-1
+  variant: esp32s3
+  flash_size: 16MB
+  framework:
+    type: esp-idf
+
+logger:
+  hardware_uart: USB_SERIAL_JTAG
+  level: VERBOSE
+
+api:
+  encryption:
+    key: !secret api_key
+  reboot_timeout: 0s
+
+ota:
+  - platform: esphome
+
+ethernet:
+  type: W5500
+  clk_pin: GPIO13
+  mosi_pin: GPIO11
+  miso_pin: GPIO12
+  cs_pin: GPIO14
+  interrupt_pin: GPIO10
+  reset_pin: GPIO9
+
+wifi:
+  ap:
+    ssid: ${ap_ssid}
+    password: !secret wisp_psk
+    ap_mode: WISP

.github/workflows/ci.yml

@@ -286,7 +286,7 @@ jobs:
           fi
           echo "version=$version" >> "$GITHUB_OUTPUT"
       - name: Run prek
-        uses: j178/prek-action@1382ad72dea72f9d53832f2bcb65b3e87a947204 # v3.0.1
+        uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0
         with:
           prek-version: ${{ steps.prek.outputs.version }}
           # This job only runs on pull requests, so nothing ever populates

.github/workflows/release.yml

@@ -94,7 +94,7 @@ jobs:
           pip3 install build
           python3 -m build
       - name: Publish
-        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
         with:
           skip-existing: true
 

AGENTS.md

@@ -209,7 +209,8 @@ file does, and it is the authority when they disagree. The most useful starting
         registered with `automation.ApplyBytes` (see Actions below), which keeps a constant payload in flash;
         `TEMPLATABLE_BYTES` is for a `play()` that does more with the bytes.
     *   **Fixed sets of names** (status words, model names): a `PROGMEM_STRING_TABLE` (`esphome/core/progmem.h`),
-        logged with `get_log_str` and `LOG_STR_ARG`, copied out with `ESPHOME_strncpy_P` before `publish_state`.
+        logged with `get_log_str` and `LOG_STR_ARG`, published on a text sensor with
+        `publish_state(Table::get_progmem_str(idx, fallback))`, which copies it out of flash on ESP8266.
         A `dump_config` helper that picks a name returns `const LogString *` from `LOG_STR(...)`.
     *   **CRCs and bit tricks** come from `esphome/core/helpers.h` (`crc8`, `crc16`, `xor_bytes`, `sum16_bytes`,
         `reverse_bits`, `encode_uint16`, `encode_value_le`, `sign_extend<BITS>`, `bcd_to_uint8`, `assign_bits`); pick
@@ -446,6 +447,8 @@ file does, and it is the authority when they disagree. The most useful starting
           switches = switch.sub_switches(config, parent=hub)
           await switches(CONF_BLUETOOTH, None, apply="set_bluetooth(state)", publish="after")
           ```
+          Restore an owned or standalone switch in `setup()` with `sw->restore()`, or `restore(default)`
+          to still drive a state when the restore mode is disabled.
 
         - **Other codegen helpers:** `uart.new_uart_component(config, *ctor_args)` (and `i2c.new_i2c_component`,
           `spi.new_spi_component`, `modbus.new_modbus_client_component`, `ble_client.new_ble_node_component`)
@@ -647,7 +650,13 @@ file does, and it is the authority when they disagree. The most useful starting
     *   **Common Validators:** `cv.int_`, `cv.float_`, `cv.string`, `cv.boolean`, `cv.int_range(min=0, max=100)`, `cv.positive_int`, `cv.percentage`.
     *   **Complex Validation:** `cv.All(cv.string, cv.Length(min=1, max=50))`, `cv.Any(cv.int_, cv.string)`.
     *   **Platform-Specific:** `cv.only_on(["esp32", "esp8266"])`, `esp32.only_on_variant(...)`, `cv.only_on_esp32`, `cv.only_on_esp8266`, `cv.only_on_rp2040`.
-    *   **Framework-Specific:** `cv.only_with_framework(...)`, `cv.only_with_arduino`, `cv.only_with_esp_idf`.
+    *   **Framework-Specific:** `cv.only_with_framework(...)`, `cv.only_with_arduino`. On the ESP32, Arduino is
+        built as a component of ESP-IDF, so an ESP-IDF API, sdkconfig option or version floor is there on both
+        frameworks: gate on `esp32.require_idf_version(cv.Version(5, 5, 3), "psram_dma")`, which checks the
+        platform and the ESP-IDF under either framework, as `spi`, `usb_host` and `wifi` do. Reserve
+        `cv.only_with_framework("esp-idf")` for a build that has been tried on Arduino and fails there, and write
+        the actual failure next to it (`sendspin`: arduino-esp32 below ESP-IDF 6.0 bundles a second libsodium,
+        and from 6.0 sendspin-cpp's enumerators collide with `Arduino.h` macros such as `DISPLAY`).
     *   **Schema Extensions:**
         ```python
         CONFIG_SCHEMA = cv.Schema({ ... })

CODEOWNERS

@@ -147,6 +147,7 @@ esphome/components/cst816/* @clydebarrow
 esphome/components/cst9220/* @clydebarrow
 esphome/components/ct_clamp/* @jesserockz
 esphome/components/current_based/* @djwmarcx
+esphome/components/cw2017/* @exciton
 esphome/components/d01/* @ch604
 esphome/components/dac7678/* @NickB1
 esphome/components/daikin_arc/* @MagicBear
@@ -157,6 +158,7 @@ esphome/components/dashboard_import/* @esphome/core
 esphome/components/datetime/* @jesserockz @rfdarter
 esphome/components/debug/* @esphome/core
 esphome/components/delonghi/* @grob6000
+esphome/components/delta_wallbox/* @epicRE
 esphome/components/dew_point/* @CFlix
 esphome/components/dfplayer/* @glmnet
 esphome/components/dfrobot_sen0395/* @niklasweber
@@ -174,6 +176,11 @@ esphome/components/ds2484/* @mrk-its
 esphome/components/ds248x/* @tomwellnitz
 esphome/components/ds3231/* @linkedupbits
 esphome/components/dsmr/* @glmnet @PolarGoose
+esphome/components/duco/* @kokx
+esphome/components/duco/number/* @kokx
+esphome/components/duco/select/* @kokx
+esphome/components/duco/sensor/* @kokx
+esphome/components/duco/text_sensor/* @kokx
 esphome/components/duty_time/* @dudanov
 esphome/components/ecocomfort2/* @gledian
 esphome/components/ee895/* @Stock-M
@@ -325,6 +332,7 @@ esphome/components/internal_temperature/* @Mat931
 esphome/components/interval/* @esphome/core
 esphome/components/ir_rf_base/* @bdraco @kbx81
 esphome/components/ir_rf_proxy/* @kbx81
+esphome/components/islandaire/* @ipopov
 esphome/components/it8951/* @koosoli @limengdu @Passific
 esphome/components/jsn_sr04t/* @Mafus1
 esphome/components/json/* @esphome/core
@@ -356,6 +364,7 @@ esphome/components/lm75b/* @beormund
 esphome/components/ln882h_ble/* @Bl00d-B0b
 esphome/components/ln882h_ble_tracker/* @Bl00d-B0b
 esphome/components/ln882x/* @lamauny
+esphome/components/ln882x_spi_led_strip/* @sebo-b
 esphome/components/lock/* @esphome/core
 esphome/components/logger/* @esphome/core
 esphome/components/logger/select/* @clydebarrow
@@ -366,11 +375,13 @@ esphome/components/ltr390/* @latonita @sjtrny
 esphome/components/ltr501/* @latonita
 esphome/components/ltr_als_ps/* @latonita
 esphome/components/lvgl/* @clydebarrow
+esphome/components/m5stack_4relay/* @KoenBreeman
 esphome/components/m5stack_8angle/* @rnauber
 esphome/components/mapping/* @clydebarrow
 esphome/components/matrix_keypad/* @ssieb
 esphome/components/max17043/* @blacknell
-esphome/components/max17048/* @B48D81EFCC
+esphome/components/max17048/* @B48D81EFCC @ryansch
+esphome/components/max170xx/* @ryansch
 esphome/components/max31865/* @DAVe3283
 esphome/components/max31888/* @JiriPrchal
 esphome/components/max44009/* @berfenger
@@ -425,6 +436,7 @@ esphome/components/modbus_controller/sensor/* @martgras
 esphome/components/modbus_controller/switch/* @martgras
 esphome/components/modbus_controller/text_sensor/* @martgras
 esphome/components/modbus_server/* @exciton
+esphome/components/modem/* @oarcher
 esphome/components/mopeka_ble/* @Fabian-Schmidt @spbrogan
 esphome/components/mopeka_pro_check/* @spbrogan
 esphome/components/mopeka_std_check/* @Fabian-Schmidt
@@ -458,6 +470,8 @@ esphome/components/openthread/* @mrene
 esphome/components/opt3001/* @ccutrer
 esphome/components/ota/* @esphome/core
 esphome/components/output/* @esphome/core
+esphome/components/packet_interface/* @clydebarrow
+esphome/components/packet_interface/packet_transport/* @clydebarrow
 esphome/components/packet_transport/* @clydebarrow
 esphome/components/pca6416a/* @Mat931
 esphome/components/pca9505/* @ajfriesen @ssieb
@@ -537,6 +551,7 @@ esphome/components/sdp3x/* @Azimath
 esphome/components/seeed_mr24hpc1/* @limengdu
 esphome/components/seeed_mr60bha2/* @limengdu
 esphome/components/seeed_mr60fda2/* @limengdu
+esphome/components/seeed_multi_channel_relay/* @KoenBreeman
 esphome/components/selec_meter/* @sourabhjaiswal
 esphome/components/select/* @esphome/core
 esphome/components/sen0321/* @notjj
@@ -677,10 +692,12 @@ esphome/components/tuya/water_heater/* @iago-veiga
 esphome/components/uart/* @esphome/core
 esphome/components/uart/button/* @ssieb
 esphome/components/uart/event/* @eoasmxd
+esphome/components/uart/packet_interface/* @clydebarrow
 esphome/components/uart/packet_transport/* @clydebarrow
 esphome/components/uart_mux/* @kbx81
 esphome/components/uart_tcp/* @Bascht74
 esphome/components/udp/* @clydebarrow
+esphome/components/udp/packet_interface/* @clydebarrow
 esphome/components/ufire_ec/* @pvizeli
 esphome/components/ufire_ise/* @pvizeli
 esphome/components/ufm01/* @ljungqvist

docker/Dockerfile

@@ -84,3 +84,5 @@ FROM base-${BUILD_TYPE} AS final
 # Copy esphome and install
 COPY . /esphome
 RUN uv pip install --no-cache-dir -e /esphome
+# The tree has no .git; lets SBOM manifests describe it as the release it was built from
+ENV ESPHOME_IS_DOCKER_IMAGE=true

esphome/arduino/library.py

@@ -44,7 +44,6 @@ from esphome.platformio.library import (
     normalize_dependencies,
     parse_library_json,
     parse_library_properties,
-    warn_properties_depends,
 )
 
 _LOGGER = logging.getLogger(__name__)
@@ -283,7 +282,6 @@ def _bundled_library(framework_path: Path, name: str) -> ArduinoLibrary:
                 "resolved automatically; add them with add_library() if needed",
                 name,
             )
-        warn_properties_depends(name, data)
         build = data.get("build")
         if isinstance(build, dict) and build.get("extraScript"):
             # Scripts only run on the converted path; building without

esphome/automation.py

@@ -24,6 +24,7 @@ from esphome.const import (
 )
 from esphome.core import CORE, ID, EsphomeError, HexInt, Lambda
 from esphome.cpp_generator import (
+    CallExpression,
     Expression,
     LambdaExpression,
     MockObj,
@@ -446,9 +447,17 @@ async def _apply_parent(config: ConfigType, id_key: str = CONF_ID) -> str:
 
 
 def _apply_lambda_args(args: TemplateArgsType) -> TemplateArgsType:
-    # The generated function's parameters; a std::string arg is never copied.
+    # The generated function's parameters: a reference keeps its spelling, so a mutable
+    # one stays mutable; a value is taken by const reference, so a std::string is never copied.
     return [
-        (cg.RawExpression(f"const std::remove_cvref_t<{cg.safe_exp(t)}> &"), arg)
+        (
+            (
+                t
+                if str(cg.safe_exp(t)).rstrip().endswith("&")
+                else cg.RawExpression(f"const std::remove_cvref_t<{cg.safe_exp(t)}> &")
+            ),
+            arg,
+        )
         for t, arg in args
     ]
 
@@ -578,7 +587,7 @@ def apply_action_builder(
             if isinstance(spec, ApplyBytes):
                 statements.extend(
                     await _render_bytes(
-                        spec, config, receiver, parent, lambda_args, table_name
+                        spec, config, receiver, parent, args, table_name
                     )
                 )
                 continue
@@ -608,10 +617,14 @@ async def _render_bytes(
     config: ConfigType,
     receiver: str,
     parent: str,
-    lambda_args: TemplateArgsType,
+    args: TemplateArgsType,
     table_name: str,
 ) -> list[str]:
-    """The statements for one ``ApplyBytes``: what ``TemplatableBytes::visit`` does, inlined."""
+    """The statements for one ``ApplyBytes``: what ``TemplatableBytes::visit`` does, inlined.
+
+    The payload lambda keeps the automation's own argument types, as ``TemplatableBytes``
+    gave it, and is always called, so a body that modifies an argument still compiles.
+    """
     value = _config_lookup(config, spec.conf_key)
     if value is None:
         return []
@@ -622,21 +635,23 @@ async def _render_bytes(
 
     if isinstance(value, Lambda):
         inner = await cg.process_lambda(
-            value, lambda_args, return_type=cg.std_vector.template(cg.uint8)
+            value, args, return_type=cg.std_vector.template(cg.uint8)
         )
+        # Never reduced into the outer function, whose own parameters are const
+        call = CallExpression(inner, *[cg.MockObj(name) for _, name in args])
         return [
             "{",
-            f"  const std::vector<uint8_t> esphome__bytes = ({call_lambda(inner)});",
+            f"  const std::vector<uint8_t> esphome__bytes = {call};",
             f"  {send(spec.target, 'esphome__bytes.data(), esphome__bytes.size()')}",
             "}",
         ]
     table, size = _static_bytes(table_name, value)
     # Qualified so a trigger argument cannot shadow a reused table; an empty payload is nullptr
-    args = f"::{table}, {size}" if size else f"{table}, {size}"
+    table_args = f"::{table}, {size}" if size else f"{table}, {size}"
     if CORE.is_esp8266 and spec.progmem_target is not None:
-        return [send(spec.progmem_target, args)]
+        return [send(spec.progmem_target, table_args)]
     if not CORE.is_esp8266:
-        return [send(spec.target, args)]
+        return [send(spec.target, table_args)]
     # A PROGMEM table must be read with aligned loads on ESP8266, so copy it out first;
     # the length is known here, so the copy is an exact array, on the heap past ``stack``.
     # An empty payload still gets a one byte array: the raw lwIP socket rejects a null buffer.
@@ -649,7 +664,7 @@ async def _render_bytes(
         )
     statements = ["{", f"  {buffer}"]
     if size:
-        statements.append(f"  esphome::progmem_memcpy({data}, {args});")
+        statements.append(f"  esphome::progmem_memcpy({data}, {table_args});")
     return [*statements, f"  {send(spec.target, f'{data}, {size}')}", "}"]
 
 

esphome/codegen.py

@@ -49,6 +49,7 @@ from esphome.cpp_generator import (  # noqa: F401
     static_const_array,
     static_function,
     templatable,
+    unique_global_id,
     variable,
     with_local_variable,
 )

esphome/components/alarm_control_panel/__init__.py

@@ -91,17 +91,19 @@ def alarm_control_panel_schema(
 
 
 ALARM_CONTROL_PANEL_ACTION_SCHEMA = maybe_simple_id(
+    {
+        cv.GenerateID(): cv.use_id(AlarmControlPanel),
+    }
+)
+
+ALARM_CONTROL_PANEL_CODE_ACTION_SCHEMA = maybe_simple_id(
     {
         cv.GenerateID(): cv.use_id(AlarmControlPanel),
         cv.Optional(CONF_CODE): cv.templatable(cv.string),
     }
 )
 
-ALARM_CONTROL_PANEL_CONDITION_SCHEMA = maybe_simple_id(
-    {
-        cv.GenerateID(): cv.use_id(AlarmControlPanel),
-    }
-)
+ALARM_CONTROL_PANEL_CONDITION_SCHEMA = ALARM_CONTROL_PANEL_ACTION_SCHEMA
 
 
 _CALLBACK_AUTOMATIONS = (
@@ -194,7 +196,7 @@ for _name, _arm in (
 ):
     automation.register_apply_action(
         _name,
-        ALARM_CONTROL_PANEL_ACTION_SCHEMA,
+        ALARM_CONTROL_PANEL_CODE_ACTION_SCHEMA,
         automation.ApplyCall(_arm),
         automation.ApplyField(CONF_CODE, "set_code", cg.std_string),
         call="make_call",

esphome/components/as7341/as7341.cpp

@@ -110,12 +110,12 @@ bool AS7341Component::read_channels(uint16_t *data) {
   this->set_smux_low_channels(true);
   this->enable_spectral_measurement(true);
   this->wait_for_data();
-  bool low_success = this->read_bytes_16(AS7341_CH0_DATA_L, data, 6);
+  bool low_success = this->read_bytes_16_le(AS7341_CH0_DATA_L, data, 6);
 
   this->set_smux_low_channels(false);
   this->enable_spectral_measurement(true);
   this->wait_for_data();
-  bool high_sucess = this->read_bytes_16(AS7341_CH0_DATA_L, &data[6], 6);
+  bool high_sucess = this->read_bytes_16_le(AS7341_CH0_DATA_L, &data[6], 6);
 
   return low_success && high_sucess;
 }

esphome/components/beken_spi_led_strip/led_strip.cpp

@@ -293,14 +293,9 @@ void BekenSPILEDStripLightOutput::set_led_params(uint8_t bit0, uint8_t bit1, uin
 }
 
 void BekenSPILEDStripLightOutput::write_state(light::LightState *state) {
-  // protect from refreshing too often
   uint32_t now = micros();
-  if (this->max_refresh_rate_.has_value() && *this->max_refresh_rate_ != 0 &&
-      (now - this->last_refresh_) < *this->max_refresh_rate_) {
-    // try again next loop iteration, so that this change won't get lost
-    this->schedule_show();
+  if (this->throttle_show_(now, this->last_refresh_, this->max_refresh_rate_))
     return;
-  }
   this->last_refresh_ = now;
   this->mark_shown_();
 
@@ -369,17 +364,6 @@ void BekenSPILEDStripLightOutput::write_state(light::LightState *state) {
   this->status_clear_warning();
 }
 
-light::ESPColorView BekenSPILEDStripLightOutput::get_view_internal(int32_t index) const {
-  const light::ChannelColors &colors = this->channel_colors_;
-  uint8_t *led = this->buf_ + (index * colors.bytes_per_led());
-  return {led + colors.r,
-          led + colors.g,
-          led + colors.b,
-          colors.has_white() ? led + colors.w : nullptr,
-          &this->effect_data_[index],
-          &this->correction_};
-}
-
 void BekenSPILEDStripLightOutput::dump_config() {
   ESP_LOGCONFIG(TAG,
                 "Beken SPI LED Strip:\n"
@@ -390,7 +374,7 @@ void BekenSPILEDStripLightOutput::dump_config() {
                 "  Channel colors: %s\n"
                 "  Max refresh rate: %" PRIu32 "\n"
                 "  Number of LEDs: %u",
-                this->channel_colors_.to_string(channel_colors), this->max_refresh_rate_.value_or(0), this->num_leds_);
+                this->channel_colors_.to_string(channel_colors), this->max_refresh_rate_, this->num_leds_);
 }
 
 float BekenSPILEDStripLightOutput::get_setup_priority() const { return setup_priority::HARDWARE; }

esphome/components/beken_spi_led_strip/led_strip.h

@@ -18,15 +18,7 @@ class BekenSPILEDStripLightOutput final : public light::AddressableLight {
   float get_setup_priority() const override;
 
   int32_t size() const override { return this->num_leds_; }
-  light::LightTraits get_traits() override {
-    auto traits = light::LightTraits();
-    if (this->channel_colors_.has_white()) {
-      traits.set_supported_color_modes({light::ColorMode::RGB_WHITE, light::ColorMode::WHITE});
-    } else {
-      traits.set_supported_color_modes({light::ColorMode::RGB});
-    }
-    return traits;
-  }
+  light::LightTraits get_traits() override { return this->channel_colors_.traits(); }
 
   void set_pin(uint8_t pin) { this->pin_ = pin; }
   void set_num_leds(uint16_t num_leds) { this->num_leds_ = num_leds; }
@@ -38,14 +30,16 @@ class BekenSPILEDStripLightOutput final : public light::AddressableLight {
   void set_led_params(uint8_t bit0, uint8_t bit1, uint32_t spi_frequency);
 
   void clear_effect_data() override {
-    for (int i = 0; i < this->size(); i++)
-      this->effect_data_[i] = 0;
+    if (this->effect_data_ != nullptr)
+      memset(this->effect_data_, 0, this->num_leds_);
   }
 
   void dump_config() override;
 
  protected:
-  light::ESPColorView get_view_internal(int32_t index) const override;
+  light::ESPColorView get_view_internal(int32_t index) const override {
+    return this->channel_colors_.view(this->buf_, this->effect_data_, index, &this->correction_);
+  }
 
   size_t get_buffer_size_() const { return this->num_leds_ * this->channel_colors_.bytes_per_led(); }
 
@@ -62,7 +56,7 @@ class BekenSPILEDStripLightOutput final : public light::AddressableLight {
   light::ChannelColors channel_colors_{0, 1, 2, light::ChannelColors::NO_WHITE};
 
   uint32_t last_refresh_{0};
-  optional<uint32_t> max_refresh_rate_{};
+  uint32_t max_refresh_rate_{0};
 };
 
 }  // namespace esphome::beken_spi_led_strip

esphome/components/binary_sensor/__init__.py

@@ -3,7 +3,6 @@ from logging import getLogger
 from esphome import automation, core
 from esphome.automation import maybe_simple_id
 import esphome.codegen as cg
-from esphome.components import mqtt, web_server, zigbee
 from esphome.components.const import CONF_ON_STATE_CHANGE
 from esphome.config_helpers import filter_source_files_from_defines
 import esphome.config_validation as cv
@@ -29,7 +28,6 @@ from esphome.const import (
     CONF_STATE,
     CONF_TIMING,
     CONF_TRIGGER_ID,
-    CONF_WEB_SERVER,
     DEVICE_CLASS_BATTERY,
     DEVICE_CLASS_BATTERY_CHARGING,
     DEVICE_CLASS_CARBON_MONOXIDE,
@@ -61,10 +59,12 @@ from esphome.const import (
     DEVICE_CLASS_VIBRATION,
     DEVICE_CLASS_WINDOW,
 )
-from esphome.core import CORE, ID, CoroPriority, coroutine_with_priority
+from esphome.core import CORE, ID, CoroPriority, coroutine_with_priority, entity_helpers
 from esphome.core.entity_helpers import (
     SubEntities,
     entity_duplicate_validator,
+    lazy_load_validator,
+    mqtt_component_class,
     queue_entity_register,
     setup_device_class,
     setup_entity,
@@ -433,14 +433,14 @@ def validate_publish_initial_state(value):
 
 
 _BINARY_SENSOR_SCHEMA = (
-    cv.ENTITY_BASE_SCHEMA.extend(web_server.WEBSERVER_SORTING_SCHEMA)
+    cv.ENTITY_BASE_SCHEMA.extend(entity_helpers.WEBSERVER_SORTING_SCHEMA)
     .extend(cv.MQTT_COMPONENT_SCHEMA)
-    .extend(zigbee.BINARY_SENSOR_SCHEMA)
+    .extend(entity_helpers.ZIGBEE_BINARY_SENSOR_SCHEMA)
     .extend(
         {
             cv.GenerateID(): cv.declare_id(BinarySensor),
             cv.OnlyWith(CONF_MQTT_ID, "mqtt"): cv.declare_id(
-                mqtt.MQTTBinarySensorComponent
+                mqtt_component_class("MQTTBinarySensorComponent")
             ),
             cv.Exclusive(
                 CONF_PUBLISH_INITIAL_STATE, CONF_TRIGGER_ON_INITIAL_STATE
@@ -508,7 +508,7 @@ _BINARY_SENSOR_SCHEMA = (
 
 
 _BINARY_SENSOR_SCHEMA.add_extra(entity_duplicate_validator("binary_sensor"))
-_BINARY_SENSOR_SCHEMA.add_extra(zigbee.validate_binary_sensor)
+_BINARY_SENSOR_SCHEMA.add_extra(lazy_load_validator("zigbee", "validate_binary_sensor"))
 
 
 def binary_sensor_schema(
@@ -619,14 +619,12 @@ async def setup_binary_sensor_core_(var, config):
 
     CORE.add_job(_build_binary_sensor_automations, var, config)
 
-    if mqtt_id := config.get(CONF_MQTT_ID):
-        mqtt_ = cg.new_Pvariable(mqtt_id, var)
-        await mqtt.register_mqtt_component(mqtt_, config)
+    await entity_helpers.setup_entity_integrations(var, config)
 
-    if web_server_config := config.get(CONF_WEB_SERVER):
-        await web_server.add_entity_config(var, web_server_config)
+    if "zigbee" in CORE.loaded_integrations:
+        from esphome.components import zigbee
 
-    await zigbee.setup_binary_sensor(var, config)
+        await zigbee.setup_binary_sensor(var, config)
 
 
 async def register_binary_sensor(var, config):

esphome/components/bp1658cj/output.py

@@ -20,6 +20,11 @@ CONFIG_SCHEMA = output.FLOAT_OUTPUT_SCHEMA.extend(
 ).extend(cv.COMPONENT_SCHEMA)
 
 
+FINAL_VALIDATE_SCHEMA = output.final_validate_unique_channel(
+    platform="bp1658cj", hub_key=CONF_BP1658CJ_ID
+)
+
+
 async def to_code(config: ConfigType) -> None:
     var = cg.new_Pvariable(config[CONF_ID])
     await output.register_output(var, config)

esphome/components/bp5758d/output.py

@@ -21,6 +21,11 @@ CONFIG_SCHEMA = output.FLOAT_OUTPUT_SCHEMA.extend(
 ).extend(cv.COMPONENT_SCHEMA)
 
 
+FINAL_VALIDATE_SCHEMA = output.final_validate_unique_channel(
+    platform="bp5758d", hub_key=CONF_BP5758D_ID
+)
+
+
 async def to_code(config: ConfigType) -> None:
     var = cg.new_Pvariable(config[CONF_ID])
     await output.register_output(var, config)

esphome/components/cc1101/__init__.py

@@ -295,11 +295,6 @@ async def to_code(config):
         )
 
 
-# Actions
-SendPacketAction = ns.class_(
-    "SendPacketAction", automation.Action, cg.Parented.template(CC1101Component)
-)
-
 CC1101_ACTION_SCHEMA = cv.Schema(
     maybe_simple_id({cv.GenerateID(CONF_ID): cv.use_id(CC1101Component)})
 )
@@ -338,23 +333,11 @@ SEND_PACKET_ACTION_SCHEMA = cv.maybe_simple_value(
 )
 
 
-@automation.register_action(
+automation.register_apply_action(
     "cc1101.send_packet",
-    SendPacketAction,
     SEND_PACKET_ACTION_SCHEMA,
-    synchronous=True,
+    automation.ApplyBytes(CONF_DATA, "transmit_packet({})"),
 )
-async def send_packet_action_to_code(config, action_id, template_arg, args):
-    var = cg.new_Pvariable(action_id, template_arg)
-    await cg.register_parented(var, config[CONF_ID])
-    await automation.templatable_bytes(
-        config[CONF_DATA],
-        args,
-        var.set_data_template,
-        var.set_data_static,
-        "cc1101_data",
-    )
-    return var
 
 
 _CONFIG_VALIDATORS = {opt.schema: validator for opt, validator in CONFIG_MAP.items()}

esphome/components/cc1101/cc1101.h

@@ -132,13 +132,4 @@ class CC1101Component final : public Component,
   bool enter_tx_();
 };
 
-// Action Wrappers
-template<typename... Ts> class SendPacketAction final : public Action<Ts...>, public Parented<CC1101Component> {
-  TEMPLATABLE_BYTES(data)
-
-  void play(const Ts &...x) override {
-    this->data_.visit([this](const uint8_t *data, size_t len) { this->parent_->transmit_packet(data, len); }, x...);
-  }
-};
-
 }  // namespace esphome::cc1101

esphome/components/ch422g/ch422g.cpp

@@ -1,4 +1,5 @@
 #include "ch422g.h"
+#include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 
 namespace esphome::ch422g {
@@ -59,11 +60,7 @@ bool CH422GComponent::digital_read(uint8_t pin) {
 }
 
 void CH422GComponent::digital_write(uint8_t pin, bool value) {
-  if (value) {
-    this->output_bits_ |= (1 << pin);
-  } else {
-    this->output_bits_ &= ~(1 << pin);
-  }
+  assign_bits(this->output_bits_, 1 << pin, value);
   this->write_outputs_();
 }
 

esphome/components/ch423/ch423.cpp

@@ -1,4 +1,5 @@
 #include "ch423.h"
+#include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 #include "esphome/core/progmem.h"
 
@@ -62,11 +63,7 @@ bool CH423Component::digital_read(uint8_t pin) {
 }
 
 void CH423Component::digital_write(uint8_t pin, bool value) {
-  if (value) {
-    this->output_bits_ |= (1 << pin);
-  } else {
-    this->output_bits_ &= ~(1 << pin);
-  }
+  assign_bits(this->output_bits_, 1 << pin, value);
   this->write_outputs_();
 }
 

esphome/components/climate_ir/climate_ir.cpp

@@ -24,7 +24,9 @@ climate::ClimateTraits ClimateIR::traits() {
   return traits;
 }
 
-void ClimateIR::setup() {
+void ClimateIR::setup() { this->setup_(this->restore_state_()); }
+
+void ClimateIR::setup_(optional<climate::ClimateDeviceRestoreState> restore) {
   if (this->sensor_) {
     this->sensor_->add_on_state_callback([this](float state) {
       this->current_temperature = state;
@@ -43,7 +45,6 @@ void ClimateIR::setup() {
   }
 
   // restore set points
-  auto restore = this->restore_state_();
   if (restore.has_value()) {
     restore->apply(this);
   } else {

esphome/components/climate_ir/climate_ir.h

@@ -60,6 +60,10 @@ class ClimateIR : public Component,
   /// Transmit via IR the state of this climate controller.
   virtual void transmit_state() = 0;
 
+  /// setup() with the restored state already loaded, for subclasses that read it first. Load it only once:
+  /// every restore_state_() call takes a new preference slot on some platforms.
+  void setup_(optional<climate::ClimateDeviceRestoreState> restore);
+
   // Dummy implement on_receive so implementation is optional for inheritors
   bool on_receive(remote_base::RemoteReceiveData data) override { return false; };
 

esphome/components/const/__init__.py

@@ -19,6 +19,7 @@ CONF_BITRATE = "bitrate"
 CONF_BLUE_CHANNEL = "blue_channel"
 CONF_BORDER_ROUTER = "border_router"
 CONF_BREATH_VOC_EQUIVALENT = "breath_voc_equivalent"
+CONF_BUTTONS = "buttons"
 CONF_BYTE_ORDER = "byte_order"
 CONF_CHANNEL_COLORS = "channel_colors"
 CONF_CLEAR_CHANNEL = "clear_channel"

esphome/components/copy/lock/copy_lock.cpp

@@ -8,10 +8,7 @@ ESPHOME_LOG_TAG(TAG, "copy.lock");
 void CopyLock::setup() {
   source_->add_on_state_callback([this](lock::LockState state) { this->publish_state(state); });
 
-  traits.set_assumed_state(source_->traits.get_assumed_state());
-  traits.set_requires_code(source_->traits.get_requires_code());
-  traits.set_supported_states_mask(source_->traits.get_supported_states_mask());
-  traits.set_supports_open(source_->traits.get_supports_open());
+  this->traits = this->source_->traits;
 
   this->publish_state(source_->state);
 }

esphome/components/cover/cover_traits.h

@@ -1,31 +1,37 @@
 #pragma once
 
+#include <cstdint>
+
 namespace esphome::cover {
 
 class CoverTraits {
  public:
   CoverTraits() = default;
 
-  bool get_is_assumed_state() const { return this->is_assumed_state_; }
-  void set_is_assumed_state(bool is_assumed_state) { this->is_assumed_state_ = is_assumed_state; }
-  bool get_supports_position() const { return this->supports_position_; }
-  void set_supports_position(bool supports_position) { this->supports_position_ = supports_position; }
-  bool get_supports_tilt() const { return this->supports_tilt_; }
-  void set_supports_tilt(bool supports_tilt) { this->supports_tilt_ = supports_tilt; }
-  bool get_supports_toggle() const { return this->supports_toggle_; }
-  void set_supports_toggle(bool supports_toggle) { this->supports_toggle_ = supports_toggle; }
-  bool get_supports_stop() const { return this->supports_stop_; }
-  void set_supports_stop(bool supports_stop) { this->supports_stop_ = supports_stop; }
-  bool get_supports_stop_tilt() const { return this->supports_stop_tilt_; }
-  void set_supports_stop_tilt(bool supports_stop_tilt) { this->supports_stop_tilt_ = supports_stop_tilt; }
+  bool get_is_assumed_state() const { return this->flags_.is_assumed_state; }
+  void set_is_assumed_state(bool is_assumed_state) { this->flags_.is_assumed_state = is_assumed_state; }
+  bool get_supports_position() const { return this->flags_.supports_position; }
+  void set_supports_position(bool supports_position) { this->flags_.supports_position = supports_position; }
+  bool get_supports_tilt() const { return this->flags_.supports_tilt; }
+  void set_supports_tilt(bool supports_tilt) { this->flags_.supports_tilt = supports_tilt; }
+  bool get_supports_toggle() const { return this->flags_.supports_toggle; }
+  void set_supports_toggle(bool supports_toggle) { this->flags_.supports_toggle = supports_toggle; }
+  bool get_supports_stop() const { return this->flags_.supports_stop; }
+  void set_supports_stop(bool supports_stop) { this->flags_.supports_stop = supports_stop; }
+  bool get_supports_stop_tilt() const { return this->flags_.supports_stop_tilt; }
+  void set_supports_stop_tilt(bool supports_stop_tilt) { this->flags_.supports_stop_tilt = supports_stop_tilt; }
 
  protected:
-  bool is_assumed_state_{false};
-  bool supports_position_{false};
-  bool supports_tilt_{false};
-  bool supports_toggle_{false};
-  bool supports_stop_{false};
-  bool supports_stop_tilt_{false};
+  // Bit-packed flags to save memory (1 byte instead of 6)
+  struct CoverTraitFlags {
+    uint8_t is_assumed_state : 1;
+    uint8_t supports_position : 1;
+    uint8_t supports_tilt : 1;
+    uint8_t supports_toggle : 1;
+    uint8_t supports_stop : 1;
+    uint8_t supports_stop_tilt : 1;
+    uint8_t reserved : 2;
+  } flags_{};
 };
 
 }  // namespace esphome::cover

esphome/components/cw2017/__init__.py

@@ -0,0 +1,2 @@
+CODEOWNERS = ["@exciton"]
+DOMAIN = "cw2017"

esphome/components/cw2017/cw2017.cpp

@@ -0,0 +1,196 @@
+#include "cw2017.h"
+
+#include <cstring>
+
+#include "esphome/core/hal.h"
+#include "esphome/core/log.h"
+
+#ifdef USE_DEEP_SLEEP
+#include "esphome/components/deep_sleep/deep_sleep_component.h"
+#endif
+
+namespace esphome::cw2017 {
+
+ESPHOME_LOG_TAG(TAG, "cw2017");
+
+static constexpr uint8_t REG_VERSION = 0x00;
+static constexpr uint8_t REG_VCELL = 0x02;
+static constexpr uint8_t REG_SOC = 0x04;
+static constexpr uint8_t REG_MODE = 0x08;
+static constexpr uint8_t REG_SOC_ALERT = 0x0B;
+static constexpr uint8_t REG_BATINFO = 0x10;
+
+static constexpr uint8_t MODE_NORMAL = 0x00;
+static constexpr uint8_t MODE_SLEEP = 0x30;
+static constexpr uint8_t UPDATE_FLAG = 0x80;
+static constexpr uint8_t RESTART_MODES[] PROGMEM = {0xF0, MODE_SLEEP, MODE_NORMAL};
+static constexpr uint8_t RESTART_STEPS = sizeof(RESTART_MODES);
+
+static constexpr uint16_t VCELL_MASK = 0x3FFF;
+static constexpr float VCELL_VOLTS_PER_LSB = 312.5e-6f;
+
+static constexpr uint32_t STEP_DELAY_MS = 20;
+static constexpr uint32_t READY_POLL_MS = 100;
+static constexpr uint8_t READY_ATTEMPTS = 40;
+static constexpr uint32_t INIT_RETRY_MS = 1000;
+static constexpr uint8_t INIT_ATTEMPTS = 3;
+
+static bool version_is_running(uint8_t version) { return (version & 0xFD) == 0x0D; }
+
+// The configured profile only changes with new firmware, and flashing never ends in a deep-sleep wake.
+static bool woke_from_deep_sleep() {
+#ifdef USE_DEEP_SLEEP
+  return deep_sleep::woke_from_deep_sleep();
+#else
+  return false;
+#endif
+}
+
+bool CW2017::read_profile_matches_(bool &matches) {
+  uint8_t stored[PROFILE_SIZE];
+  uint8_t expected[PROFILE_SIZE];
+  if (!this->read_bytes(REG_BATINFO, stored, PROFILE_SIZE))
+    return false;
+  progmem_memcpy(expected, this->profile_, PROFILE_SIZE);
+  matches = std::memcmp(stored, expected, PROFILE_SIZE) == 0;
+  return true;
+}
+
+bool CW2017::upload_profile_() {
+  // Built here with the register first, so the bus layer does not heap-allocate a buffer this size.
+  uint8_t buffer[1 + PROFILE_SIZE] = {REG_BATINFO};
+  progmem_memcpy(buffer + 1, this->profile_, PROFILE_SIZE);
+  return this->write(buffer, sizeof(buffer)) == i2c::ERROR_OK && this->write_byte(REG_SOC_ALERT, UPDATE_FLAG);
+}
+
+void CW2017::setup() { this->init_(); }
+
+// Retried because another device resetting on the same bus can disturb an early transfer.
+void CW2017::init_failed_(const LogString *reason) {
+  if (++this->init_attempts_ >= INIT_ATTEMPTS) {
+    this->mark_failed(reason);
+    return;
+  }
+  this->set_timeout(INIT_RETRY_MS, [this]() { this->init_(); });
+}
+
+void CW2017::init_() {
+  // A profile upload only takes effect after a restart, so a failed restart is retried, not skipped.
+  if (this->restart_pending_) {
+    this->restart_();
+    return;
+  }
+
+  uint8_t mode = 0;
+  uint8_t version = 0;
+  uint8_t config = 0;
+  if (!this->read_byte(REG_MODE, &mode) || !this->read_byte(REG_VERSION, &version) ||
+      !this->read_byte(REG_SOC_ALERT, &config)) {
+    this->init_failed_(LOG_STR(ESP_LOG_MSG_COMM_FAIL));
+    return;
+  }
+  const bool has_profile = (config & UPDATE_FLAG) != 0;
+  bool matches = has_profile && woke_from_deep_sleep();
+  if (has_profile && !matches && !this->read_profile_matches_(matches)) {
+    this->init_failed_(LOG_STR(ESP_LOG_MSG_COMM_FAIL));
+    return;
+  }
+
+  if (!matches) {
+    ESP_LOGI(TAG, "Uploading battery profile");
+    if (!this->upload_profile_()) {
+      this->init_failed_(LOG_STR("Battery profile upload failed"));
+      return;
+    }
+    this->restart_();
+    return;
+  }
+
+  if (mode == MODE_SLEEP) {
+    // The gauge keeps its profile and state through its own sleep, so a wake is a mode write, not a restart.
+    if (!this->write_byte(REG_MODE, MODE_NORMAL)) {
+      this->init_failed_(LOG_STR("Gauge wake failed"));
+      return;
+    }
+    this->set_timeout(STEP_DELAY_MS, [this]() { this->wait_ready_(0); });
+    return;
+  }
+
+  if (mode != MODE_NORMAL || !version_is_running(version)) {
+    this->restart_();
+    return;
+  }
+
+  this->wait_ready_(0);
+}
+
+void CW2017::restart_() {
+  this->restart_pending_ = true;
+  this->set_timeout(STEP_DELAY_MS, [this]() { this->restart_step_(0); });
+}
+
+void CW2017::restart_step_(uint8_t step) {
+  if (!this->write_byte(REG_MODE, progmem_read_byte(&RESTART_MODES[step]))) {
+    this->init_failed_(LOG_STR("Restart failed"));
+    return;
+  }
+  if (step + 1 < RESTART_STEPS) {
+    this->set_timeout(STEP_DELAY_MS, [this, step]() { this->restart_step_(step + 1); });
+  } else {
+    this->restart_pending_ = false;
+    this->set_timeout(STEP_DELAY_MS, [this]() { this->wait_ready_(0); });
+  }
+}
+
+void CW2017::wait_ready_(uint8_t attempt) {
+  uint8_t version = 0;
+  uint8_t soc = 0;
+  if (this->read_byte(REG_VERSION, &version) && version_is_running(version) && this->read_byte(REG_SOC, &soc) &&
+      soc <= 100) {
+    ESP_LOGD(TAG, "Gauge ready %u ms after boot", (unsigned) millis());
+    this->ready_ = true;
+    this->update();
+    return;
+  }
+  if (attempt + 1 >= READY_ATTEMPTS) {
+    this->init_failed_(LOG_STR("Gauge did not become ready"));
+    return;
+  }
+  this->set_timeout(READY_POLL_MS, [this, attempt]() { this->wait_ready_(attempt + 1); });
+}
+
+void CW2017::update() {
+  if (!this->ready_)
+    return;
+
+  if (this->battery_level_sensor_ != nullptr) {
+    uint8_t soc = 0;
+    if (this->read_byte(REG_SOC, &soc) && soc <= 100) {
+      this->battery_level_sensor_->publish_state(soc);
+    } else {
+      this->status_set_warning();
+      return;
+    }
+  }
+
+  if (this->battery_voltage_sensor_ != nullptr) {
+    uint16_t raw = 0;
+    if (this->read_byte_16(REG_VCELL, &raw)) {
+      this->battery_voltage_sensor_->publish_state((raw & VCELL_MASK) * VCELL_VOLTS_PER_LSB);
+    } else {
+      this->status_set_warning();
+      return;
+    }
+  }
+  this->status_clear_warning();
+}
+
+void CW2017::dump_config() {
+  ESP_LOGCONFIG(TAG, "CW2017:");
+  LOG_I2C_DEVICE(this);
+  LOG_UPDATE_INTERVAL(this);
+  LOG_SENSOR("  ", "Battery Level", this->battery_level_sensor_);
+  LOG_SENSOR("  ", "Battery Voltage", this->battery_voltage_sensor_);
+}
+
+}  // namespace esphome::cw2017

esphome/components/cw2017/cw2017.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#include "esphome/components/i2c/i2c.h"
+#include "esphome/components/sensor/sensor.h"
+#include "esphome/core/component.h"
+
+namespace esphome::cw2017 {
+
+static constexpr uint8_t PROFILE_SIZE = 80;
+
+class CW2017 : public PollingComponent, public i2c::I2CDevice {
+ public:
+  explicit CW2017(const uint8_t *profile) : profile_(profile) {}
+
+  void set_battery_level_sensor(sensor::Sensor *sensor) { this->battery_level_sensor_ = sensor; }
+  void set_battery_voltage_sensor(sensor::Sensor *sensor) { this->battery_voltage_sensor_ = sensor; }
+
+  void setup() override;
+  void update() override;
+  void dump_config() override;
+
+ protected:
+  void init_();
+  void init_failed_(const LogString *reason);
+  bool read_profile_matches_(bool &matches);
+  bool upload_profile_();
+  void restart_();
+  void restart_step_(uint8_t step);
+  void wait_ready_(uint8_t attempt);
+
+  const uint8_t *profile_;
+  sensor::Sensor *battery_level_sensor_{nullptr};
+  sensor::Sensor *battery_voltage_sensor_{nullptr};
+  bool ready_{false};
+  bool restart_pending_{false};
+  uint8_t init_attempts_{0};
+};
+
+}  // namespace esphome::cw2017

esphome/components/cw2017/sensor.py

@@ -0,0 +1,61 @@
+import esphome.codegen as cg
+from esphome.components import i2c, sensor
+import esphome.config_validation as cv
+from esphome.const import (
+    CONF_BATTERY_LEVEL,
+    CONF_BATTERY_VOLTAGE,
+    CONF_RAW_DATA_ID,
+    DEVICE_CLASS_BATTERY,
+    DEVICE_CLASS_VOLTAGE,
+    ENTITY_CATEGORY_DIAGNOSTIC,
+    STATE_CLASS_MEASUREMENT,
+    UNIT_PERCENT,
+    UNIT_VOLT,
+)
+from esphome.types import ConfigType
+
+DEPENDENCIES = ["i2c"]
+
+CONF_BATTERY_PROFILE = "battery_profile"
+PROFILE_SIZE = 80
+
+cw2017_ns = cg.esphome_ns.namespace("cw2017")
+CW2017 = cw2017_ns.class_("CW2017", cg.PollingComponent, i2c.I2CDevice)
+
+CONFIG_SCHEMA = (
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.declare_id(CW2017),
+            cv.GenerateID(CONF_RAW_DATA_ID): cv.declare_id(cg.uint8),
+            cv.Required(CONF_BATTERY_PROFILE): cv.All(
+                cv.ensure_list(cv.hex_uint8_t),
+                cv.Length(min=PROFILE_SIZE, max=PROFILE_SIZE),
+            ),
+            cv.Optional(CONF_BATTERY_LEVEL): sensor.sensor_schema(
+                unit_of_measurement=UNIT_PERCENT,
+                accuracy_decimals=0,
+                device_class=DEVICE_CLASS_BATTERY,
+                state_class=STATE_CLASS_MEASUREMENT,
+                entity_category=ENTITY_CATEGORY_DIAGNOSTIC,
+            ),
+            cv.Optional(CONF_BATTERY_VOLTAGE): sensor.sensor_schema(
+                unit_of_measurement=UNIT_VOLT,
+                accuracy_decimals=3,
+                device_class=DEVICE_CLASS_VOLTAGE,
+                state_class=STATE_CLASS_MEASUREMENT,
+                entity_category=ENTITY_CATEGORY_DIAGNOSTIC,
+            ),
+        }
+    )
+    .extend(cv.polling_component_schema("60s"))
+    .extend(i2c.i2c_device_schema(0x63))
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    profile = cg.progmem_array(config[CONF_RAW_DATA_ID], config[CONF_BATTERY_PROFILE])
+    var = await i2c.new_i2c_component(config, profile)
+
+    sensors = sensor.sub_sensors(config)
+    await sensors(CONF_BATTERY_LEVEL, var.set_battery_level_sensor)
+    await sensors(CONF_BATTERY_VOLTAGE, var.set_battery_voltage_sensor)

esphome/components/dac7678/output.py

@@ -21,6 +21,11 @@ CONFIG_SCHEMA = output.FLOAT_OUTPUT_SCHEMA.extend(
 )
 
 
+FINAL_VALIDATE_SCHEMA = output.final_validate_unique_channel(
+    platform="dac7678", hub_key=CONF_DAC7678_ID
+)
+
+
 async def to_code(config: ConfigType) -> MockObj:
     paren = await cg.get_variable(config[CONF_DAC7678_ID])
     var = cg.new_Pvariable(config[CONF_ID])

esphome/components/deep_sleep/deep_sleep_bk72xx.cpp

@@ -7,7 +7,6 @@ namespace esphome::deep_sleep {
 
 ESPHOME_LOG_TAG(TAG, "deep_sleep");
 
-#ifdef USE_DEEP_SLEEP_ON_WAKE
 WakeupCause get_wakeup_cause() {
   switch (lt_get_reboot_reason()) {
     case REBOOT_REASON_SLEEP_GPIO:
@@ -20,7 +19,6 @@ WakeupCause get_wakeup_cause() {
       return WAKEUP_CAUSE_NONE;
   }
 }
-#endif  // USE_DEEP_SLEEP_ON_WAKE
 
 optional<uint32_t> DeepSleepComponent::get_run_duration_() const { return this->run_duration_; }
 

esphome/components/deep_sleep/deep_sleep_component.h

@@ -60,8 +60,6 @@ struct WakeupCauseToRunDuration {
 
 #endif  // USE_ESP32
 
-#ifdef USE_DEEP_SLEEP_ON_WAKE
-
 /// Why the device woke from deep sleep. Passed to on_wake automations.
 enum WakeupCause : uint8_t {
   /// The device did not wake from deep sleep (for example a cold boot, reset or OTA restart).
@@ -79,6 +77,11 @@ enum WakeupCause : uint8_t {
 /// Return why the device woke from deep sleep. Implemented per platform.
 WakeupCause get_wakeup_cause();
 
+/// Return true when this boot is a wake from deep sleep.
+inline bool woke_from_deep_sleep() { return get_wakeup_cause() != WAKEUP_CAUSE_NONE; }
+
+#ifdef USE_DEEP_SLEEP_ON_WAKE
+
 /** Setup priority of on_wake triggers.
  *
  * Between restoring global variables (setup_priority::HARDWARE, 800) and on_boot automations at

esphome/components/deep_sleep/deep_sleep_esp32.cpp

@@ -30,7 +30,6 @@ namespace esphome::deep_sleep {
 
 ESPHOME_LOG_TAG(TAG, "deep_sleep");
 
-#ifdef USE_DEEP_SLEEP_ON_WAKE
 WakeupCause get_wakeup_cause() {
   switch (esp_sleep_get_wakeup_cause()) {
     case ESP_SLEEP_WAKEUP_EXT0:
@@ -47,7 +46,6 @@ WakeupCause get_wakeup_cause() {
       return WAKEUP_CAUSE_UNKNOWN;
   }
 }
-#endif  // USE_DEEP_SLEEP_ON_WAKE
 
 optional<uint32_t> DeepSleepComponent::get_run_duration_() const {
   if (this->wakeup_cause_to_run_duration_.has_value()) {

esphome/components/deep_sleep/deep_sleep_esp8266.cpp

@@ -3,17 +3,14 @@
 
 #include <Esp.h>
 
-#ifdef USE_DEEP_SLEEP_ON_WAKE
 extern "C" {
 #include <user_interface.h>
 }
-#endif
 
 namespace esphome::deep_sleep {
 
 ESPHOME_LOG_TAG(TAG, "deep_sleep");
 
-#ifdef USE_DEEP_SLEEP_ON_WAKE
 WakeupCause get_wakeup_cause() {
   // The ESP8266 can only wake from deep sleep through the RTC timer (via GPIO16 -> RST).
   // NOLINTNEXTLINE(readability-static-accessed-through-instance)
@@ -22,7 +19,6 @@ WakeupCause get_wakeup_cause() {
   }
   return WAKEUP_CAUSE_NONE;
 }
-#endif  // USE_DEEP_SLEEP_ON_WAKE
 
 optional<uint32_t> DeepSleepComponent::get_run_duration_() const { return this->run_duration_; }
 

esphome/components/deep_sleep/deep_sleep_zephyr.cpp

@@ -31,6 +31,9 @@ static bool wakeable_delay_feed_wdt(uint32_t ms) {
   return false;
 }
 
+// A wake from System OFF is not told apart from a reset yet.
+WakeupCause get_wakeup_cause() { return WAKEUP_CAUSE_NONE; }
+
 optional<uint32_t> DeepSleepComponent::get_run_duration_() const { return this->run_duration_; }
 
 void DeepSleepComponent::dump_config_platform_() {}

esphome/components/delta_wallbox/__init__.py

@@ -0,0 +1,42 @@
+import esphome.codegen as cg
+from esphome.components import ble_client, time
+import esphome.config_validation as cv
+from esphome.const import CONF_PASSWORD, CONF_PIN, CONF_TIME_ID
+from esphome.types import ConfigType
+
+CODEOWNERS = ["@epicRE"]
+DEPENDENCIES = ["ble_client"]
+DOMAIN = "delta_wallbox"
+MULTI_CONF = True
+
+CONF_DELTA_WALLBOX_ID = "delta_wallbox_id"
+CONF_USER = "user"
+
+delta_wallbox_ns = cg.esphome_ns.namespace("delta_wallbox")
+DeltaWallbox = delta_wallbox_ns.class_(
+    "DeltaWallbox", ble_client.BLEClientNode, cg.PollingComponent
+)
+
+CONFIG_SCHEMA = (
+    cv.COMPONENT_SCHEMA.extend(
+        {
+            cv.GenerateID(): cv.declare_id(DeltaWallbox),
+            cv.Required(CONF_PASSWORD): cv.All(cv.string_strict, cv.Length(max=22)),
+            cv.Optional(CONF_PIN): cv.int_range(min=0, max=999999),
+            cv.Optional(CONF_USER, default="admin"): cv.All(
+                cv.string_strict, cv.Length(max=6)
+            ),
+            cv.Optional(CONF_TIME_ID): cv.use_id(time.RealTimeClock),
+        }
+    )
+    .extend(ble_client.BLE_CLIENT_SCHEMA)
+    .extend(cv.polling_component_schema("15s"))
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    var = await ble_client.new_ble_node_component(
+        config, config[CONF_USER], config[CONF_PASSWORD]
+    )
+    cg.add_optional(var.set_pin, config.get(CONF_PIN))
+    await cg.add_variable(var.set_time_id, config.get(CONF_TIME_ID))

esphome/components/delta_wallbox/button.py

@@ -0,0 +1,30 @@
+from esphome.components import button
+import esphome.config_validation as cv
+from esphome.types import ConfigType
+
+from . import CONF_DELTA_WALLBOX_ID, DeltaWallbox
+
+DEPENDENCIES = ["delta_wallbox"]
+
+CONF_START_CHARGING = "start_charging"
+CONF_STOP_CHARGING = "stop_charging"
+
+CONFIG_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(CONF_DELTA_WALLBOX_ID): cv.use_id(DeltaWallbox),
+        cv.Optional(CONF_START_CHARGING): button.button_schema(
+            button.ApplyButton,
+            icon="mdi:play-circle-outline",
+        ),
+        cv.Optional(CONF_STOP_CHARGING): button.button_schema(
+            button.ApplyButton,
+            icon="mdi:stop-circle-outline",
+        ),
+    }
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    buttons = button.sub_buttons(config, parent=config[CONF_DELTA_WALLBOX_ID])
+    await buttons(CONF_START_CHARGING, None, apply="start_charging()")
+    await buttons(CONF_STOP_CHARGING, None, apply="stop_charging()")

esphome/components/delta_wallbox/delta_wallbox.cpp

@@ -0,0 +1,691 @@
+#include "delta_wallbox.h"
+#include "esphome/core/log.h"
+#include "esphome/core/progmem.h"
+#include <algorithm>
+#include <array>
+#include <cctype>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+
+#ifdef USE_ESP32
+
+namespace esphome::delta_wallbox {
+ESPHOME_LOG_TAG(TAG, "delta_wallbox");
+// Modbus function codes
+static constexpr uint8_t FC_READ_HOLDING_REGISTERS = 0x03;
+static constexpr uint8_t FC_WRITE_SINGLE_REGISTER = 0x06;
+static constexpr uint8_t FC_WRITE_MULTIPLE_REGISTERS = 0x10;
+static constexpr uint8_t FC_EXCEPTION_FLAG = 0x80;
+
+// Response lengths in bytes, CRC included
+static constexpr size_t READ_RESPONSE_OVERHEAD = 5;
+static constexpr size_t WRITE_RESPONSE_LEN = 8;
+static constexpr size_t EXCEPTION_RESPONSE_LEN = 5;
+
+// Frame bodies without CRC
+static constexpr size_t LOGIN_BODY_LEN = 35;
+static constexpr size_t LOGIN_PASS_LEN = 22;
+static constexpr size_t LOGIN_USER_LEN = 6;
+static constexpr size_t TIME_SYNC_BODY_LEN = 15;
+
+static constexpr uint8_t REGISTER_BYTE_COUNT = 2;
+static constexpr uint8_t TWO_REGISTER_BYTE_COUNT = 4;
+static constexpr uint8_t CHARGING_INFO_BYTE_COUNT = 18;
+static constexpr uint8_t SERIAL_TEXT_BYTE_COUNT = 14;
+static constexpr uint32_t RETRANSMIT_TIMEOUT_MS = 4000;
+static constexpr uint32_t RETRANSMIT_TIMEOUT_ID = 0;
+static constexpr uint8_t MAX_PAIRING_ATTEMPTS = 5;
+static constexpr uint16_t PAIRING_STATUS_READY = 0x0007;
+static constexpr uint16_t PAIRING_STATUS_WAITING = 0x0008;
+static constexpr uint8_t LOGIN_ACCEPTED = 0x01;
+
+static constexpr uint8_t CMD_POLL_CHARGING[] = {0x01, 0x03, 0x01, 0x1B, 0x00, 0x09};
+static constexpr uint8_t CMD_GET_MODEL[] = {0x01, 0x03, 0x01, 0x85, 0x00, 0x0E};
+static constexpr uint8_t CMD_GET_BT_FW_VERSION[] = {0x02, 0x03, 0x01, 0x00, 0x00, 0x01};
+static constexpr uint8_t CMD_CHECK_PAIRING[] = {0x02, 0x03, 0x01, 0x00, 0x00, 0x03};
+static constexpr uint8_t CMD_GET_LOGIN_USER[] = {0x01, 0x03, 0x01, 0x7D, 0x00, 0x03};
+static constexpr uint8_t CMD_READ_LOGIN_STATUS[] = {0x01, 0x03, 0x01, 0x80, 0x00, 0x01};
+static constexpr uint8_t CMD_GET_LOGIN_ROLE[] = {0x01, 0x03, 0x01, 0x81, 0x00, 0x01};
+static constexpr uint8_t CMD_GET_CHARGER_FW_VERSION[] = {0x01, 0x03, 0x01, 0x10, 0x00, 0x02};
+static constexpr uint8_t CMD_GET_MAX_CURRENT[] = {0x01, 0x03, 0x01, 0x12, 0x00, 0x02};
+static constexpr uint8_t CMD_GET_SERIAL_NUMBER[] = {0x01, 0x03, 0x01, 0x09, 0x00, 0x01};
+static constexpr uint8_t CMD_GET_ERROR_CODE[] = {0x01, 0x03, 0x01, 0xB5, 0x00, 0x01};
+static constexpr uint8_t CMD_START_CHARGING[] = {0x01, 0x06, 0x01, 0x02, 0x00, 0x01};
+static constexpr uint8_t CMD_STOP_CHARGING[] = {0x01, 0x06, 0x01, 0x03, 0x00, 0x01};
+
+// Indexed by DeltaState
+PROGMEM_STRING_TABLE(DeltaStateStrings, "CHECK_PAIRING", "CONNECTED", "GET_CHARGER_FW_VERSION", "GET_BT_FW_VERSION",
+                     "GET_LOGIN_RESULT", "GET_LOGIN_RESULT0", "GET_LOGIN_ROLE", "GET_LOGIN_USER", "GET_MODEL",
+                     "GET_SERIAL_NUMBER", "HALTED", "IDLE", "SEND_LOGIN_CREDENTIALS", "TIME_SYNC");
+static_assert(DeltaStateStrings::LAST_INDEX == static_cast<uint8_t>(DeltaState::DELTA_STATE_TIME_SYNC),
+              "DeltaStateStrings must list every DeltaState");
+static const LogString *delta_state_to_string(DeltaState state) {
+  return DeltaStateStrings::get_log_str(static_cast<uint8_t>(state), DeltaStateStrings::LAST_INDEX);
+}
+
+// The function code a handshake step waits for; 0 where any frame is handled
+static uint8_t expected_function_code(DeltaState state) {
+  switch (state) {
+    case DeltaState::DELTA_STATE_IDLE:
+    case DeltaState::DELTA_STATE_HALTED:
+    case DeltaState::DELTA_STATE_CONNECTED:
+      return 0;
+    case DeltaState::DELTA_STATE_SEND_LOGIN_CREDENTIALS:
+    case DeltaState::DELTA_STATE_TIME_SYNC:
+      return FC_WRITE_MULTIPLE_REGISTERS;
+    default:
+      return FC_READ_HOLDING_REGISTERS;
+  }
+}
+
+// UUID references
+static const esp32_ble_tracker::ESPBTUUID SERVICE_UUID =
+    esp32_ble_tracker::ESPBTUUID::from_raw("6e400001-b5a3-f393-e0a9-e50e24dcca9e");
+static const esp32_ble_tracker::ESPBTUUID TX_UUID =
+    esp32_ble_tracker::ESPBTUUID::from_raw("6e400002-b5a3-f393-e0a9-e50e24dcca9e");
+static const esp32_ble_tracker::ESPBTUUID RX_UUID =
+    esp32_ble_tracker::ESPBTUUID::from_raw("6e400003-b5a3-f393-e0a9-e50e24dcca9e");
+
+// Appends the little-endian Modbus CRC-16 to the len bytes in frame and returns the new length.
+static size_t append_crc(uint8_t *frame, size_t len) {
+  const uint16_t crc = crc16(frame, static_cast<uint16_t>(len));
+  frame[len] = static_cast<uint8_t>(crc & 0xFF);
+  frame[len + 1] = static_cast<uint8_t>(crc >> 8);
+  return len + 2;
+}
+
+static bool verify_crc(const uint8_t *data, size_t len) {
+  if (len < EXCEPTION_RESPONSE_LEN)
+    return false;
+  const uint16_t calculated = crc16(data, static_cast<uint16_t>(len - 2));
+  const uint16_t received = data[len - 2] | (data[len - 1] << 8);
+  return calculated == received;
+}
+
+// Login write body: 22-byte password and 6-byte user, both left-padded with zeros
+static std::array<uint8_t, LOGIN_BODY_LEN> build_login_body(StringRef user, StringRef password) {
+  std::array<uint8_t, LOGIN_BODY_LEN> frame = {
+      0x01, 0x10, 0x01, 0x72, 0x00, 0x0E, 0x1C,  // Unit, FC16, register 0x0172, 14 registers, 28 bytes
+  };
+
+  const size_t pass_len = std::min(password.size(), LOGIN_PASS_LEN);
+  std::copy_n(password.c_str(), pass_len, frame.begin() + 7 + (LOGIN_PASS_LEN - pass_len));
+
+  uint8_t *user_chunk = frame.data() + 7 + LOGIN_PASS_LEN;
+  bool is_digit = !user.empty();
+  for (size_t i = 0; i < user.size() && is_digit; i++) {
+    is_digit = isdigit(static_cast<unsigned char>(user.c_str()[i]));
+  }
+  if (is_digit) {
+    const uint64_t val = strtoull(user.c_str(), nullptr, 10);
+    for (size_t i = 0; i < LOGIN_USER_LEN; i++) {
+      user_chunk[LOGIN_USER_LEN - 1 - i] = static_cast<uint8_t>((val >> (8 * i)) & 0xFF);
+    }
+  } else {
+    const size_t user_len = std::min(user.size(), LOGIN_USER_LEN);
+    std::copy_n(user.c_str(), user_len, user_chunk + LOGIN_USER_LEN - user_len);
+  }
+  return frame;
+}
+
+static std::array<uint8_t, TIME_SYNC_BODY_LEN> build_time_sync_body(int year, int month, int day, int hour, int minute,
+                                                                    int second, int weekday) {
+  const uint8_t weekday_bitmap = static_cast<uint8_t>(1 << weekday);  // Sunday=bit0, Mon=bit1...
+  return {
+      0x01,
+      0x10,
+      0x01,
+      0x14,
+      0x00,
+      0x04,
+      0x08,  // Unit, FC16, register 0x0114, 4 registers, 8 bytes
+      static_cast<uint8_t>(year % 100),
+      static_cast<uint8_t>(month),
+      weekday_bitmap,
+      static_cast<uint8_t>(day),
+      static_cast<uint8_t>(hour),
+      static_cast<uint8_t>(minute),
+      static_cast<uint8_t>(second),
+      0x00,
+  };
+}
+
+void DeltaWallbox::dump_config() {
+  ESP_LOGCONFIG(TAG, "Delta Wallbox:");
+  ESP_LOGCONFIG(TAG, "  User: %s", this->user_.c_str());
+  ESP_LOGCONFIG(TAG, "  BLE PIN configured: %s", this->has_pin_ ? LOG_STR_LITERAL("YES") : LOG_STR_LITERAL("NO"));
+  LOG_UPDATE_INTERVAL(this);
+}
+
+void DeltaWallbox::update() {
+  if (this->is_connected()) {
+    // Start poll flow sequence
+    ESP_LOGD(TAG, "Polling charging info...");
+    this->send_frame_(CMD_POLL_CHARGING, sizeof(CMD_POLL_CHARGING));
+  }
+}
+
+void DeltaWallbox::write_frame_(const uint8_t *frame, size_t len) {
+  if (this->tx_char_handle_ == 0) {
+    ESP_LOGW(TAG, "TX characteristic handle is not ready while in state %s. Dropping %u-byte frame.",
+             LOG_STR_ARG(delta_state_to_string(this->state_)), (unsigned int) len);
+    return;
+  }
+  ESP_LOGD(TAG, "Sending %u-byte frame in state %s (conn_id=%u, tx_handle=0x%04X).", (unsigned int) len,
+           LOG_STR_ARG(delta_state_to_string(this->state_)), this->parent_->get_conn_id(), this->tx_char_handle_);
+  auto status =
+      esp_ble_gattc_write_char(this->parent_->get_gattc_if(), this->parent_->get_conn_id(), this->tx_char_handle_, len,
+                               const_cast<uint8_t *>(frame), ESP_GATT_WRITE_TYPE_NO_RSP, ESP_GATT_AUTH_REQ_NONE);
+  if (status != ESP_GATT_OK) {
+    ESP_LOGW(TAG, "esp_ble_gattc_write_char failed, status=%d", status);
+  }
+}
+
+// Copies body into a stack buffer, appends the CRC and writes the frame.
+void DeltaWallbox::send_frame_(const uint8_t *body, size_t len) {
+  std::array<uint8_t, MAX_FRAME_LEN> frame{};
+  std::copy_n(body, len, frame.begin());
+  this->write_frame_(frame.data(), append_crc(frame.data(), len));
+}
+
+void DeltaWallbox::drop_rx_bytes_(size_t count) {
+  count = std::min(count, this->rx_len_);
+  std::memmove(this->rx_buffer_.data(), this->rx_buffer_.data() + count, this->rx_len_ - count);
+  this->rx_len_ -= count;
+}
+
+void DeltaWallbox::send_next_state_command_() {
+  ESP_LOGD(TAG, "Preparing command for state %s.", LOG_STR_ARG(delta_state_to_string(this->state_)));
+  switch (this->state_) {
+    case DeltaState::DELTA_STATE_GET_MODEL:
+      ESP_LOGI(TAG, "Requesting charger model name...");
+      this->send_frame_(CMD_GET_MODEL, sizeof(CMD_GET_MODEL));
+      break;
+    case DeltaState::DELTA_STATE_GET_BT_FW_VERSION:
+      ESP_LOGI(TAG, "Requesting BT firmware version...");
+      this->send_frame_(CMD_GET_BT_FW_VERSION, sizeof(CMD_GET_BT_FW_VERSION));
+      break;
+    case DeltaState::DELTA_STATE_CHECK_PAIRING:
+      ESP_LOGI(TAG, "Checking pairing status...");
+      this->send_frame_(CMD_CHECK_PAIRING, sizeof(CMD_CHECK_PAIRING));
+      break;
+    case DeltaState::DELTA_STATE_GET_LOGIN_USER:
+      ESP_LOGI(TAG, "Querying user profile...");
+      this->send_frame_(CMD_GET_LOGIN_USER, sizeof(CMD_GET_LOGIN_USER));
+      break;
+    case DeltaState::DELTA_STATE_GET_LOGIN_RESULT0:
+      ESP_LOGI(TAG, "Checking pre-login status register...");
+      this->send_frame_(CMD_READ_LOGIN_STATUS, sizeof(CMD_READ_LOGIN_STATUS));
+      break;
+    case DeltaState::DELTA_STATE_SEND_LOGIN_CREDENTIALS: {
+      ESP_LOGI(TAG, "Transmitting login credentials...");
+      const auto body = build_login_body(this->user_, this->password_);
+      this->send_frame_(body.data(), body.size());
+      break;
+    }
+    case DeltaState::DELTA_STATE_GET_LOGIN_RESULT:
+      ESP_LOGI(TAG, "Verifying login result...");
+      this->send_frame_(CMD_READ_LOGIN_STATUS, sizeof(CMD_READ_LOGIN_STATUS));
+      break;
+    case DeltaState::DELTA_STATE_GET_LOGIN_ROLE:
+      ESP_LOGI(TAG, "Checking role privileges...");
+      this->send_frame_(CMD_GET_LOGIN_ROLE, sizeof(CMD_GET_LOGIN_ROLE));
+      break;
+    case DeltaState::DELTA_STATE_TIME_SYNC: {
+#ifdef USE_TIME
+      // Only a valid time is written; the charger keeps its own clock otherwise
+      if (this->time_id_ != nullptr) {
+        auto tm = this->time_id_->now();
+        if (tm.is_valid()) {
+          ESP_LOGI(TAG, "Synchronizing wallbox clock...");
+          // ESPTime day_of_week is 1 (Sunday) to 7 (Saturday); the charger counts from 0
+          const auto body = build_time_sync_body(tm.year, tm.month, tm.day_of_month, tm.hour, tm.minute, tm.second,
+                                                 tm.day_of_week - 1);
+          this->send_frame_(body.data(), body.size());
+          break;
+        }
+      }
+#endif
+      this->advance_to_(DeltaState::DELTA_STATE_GET_CHARGER_FW_VERSION);
+      break;
+    }
+    case DeltaState::DELTA_STATE_GET_CHARGER_FW_VERSION:
+      ESP_LOGI(TAG, "Requesting charger main firmware version...");
+      this->send_frame_(CMD_GET_CHARGER_FW_VERSION, sizeof(CMD_GET_CHARGER_FW_VERSION));
+      break;
+    case DeltaState::DELTA_STATE_GET_SERIAL_NUMBER:
+      ESP_LOGI(TAG, "Requesting wallbox serial number...");
+      this->send_frame_(CMD_GET_SERIAL_NUMBER, sizeof(CMD_GET_SERIAL_NUMBER));
+      break;
+    default:
+      this->cancel_timeout(RETRANSMIT_TIMEOUT_ID);
+      return;
+  }
+  this->set_timeout(RETRANSMIT_TIMEOUT_ID, RETRANSMIT_TIMEOUT_MS, [this]() { this->retransmit_(); });
+}
+
+void DeltaWallbox::retransmit_() {
+  ESP_LOGW(TAG, "No answer in login state %s within %u ms. Sending the command again...",
+           LOG_STR_ARG(delta_state_to_string(this->state_)), (unsigned int) RETRANSMIT_TIMEOUT_MS);
+  this->send_next_state_command_();
+}
+
+void DeltaWallbox::advance_to_(DeltaState next) {
+  ESP_LOGD(TAG, "State transition: %s -> %s", LOG_STR_ARG(delta_state_to_string(this->state_)),
+           LOG_STR_ARG(delta_state_to_string(next)));
+  this->state_ = next;
+  this->send_next_state_command_();
+}
+
+void DeltaWallbox::handle_frame_(const uint8_t *frame, size_t len) {
+  ESP_LOGD(TAG, "Received valid frame in state %s: func=0x%02X len=%u",
+           LOG_STR_ARG(delta_state_to_string(this->state_)), frame[1], (unsigned int) len);
+  if (frame[1] & FC_EXCEPTION_FLAG) {
+    ESP_LOGE(TAG, "Modbus exception received in state %s! Error code: 0x%02X",
+             LOG_STR_ARG(delta_state_to_string(this->state_)), frame[2]);
+    if (this->state_ == DeltaState::DELTA_STATE_TIME_SYNC) {
+      // The clock write is optional, so a charger that refuses it is used without it
+      ESP_LOGW(TAG, "Charger refused the clock sync; continuing without it");
+      this->advance_to_(DeltaState::DELTA_STATE_GET_CHARGER_FW_VERSION);
+    } else if (expected_function_code(this->state_) != 0) {
+      // The charger refused a handshake step; sending the same request again would not change that
+      this->halt_(LOG_STR("Modbus exception during login"));
+    }
+    return;
+  }
+  const uint8_t expected = expected_function_code(this->state_);
+  if (expected != 0 && frame[1] != expected) {
+    // A late answer to a retransmitted request; the pending one is answered or sent again by the timer
+    ESP_LOGD(TAG, "Ignoring func=0x%02X reply while waiting for 0x%02X", frame[1], expected);
+    return;
+  }
+
+  switch (this->state_) {
+    case DeltaState::DELTA_STATE_IDLE:
+      break;  // No command is pending; ignore the frame.
+    case DeltaState::DELTA_STATE_GET_MODEL: {
+      char model[MAX_FRAME_LEN];
+      const size_t data_len = std::min<size_t>(frame[2], len - READ_RESPONSE_OVERHEAD);
+      size_t model_len = 0;
+      for (size_t i = 0; i < data_len; i++) {
+        if (frame[3 + i] != '\0')
+          model[model_len++] = static_cast<char>(frame[3 + i]);
+      }
+      model[model_len] = '\0';
+      ESP_LOGI(TAG, "Discovered Wallbox Model Name: %s", model);
+      if (this->model_name_text_sensor_ != nullptr) {
+        this->model_name_text_sensor_->publish_state(model);
+      }
+      this->advance_to_(DeltaState::DELTA_STATE_GET_BT_FW_VERSION);
+      break;
+    }
+    case DeltaState::DELTA_STATE_GET_BT_FW_VERSION: {
+      if (frame[2] >= REGISTER_BYTE_COUNT) {
+        uint8_t major = frame[3] % 16;
+        uint8_t minor = frame[4];
+        char ver[16];
+        snprintf(ver, sizeof(ver), "%d.%d", major, minor);
+        ESP_LOGI(TAG, "Discovered Wallbox BT FW: %s", ver);
+        if (this->bt_fw_version_text_sensor_ != nullptr) {
+          this->bt_fw_version_text_sensor_->publish_state(ver);
+        }
+      }
+      this->advance_to_(DeltaState::DELTA_STATE_CHECK_PAIRING);
+      break;
+    }
+    case DeltaState::DELTA_STATE_CHECK_PAIRING: {
+      if (frame[2] >= REGISTER_BYTE_COUNT) {
+        uint16_t status = (frame[3] << 8) | frame[4];
+        ESP_LOGI(TAG, "Pairing Status Register: 0x%04X", status);
+        if (status == PAIRING_STATUS_READY) {
+          this->pairing_in_progress_ = false;
+          this->pairing_attempts_ = 0;
+          ESP_LOGI(TAG, "Pairing ready and confirmed!");
+          this->advance_to_(DeltaState::DELTA_STATE_GET_LOGIN_USER);
+        } else if (status == PAIRING_STATUS_WAITING) {
+          ESP_LOGW(TAG, "Wallbox is waiting to be paired by the system controller (attempt %u, in_progress=%s).",
+                   this->pairing_attempts_ + 1,
+                   this->pairing_in_progress_ ? LOG_STR_LITERAL("YES") : LOG_STR_LITERAL("NO"));
+          this->pairing_attempts_++;
+          if (!this->pairing_in_progress_) {
+            ESP_LOGI(TAG, "Initiating BLE pairing with wallbox.");
+            auto err = this->parent_->pair();
+            if (err != ESP_OK) {
+              ESP_LOGW(TAG, "Failed to initiate BLE pairing, err=%d", err);
+            } else {
+              this->pairing_in_progress_ = true;
+            }
+          }
+        } else {
+          ESP_LOGW(TAG, "Unexpected pairing status 0x%04X", status);
+          this->pairing_attempts_++;
+        }
+        if (this->pairing_attempts_ >= MAX_PAIRING_ATTEMPTS) {
+          this->halt_(LOG_STR("Too many failed/waiting pairing checks"));
+        }
+      } else {
+        ESP_LOGW(TAG, "Pairing status response too short: byte_count=%u frame_len=%u", frame[2], (unsigned int) len);
+      }
+      break;
+    }
+    case DeltaState::DELTA_STATE_GET_LOGIN_USER: {
+      this->advance_to_(DeltaState::DELTA_STATE_GET_LOGIN_RESULT0);
+      break;
+    }
+    case DeltaState::DELTA_STATE_GET_LOGIN_RESULT0: {
+      if (frame[2] == REGISTER_BYTE_COUNT) {
+        this->advance_to_(DeltaState::DELTA_STATE_SEND_LOGIN_CREDENTIALS);
+      }
+      break;
+    }
+    case DeltaState::DELTA_STATE_SEND_LOGIN_CREDENTIALS: {
+      this->advance_to_(DeltaState::DELTA_STATE_GET_LOGIN_RESULT);
+      break;
+    }
+    case DeltaState::DELTA_STATE_GET_LOGIN_RESULT: {
+      // Only the one-register status answer counts; a late reply to another read has a different length
+      if (frame[2] == REGISTER_BYTE_COUNT) {
+        uint8_t login_val = frame[4];  // respondent data_lo
+        if (login_val == LOGIN_ACCEPTED) {
+          ESP_LOGI(TAG, "Credentials accepted! Logged in as %s.", this->user_.c_str());
+          this->advance_to_(DeltaState::DELTA_STATE_GET_LOGIN_ROLE);
+        } else {
+          ESP_LOGE(TAG, "Login validation failed (0x%02X). Check password.", login_val);
+          this->halt_(LOG_STR("Bad credentials"));
+        }
+      }
+      break;
+    }
+    case DeltaState::DELTA_STATE_HALTED: {
+      break;  // Authentication is halted; ignore any late replies.
+    }
+    case DeltaState::DELTA_STATE_GET_LOGIN_ROLE: {
+      if (frame[2] == REGISTER_BYTE_COUNT) {
+        this->advance_to_(DeltaState::DELTA_STATE_TIME_SYNC);
+      }
+      break;
+    }
+    case DeltaState::DELTA_STATE_TIME_SYNC: {
+      this->advance_to_(DeltaState::DELTA_STATE_GET_CHARGER_FW_VERSION);
+      break;
+    }
+    case DeltaState::DELTA_STATE_GET_CHARGER_FW_VERSION: {
+      if (frame[2] >= TWO_REGISTER_BYTE_COUNT) {
+        char ver[16];
+        snprintf(ver, sizeof(ver), "%d.%d", frame[3], frame[4]);
+        ESP_LOGI(TAG, "Discovered Charger Main FW: %s", ver);
+        if (this->fw_version_text_sensor_ != nullptr) {
+          this->fw_version_text_sensor_->publish_state(ver);
+        }
+      }
+      this->advance_to_(DeltaState::DELTA_STATE_GET_SERIAL_NUMBER);
+      break;
+    }
+    case DeltaState::DELTA_STATE_GET_SERIAL_NUMBER: {
+      // Serial read (0x0109) returns 14 ASCII bytes instead of one register
+      if (frame[2] >= SERIAL_TEXT_BYTE_COUNT) {
+        char serial[SERIAL_TEXT_BYTE_COUNT + 1];
+        size_t serial_len = 0;
+        for (size_t i = 0; i < SERIAL_TEXT_BYTE_COUNT; i++) {
+          if (frame[3 + i] != '\0')
+            serial[serial_len++] = static_cast<char>(frame[3 + i]);
+        }
+        serial[serial_len] = '\0';
+        ESP_LOGI(TAG, "Wallbox serial text: %s", serial);
+        if (this->serial_number_text_sensor_ != nullptr)
+          this->serial_number_text_sensor_->publish_state(serial);
+      }
+      this->advance_to_(DeltaState::DELTA_STATE_CONNECTED);
+      ESP_LOGI(TAG, "Authentication complete. Core parameters loaded.");
+      this->status_clear_warning();
+      this->update();  // perform first poll update immediately
+      break;
+    }
+    case DeltaState::DELTA_STATE_CONNECTED: {
+      // Connected polling responses
+      if (frame[1] == FC_READ_HOLDING_REGISTERS) {
+        uint8_t byte_count = frame[2];
+        if (byte_count == CHARGING_INFO_BYTE_COUNT) {
+          // Parsing 0x011B charging info (9 registers)
+          uint32_t power_raw = (frame[3] << 24) | (frame[4] << 16) | (frame[5] << 8) | frame[6];
+          uint32_t energy_raw = (frame[7] << 24) | (frame[8] << 16) | (frame[9] << 8) | frame[10];
+          uint8_t minutes = frame[15];
+          uint8_t hours = frame[16];
+          uint8_t state_byte = frame[17];
+
+          float power_kw = power_raw / 1000.0f;
+          float energy_kwh = energy_raw / 1000.0f;
+          float charging_minutes = hours * 60 + minutes;
+
+          if (this->power_sensor_ != nullptr)
+            this->power_sensor_->publish_state(power_kw);
+          if (this->energy_sensor_ != nullptr)
+            this->energy_sensor_->publish_state(energy_kwh);
+          if (this->charging_time_sensor_ != nullptr)
+            this->charging_time_sensor_->publish_state(charging_minutes);
+          if (this->charger_state_sensor_ != nullptr)
+            this->charger_state_sensor_->publish_state(state_byte);
+
+          // Retrieve maximum current output setting next
+          this->send_frame_(CMD_GET_MAX_CURRENT, sizeof(CMD_GET_MAX_CURRENT));
+        } else if (byte_count == TWO_REGISTER_BYTE_COUNT) {
+          // Parsing 0x0112 max output setting (2 registers)
+          uint32_t current_raw = (frame[3] << 24) | (frame[4] << 16) | (frame[5] << 8) | frame[6];
+          float amps = current_raw / 10.0f;
+          if (this->max_current_sensor_ != nullptr) {
+            this->max_current_sensor_->publish_state(amps);
+          }
+
+          // Poll the error code register every cycle
+          this->send_frame_(CMD_GET_ERROR_CODE, sizeof(CMD_GET_ERROR_CODE));
+        } else if (byte_count == REGISTER_BYTE_COUNT) {
+          // Error status register (0x01B5)
+          uint16_t reg_val = (frame[3] << 8) | frame[4];
+          char hex_str[16];
+          snprintf(hex_str, sizeof(hex_str), "%04X", reg_val);
+          if (this->error_code_text_sensor_ != nullptr)
+            this->error_code_text_sensor_->publish_state(hex_str);
+        }
+      } else if (frame[1] == FC_WRITE_SINGLE_REGISTER) {
+        // Confirmation frame of Start/Stop write actions
+        ESP_LOGI(TAG, "Wallbox charging command successfully acknowledged.");
+      }
+      break;
+    }
+  }
+}
+
+void DeltaWallbox::reset_state_() {
+  ESP_LOGW(TAG, "Resetting component state from %s. pairing_attempts=%u, pairing_in_progress=%s, rx_buffer=%u bytes",
+           LOG_STR_ARG(delta_state_to_string(this->state_)), this->pairing_attempts_,
+           this->pairing_in_progress_ ? LOG_STR_LITERAL("YES") : LOG_STR_LITERAL("NO"), (unsigned int) this->rx_len_);
+  this->cancel_timeout(RETRANSMIT_TIMEOUT_ID);
+  this->rx_len_ = 0;
+  this->state_ = DeltaState::DELTA_STATE_IDLE;
+  this->pairing_attempts_ = 0;
+  this->pairing_in_progress_ = false;
+  this->status_set_warning();
+}
+
+void DeltaWallbox::halt_(const LogString *reason) {
+  ESP_LOGE(TAG, "Halting authentication: %s. A reconnect is required to retry.", LOG_STR_ARG(reason));
+  this->cancel_timeout(RETRANSMIT_TIMEOUT_ID);
+  this->rx_len_ = 0;
+  this->state_ = DeltaState::DELTA_STATE_HALTED;
+  this->pairing_attempts_ = 0;
+  this->pairing_in_progress_ = false;
+  this->status_set_warning(reason);
+}
+
+void DeltaWallbox::set_charging_state(bool state) {
+  if (!this->is_connected()) {
+    ESP_LOGW(TAG, "Cannot send charging command while wallbox is not fully connected.");
+    return;
+  }
+
+  if (state) {
+    ESP_LOGI(TAG, "Sending remote START charging command...");
+    this->send_frame_(CMD_START_CHARGING, sizeof(CMD_START_CHARGING));
+  } else {
+    ESP_LOGI(TAG, "Sending remote STOP charging command...");
+    this->send_frame_(CMD_STOP_CHARGING, sizeof(CMD_STOP_CHARGING));
+  }
+}
+
+void DeltaWallbox::start_charging() { this->set_charging_state(true); }
+
+void DeltaWallbox::stop_charging() { this->set_charging_state(false); }
+
+void DeltaWallbox::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
+                                       esp_ble_gattc_cb_param_t *param) {
+  switch (event) {
+    case ESP_GATTC_DISCONNECT_EVT: {
+      ESP_LOGW(TAG, "Disconnected from Bluetooth wallbox client (conn_id=%u, reason=%d). Resetting state.",
+               param->disconnect.conn_id, param->disconnect.reason);
+      this->reset_state_();
+      this->node_state = esp32_ble_tracker::ClientState::IDLE;
+      break;
+    }
+    case ESP_GATTC_OPEN_EVT: {
+      ESP_LOGI(TAG, "GATT open event received: status=%d conn_id=%u", param->open.status, param->open.conn_id);
+      break;
+    }
+    case ESP_GATTC_SEARCH_CMPL_EVT: {
+      ESP_LOGI(TAG, "GATT service discovery completed: status=%d", param->search_cmpl.status);
+      auto *tx_char = this->parent_->get_characteristic(SERVICE_UUID, TX_UUID);
+      auto *rx_char = this->parent_->get_characteristic(SERVICE_UUID, RX_UUID);
+      if (tx_char == nullptr || rx_char == nullptr) {
+        ESP_LOGE(TAG, "Could not discover matching NUS TX/RX service on this BLE device.");
+        this->reset_state_();
+        break;
+      }
+      this->tx_char_handle_ = tx_char->handle;
+      this->rx_char_handle_ = rx_char->handle;
+
+      esp_err_t err = this->parent_->register_for_notify(this->rx_char_handle_);
+      if (err != ESP_OK) {
+        ESP_LOGW(TAG, "register_for_notify failed, status=%d", err);
+      }
+      break;
+    }
+    case ESP_GATTC_REG_FOR_NOTIFY_EVT: {
+      ESP_LOGI(TAG, "Register-for-notify event: status=%d handle=0x%04X", param->reg_for_notify.status,
+               param->reg_for_notify.handle);
+      if (param->reg_for_notify.handle == this->rx_char_handle_) {
+        ESP_LOGI(TAG, "Subscribed to RX notification handle 0x%04X successfully.", this->rx_char_handle_);
+        this->node_state = esp32_ble_tracker::ClientState::ESTABLISHED;
+        if (this->state_ == DeltaState::DELTA_STATE_IDLE) {
+          ESP_LOGI(TAG, "GATT connection established. Starting authentication state machine.");
+          this->advance_to_(DeltaState::DELTA_STATE_GET_MODEL);
+        }
+      }
+      break;
+    }
+    case ESP_GATTC_NOTIFY_EVT: {
+      if (param->notify.handle != this->rx_char_handle_)
+        break;
+
+      const size_t value_len = param->notify.value_len;
+      ESP_LOGD(TAG, "Notification received on handle 0x%04X with %u bytes. Buffer before append=%u bytes.",
+               param->notify.handle, param->notify.value_len, (unsigned int) this->rx_len_);
+      if (value_len > MAX_FRAME_LEN - this->rx_len_) {
+        ESP_LOGW(TAG, "Notification overflows the %u-byte RX buffer. Discarding buffered data.",
+                 (unsigned int) MAX_FRAME_LEN);
+        this->rx_len_ = 0;
+        if (value_len > MAX_FRAME_LEN)
+          break;
+      }
+      std::memcpy(this->rx_buffer_.data() + this->rx_len_, param->notify.value, value_len);
+      this->rx_len_ += value_len;
+
+      bool progress = true;
+      while (progress && this->rx_len_ >= 3) {
+        progress = false;
+        uint8_t func_code = this->rx_buffer_[1];
+        size_t expected_len = 0;
+
+        if (func_code == FC_READ_HOLDING_REGISTERS) {
+          expected_len = this->rx_buffer_[2] + READ_RESPONSE_OVERHEAD;
+        } else if (func_code == FC_WRITE_MULTIPLE_REGISTERS || func_code == FC_WRITE_SINGLE_REGISTER) {
+          expected_len = WRITE_RESPONSE_LEN;
+        } else if (func_code == (FC_EXCEPTION_FLAG | FC_READ_HOLDING_REGISTERS) ||
+                   func_code == (FC_EXCEPTION_FLAG | FC_WRITE_MULTIPLE_REGISTERS) ||
+                   func_code == (FC_EXCEPTION_FLAG | FC_WRITE_SINGLE_REGISTER)) {
+          expected_len = EXCEPTION_RESPONSE_LEN;
+        }
+
+        if (expected_len > 0) {
+          if (this->rx_len_ >= expected_len) {
+            if (verify_crc(this->rx_buffer_.data(), expected_len)) {
+              // The frame stays in rx_buffer_ during handle_frame_(); it is dropped afterwards.
+              this->handle_frame_(this->rx_buffer_.data(), expected_len);
+              this->drop_rx_bytes_(expected_len);
+              progress = true;
+            } else {
+              ESP_LOGW(TAG, "CRC mismatch while parsing notification data in state %s. Dropping one byte from buffer.",
+                       LOG_STR_ARG(delta_state_to_string(this->state_)));
+              // Shift by one byte to realign with the next possible frame start
+              this->drop_rx_bytes_(1);
+              progress = true;
+            }
+          }
+        } else {
+          ESP_LOGW(TAG,
+                   "Unsupported function code 0x%02X while parsing notification data in state %s. Advancing buffer.",
+                   func_code, LOG_STR_ARG(delta_state_to_string(this->state_)));
+          this->drop_rx_bytes_(1);
+          progress = true;
+        }
+      }
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+void DeltaWallbox::gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) {
+  switch (event) {
+    case ESP_GAP_BLE_PASSKEY_REQ_EVT: {
+      if (!this->parent_->check_addr(param->ble_security.ble_req.bd_addr))
+        return;
+
+      if (!this->has_pin_) {
+        ESP_LOGW(TAG, "Wallbox requested a BLE passkey, but no pin is configured. Set pin: under delta_wallbox:.");
+        return;
+      }
+
+      ESP_LOGI(TAG, "Wallbox requested a BLE passkey. Replying with configured YAML pin.");
+      esp_err_t err = esp_ble_passkey_reply(param->ble_security.ble_req.bd_addr, true, this->pin_);
+      if (err != ESP_OK) {
+        ESP_LOGW(TAG, "Failed to send BLE passkey reply: %s", esp_err_to_name(err));
+      }
+      break;
+    }
+    case ESP_GAP_BLE_AUTH_CMPL_EVT:
+      if (!this->parent_->check_addr(param->ble_security.auth_cmpl.bd_addr))
+        return;
+
+      this->pairing_in_progress_ = false;
+      if (param->ble_security.auth_cmpl.success) {
+        ESP_LOGI(TAG,
+                 "BLE pairing completed successfully. auth_mode=%d addr_type=%d. Re-checking wallbox pairing status.",
+                 param->ble_security.auth_cmpl.auth_mode, param->ble_security.auth_cmpl.addr_type);
+        this->pairing_attempts_ = 0;
+        if (this->node_state == esp32_ble_tracker::ClientState::ESTABLISHED &&
+            this->state_ == DeltaState::DELTA_STATE_CHECK_PAIRING) {
+          this->advance_to_(DeltaState::DELTA_STATE_CHECK_PAIRING);
+        }
+      } else {
+        ESP_LOGW(TAG, "BLE pairing failed, reason=%d", param->ble_security.auth_cmpl.fail_reason);
+      }
+      break;
+    default:
+      break;
+  }
+}
+
+}  // namespace esphome::delta_wallbox
+
+#endif

esphome/components/delta_wallbox/delta_wallbox.h

@@ -0,0 +1,103 @@
+#pragma once
+
+#ifdef USE_ESP32
+
+#include <array>
+#include "esphome/core/component.h"
+#include "esphome/components/ble_client/ble_client.h"
+#include "esphome/components/sensor/sensor.h"
+#include "esphome/components/text_sensor/text_sensor.h"
+#include "esphome/core/helpers.h"
+#include "esphome/core/string_ref.h"
+
+#ifdef USE_TIME
+#include "esphome/components/time/real_time_clock.h"
+#endif
+
+namespace esphome::delta_wallbox {
+// Largest FC03 response: unit, function, byte count, 255 data bytes, CRC.
+static constexpr size_t MAX_FRAME_LEN = 260;
+enum class DeltaState : uint8_t {
+  DELTA_STATE_CHECK_PAIRING,
+  DELTA_STATE_CONNECTED,
+  DELTA_STATE_GET_CHARGER_FW_VERSION,
+  DELTA_STATE_GET_BT_FW_VERSION,
+  DELTA_STATE_GET_LOGIN_RESULT,
+  DELTA_STATE_GET_LOGIN_RESULT0,
+  DELTA_STATE_GET_LOGIN_ROLE,
+  DELTA_STATE_GET_LOGIN_USER,
+  DELTA_STATE_GET_MODEL,
+  DELTA_STATE_GET_SERIAL_NUMBER,
+  DELTA_STATE_HALTED,
+  DELTA_STATE_IDLE,
+  DELTA_STATE_SEND_LOGIN_CREDENTIALS,
+  DELTA_STATE_TIME_SYNC,
+};
+
+class DeltaWallbox : public esphome::ble_client::BLEClientNode, public PollingComponent {
+ public:
+  DeltaWallbox(const char *user, const char *password) : user_(user), password_(password) {}
+  void update() override;
+  void gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
+                           esp_ble_gattc_cb_param_t *param) override;
+  void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) override;
+  void dump_config() override;
+
+  void set_pin(uint32_t pin) {
+    this->pin_ = pin;
+    this->has_pin_ = true;
+  }
+#ifdef USE_TIME
+  void set_time_id(time::RealTimeClock *time_id) { this->time_id_ = time_id; }
+#endif
+
+  SUB_SENSOR(power)
+  SUB_SENSOR(energy)
+  SUB_SENSOR(charging_time)
+  SUB_SENSOR(charger_state)
+  SUB_SENSOR(max_current)
+  SUB_TEXT_SENSOR(serial_number)
+  SUB_TEXT_SENSOR(fw_version)
+  SUB_TEXT_SENSOR(bt_fw_version)
+  SUB_TEXT_SENSOR(model_name)
+  SUB_TEXT_SENSOR(error_code)
+  void set_charging_state(bool state);
+  void start_charging();
+  void stop_charging();
+
+  bool is_connected() {
+    return this->node_state == esp32_ble_tracker::ClientState::ESTABLISHED &&
+           this->state_ == DeltaState::DELTA_STATE_CONNECTED;
+  }
+
+ protected:
+  void write_frame_(const uint8_t *frame, size_t len);
+  void send_frame_(const uint8_t *body, size_t len);
+  void send_next_state_command_();
+  void retransmit_();
+  void advance_to_(DeltaState next);
+  void handle_frame_(const uint8_t *frame, size_t len);
+  void drop_rx_bytes_(size_t count);
+  void reset_state_();
+  // Stops the handshake until the next BLE disconnect; used for failures a retry can't fix.
+  void halt_(const LogString *reason);
+
+  // Members ordered by size so nothing is padded
+  StringRef user_;
+  StringRef password_;
+  uint32_t pin_{0};
+#ifdef USE_TIME
+  time::RealTimeClock *time_id_{nullptr};
+#endif
+  size_t rx_len_{0};
+
+  uint16_t rx_char_handle_{0};
+  uint16_t tx_char_handle_{0};
+  DeltaState state_{DeltaState::DELTA_STATE_IDLE};
+  uint8_t pairing_attempts_{0};
+  bool has_pin_{false};
+  bool pairing_in_progress_{false};
+  std::array<uint8_t, MAX_FRAME_LEN> rx_buffer_{};
+};
+}  // namespace esphome::delta_wallbox
+#endif

esphome/components/delta_wallbox/sensor.py

@@ -0,0 +1,66 @@
+import esphome.codegen as cg
+from esphome.components import sensor
+import esphome.config_validation as cv
+from esphome.const import (
+    CONF_ENERGY,
+    CONF_MAX_CURRENT,
+    CONF_POWER,
+    DEVICE_CLASS_DURATION,
+    DEVICE_CLASS_ENERGY,
+    DEVICE_CLASS_POWER,
+    STATE_CLASS_MEASUREMENT,
+    STATE_CLASS_TOTAL_INCREASING,
+    UNIT_AMPERE,
+    UNIT_KILOWATT,
+    UNIT_KILOWATT_HOURS,
+    UNIT_MINUTE,
+)
+from esphome.types import ConfigType
+
+from . import CONF_DELTA_WALLBOX_ID, DeltaWallbox
+
+DEPENDENCIES = ["delta_wallbox"]
+
+CONF_CHARGING_TIME = "charging_time"
+CONF_CHARGER_STATE = "charger_state"
+
+CONFIG_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(CONF_DELTA_WALLBOX_ID): cv.use_id(DeltaWallbox),
+        cv.Optional(CONF_CHARGER_STATE): sensor.sensor_schema(
+            accuracy_decimals=0,
+        ),
+        cv.Optional(CONF_MAX_CURRENT): sensor.sensor_schema(
+            unit_of_measurement=UNIT_AMPERE,
+            accuracy_decimals=1,
+        ),
+        cv.Optional(CONF_POWER): sensor.sensor_schema(
+            unit_of_measurement=UNIT_KILOWATT,
+            accuracy_decimals=2,
+            device_class=DEVICE_CLASS_POWER,
+            state_class=STATE_CLASS_MEASUREMENT,
+        ),
+        cv.Optional(CONF_ENERGY): sensor.sensor_schema(
+            unit_of_measurement=UNIT_KILOWATT_HOURS,
+            accuracy_decimals=2,
+            device_class=DEVICE_CLASS_ENERGY,
+            state_class=STATE_CLASS_TOTAL_INCREASING,
+        ),
+        cv.Optional(CONF_CHARGING_TIME): sensor.sensor_schema(
+            unit_of_measurement=UNIT_MINUTE,
+            accuracy_decimals=0,
+            device_class=DEVICE_CLASS_DURATION,
+            state_class=STATE_CLASS_MEASUREMENT,
+        ),
+    }
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    hub = await cg.get_variable(config[CONF_DELTA_WALLBOX_ID])
+    sensors = sensor.sub_sensors(config)
+    await sensors(CONF_CHARGER_STATE, hub.set_charger_state_sensor)
+    await sensors(CONF_MAX_CURRENT, hub.set_max_current_sensor)
+    await sensors(CONF_POWER, hub.set_power_sensor)
+    await sensors(CONF_ENERGY, hub.set_energy_sensor)
+    await sensors(CONF_CHARGING_TIME, hub.set_charging_time_sensor)

esphome/components/delta_wallbox/text_sensor.py

@@ -0,0 +1,34 @@
+import esphome.codegen as cg
+from esphome.components import text_sensor
+from esphome.components.const import CONF_ERROR_CODE, CONF_SERIAL_NUMBER
+import esphome.config_validation as cv
+from esphome.types import ConfigType
+
+from . import CONF_DELTA_WALLBOX_ID, DeltaWallbox
+
+DEPENDENCIES = ["delta_wallbox"]
+
+CONF_FW_VERSION = "fw_version"
+CONF_BT_FW_VERSION = "bt_fw_version"
+CONF_MODEL_NAME = "model_name"
+
+CONFIG_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(CONF_DELTA_WALLBOX_ID): cv.use_id(DeltaWallbox),
+        cv.Optional(CONF_SERIAL_NUMBER): text_sensor.text_sensor_schema(),
+        cv.Optional(CONF_FW_VERSION): text_sensor.text_sensor_schema(),
+        cv.Optional(CONF_BT_FW_VERSION): text_sensor.text_sensor_schema(),
+        cv.Optional(CONF_MODEL_NAME): text_sensor.text_sensor_schema(),
+        cv.Optional(CONF_ERROR_CODE): text_sensor.text_sensor_schema(),
+    }
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    hub = await cg.get_variable(config[CONF_DELTA_WALLBOX_ID])
+    text_sensors = text_sensor.sub_text_sensors(config)
+    await text_sensors(CONF_SERIAL_NUMBER, hub.set_serial_number_text_sensor)
+    await text_sensors(CONF_FW_VERSION, hub.set_fw_version_text_sensor)
+    await text_sensors(CONF_BT_FW_VERSION, hub.set_bt_fw_version_text_sensor)
+    await text_sensors(CONF_MODEL_NAME, hub.set_model_name_text_sensor)
+    await text_sensors(CONF_ERROR_CODE, hub.set_error_code_text_sensor)

esphome/components/demo/__init__.py

@@ -18,6 +18,7 @@ from esphome.components import (
     text_sensor,
     valve,
 )
+from esphome.components.const import CONF_BUTTONS
 import esphome.config_validation as cv
 from esphome.const import (
     CONF_ACCURACY_DECIMALS,
@@ -167,7 +168,6 @@ VALVE_TYPES = {
 
 
 CONF_ALARM_CONTROL_PANELS = "alarm_control_panels"
-CONF_BUTTONS = "buttons"
 CONF_CLIMATES = "climates"
 CONF_COVERS = "covers"
 CONF_DATETIMES = "datetimes"

esphome/components/ds3231/__init__.py

@@ -1,7 +1,18 @@
-from esphome import automation
+from esphome import automation, pins
 import esphome.codegen as cg
 from esphome.components import i2c
+from esphome.components.const import CONF_ENABLED
 import esphome.config_validation as cv
+from esphome.const import (
+    CONF_FREQUENCY,
+    CONF_HOUR,
+    CONF_INTERRUPT_PIN,
+    CONF_MINUTE,
+    CONF_MODE,
+    CONF_OFFSET,
+    CONF_SECOND,
+    CONF_STATE,
+)
 from esphome.types import ConfigType
 
 CODEOWNERS = ["@linkedupbits"]
@@ -10,23 +21,245 @@ MULTI_CONF = True
 DOMAIN = "ds3231"
 
 CONF_DS3231_ID = "ds3231_id"
+CONF_ALARM = "alarm"
+CONF_ALARM_CHECK_INTERVAL = "alarm_check_interval"
+CONF_AGING_OFFSET = "aging_offset"
+CONF_AUTO_CLEAR_ALARMS = "auto_clear_alarms"
+CONF_BATTERY_BACKED_SQUARE_WAVE = "battery_backed_square_wave"
+CONF_DAY_OF_MONTH = "day_of_month"
+CONF_DAY_OF_WEEK = "day_of_week"
+CONF_ON_ALARM_1 = "on_alarm_1"
+CONF_ON_ALARM_2 = "on_alarm_2"
+CONF_OUTPUT_32KHZ = "output_32khz"
+CONF_SQUARE_WAVE_FREQUENCY = "square_wave_frequency"
 
 ds3231_ns = cg.esphome_ns.namespace("ds3231")
 DS3231Component = ds3231_ns.class_("DS3231Component", cg.Component, i2c.I2CDevice)
 
-CONFIG_SCHEMA = (
-    cv.Schema({cv.GenerateID(): cv.declare_id(DS3231Component)})
+AlarmMode = ds3231_ns.enum("AlarmMode")
+ALARM_1_MODES = AlarmMode.options(
+    "every_second",
+    "every_minute",
+    "hourly",
+    "daily",
+    "monthly",
+    "weekly",
+    prefix="ALARM_MODE_",
+)
+# Alarm 2 has no seconds register.
+ALARM_2_MODES = {k: v for k, v in ALARM_1_MODES.items() if k != "every_second"}
+
+SquareWaveFrequency = ds3231_ns.enum("SquareWaveFrequency")
+# Keyed by the frequency in Hz; cv.frequency turns "1024Hz", "1.024kHz" or 1024 into it.
+SQUARE_WAVE_FREQUENCIES = {
+    1: SquareWaveFrequency.SQUARE_WAVE_1HZ,
+    1024: SquareWaveFrequency.SQUARE_WAVE_1024HZ,
+    4096: SquareWaveFrequency.SQUARE_WAVE_4096HZ,
+    8192: SquareWaveFrequency.SQUARE_WAVE_8192HZ,
+}
+validate_square_wave_frequency = cv.All(
+    cv.frequency, cv.enum(SQUARE_WAVE_FREQUENCIES, int=True)
+)
+
+validate_aging_offset = cv.int_range(min=-128, max=127)
+
+CONFIG_SCHEMA = cv.All(
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.declare_id(DS3231Component),
+            cv.Optional(CONF_INTERRUPT_PIN): pins.internal_gpio_input_pin_schema,
+            cv.Optional(CONF_SQUARE_WAVE_FREQUENCY): validate_square_wave_frequency,
+            cv.Optional(CONF_BATTERY_BACKED_SQUARE_WAVE): cv.boolean,
+            cv.Optional(CONF_OUTPUT_32KHZ): cv.boolean,
+            cv.Optional(CONF_AGING_OFFSET): validate_aging_offset,
+            cv.Optional(CONF_AUTO_CLEAR_ALARMS, default=True): cv.boolean,
+            cv.Optional(
+                CONF_ALARM_CHECK_INTERVAL, default="1s"
+            ): cv.positive_time_period_milliseconds,
+            cv.Optional(CONF_ON_ALARM_1): automation.validate_automation(single=True),
+            cv.Optional(CONF_ON_ALARM_2): automation.validate_automation(single=True),
+        }
+    )
     .extend(cv.COMPONENT_SCHEMA)
-    .extend(i2c.i2c_device_schema(0x68))
+    .extend(i2c.i2c_device_schema(0x68)),
+    cv.has_at_most_one_key(CONF_INTERRUPT_PIN, CONF_SQUARE_WAVE_FREQUENCY),
 )
 
 
 async def to_code(config: ConfigType) -> None:
-    await i2c.new_i2c_component(config)
+    var = await i2c.new_i2c_component(config)
 
+    await cg.add_pin(var.set_interrupt_pin, config.get(CONF_INTERRUPT_PIN))
+    cg.add_optional(
+        var.set_square_wave_frequency, config.get(CONF_SQUARE_WAVE_FREQUENCY)
+    )
+    cg.add_optional(
+        var.set_battery_backed_square_wave, config.get(CONF_BATTERY_BACKED_SQUARE_WAVE)
+    )
+    cg.add_optional(var.set_output_32khz_config, config.get(CONF_OUTPUT_32KHZ))
+    cg.add_optional(var.set_aging_offset_config, config.get(CONF_AGING_OFFSET))
+    cg.add(var.set_auto_clear_alarms(config[CONF_AUTO_CLEAR_ALARMS]))
+    cg.add(var.set_alarm_check_interval(config[CONF_ALARM_CHECK_INTERVAL]))
+    # The alarm flags are only read when something uses them; the binary sensor platform
+    # turns this on as well. With an interrupt pin the check also releases INT/SQW.
+    if any(
+        key in config for key in (CONF_INTERRUPT_PIN, CONF_ON_ALARM_1, CONF_ON_ALARM_2)
+    ):
+        cg.add(var.set_monitor_alarms(True))
+
+    # One callback for both alarms; each automation runs only for its own alarm number.
+    for conf_key, alarm in ((CONF_ON_ALARM_1, 1), (CONF_ON_ALARM_2, 2)):
+        if (conf := config.get(conf_key)) is not None:
+            await automation.build_callback_automation(
+                var,
+                "add_on_alarm_callback",
+                [],
+                conf,
+                params=[(cg.uint8, "alarm")],
+                forward=[],
+                when=f"alarm == {alarm}",
+            )
+
+
+# ---------------------------------------------------------------------------------------------
+# Actions
+# ---------------------------------------------------------------------------------------------
+
+DS3231_ACTION_SCHEMA = automation.maybe_simple_id(
+    {cv.GenerateID(): cv.use_id(DS3231Component)}
+)
 
 automation.register_apply_action(
     "ds3231.force_temperature_conversion",
-    automation.maybe_simple_id({cv.GenerateID(): cv.use_id(DS3231Component)}),
+    DS3231_ACTION_SCHEMA,
     automation.ApplyCall("force_temperature_conversion()"),
 )
+
+
+def _validate_alarm_day(config: ConfigType) -> ConfigType:
+    mode = config[CONF_MODE]
+    if mode == "monthly" and CONF_DAY_OF_MONTH not in config:
+        raise cv.Invalid(f"'{CONF_DAY_OF_MONTH}' is required in monthly mode")
+    if mode == "weekly" and CONF_DAY_OF_WEEK not in config:
+        raise cv.Invalid(f"'{CONF_DAY_OF_WEEK}' is required in weekly mode")
+    # The unused day still has to be a valid register value.
+    config.setdefault(CONF_DAY_OF_MONTH, 1)
+    config.setdefault(CONF_DAY_OF_WEEK, 1)
+    return config
+
+
+def _alarm_schema(modes: dict, with_second: bool) -> cv.Schema:
+    schema = {
+        cv.GenerateID(): cv.use_id(DS3231Component),
+        cv.Required(CONF_MODE): cv.enum(modes, lower=True),
+        cv.Optional(CONF_MINUTE, default=0): cv.templatable(
+            cv.int_range(min=0, max=59)
+        ),
+        cv.Optional(CONF_HOUR, default=0): cv.templatable(cv.int_range(min=0, max=23)),
+        cv.Optional(CONF_DAY_OF_MONTH): cv.templatable(cv.int_range(min=1, max=31)),
+        # 1 = Sunday ... 7 = Saturday, as in ESPHome's time component.
+        cv.Optional(CONF_DAY_OF_WEEK): cv.templatable(cv.int_range(min=1, max=7)),
+        cv.Optional(CONF_ENABLED, default=True): cv.templatable(cv.boolean),
+    }
+    if with_second:
+        schema[cv.Optional(CONF_SECOND, default=0)] = cv.templatable(
+            cv.int_range(min=0, max=59)
+        )
+    return cv.All(cv.Schema(schema), _validate_alarm_day)
+
+
+automation.register_apply_action(
+    "ds3231.set_alarm_1",
+    _alarm_schema(ALARM_1_MODES, with_second=True),
+    automation.ApplyCall(
+        "set_alarm_1({}, {}, {}, {}, {}, {}, {})",
+        (
+            (CONF_MODE, AlarmMode),
+            (CONF_SECOND, cg.uint8),
+            (CONF_MINUTE, cg.uint8),
+            (CONF_HOUR, cg.uint8),
+            (CONF_DAY_OF_MONTH, cg.uint8),
+            (CONF_DAY_OF_WEEK, cg.uint8),
+            (CONF_ENABLED, cg.bool_),
+        ),
+    ),
+)
+
+automation.register_apply_action(
+    "ds3231.set_alarm_2",
+    _alarm_schema(ALARM_2_MODES, with_second=False),
+    automation.ApplyCall(
+        "set_alarm_2({}, {}, {}, {}, {}, {})",
+        (
+            (CONF_MODE, AlarmMode),
+            (CONF_MINUTE, cg.uint8),
+            (CONF_HOUR, cg.uint8),
+            (CONF_DAY_OF_MONTH, cg.uint8),
+            (CONF_DAY_OF_WEEK, cg.uint8),
+            (CONF_ENABLED, cg.bool_),
+        ),
+    ),
+)
+
+DS3231_ALARM_ACTION_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(): cv.use_id(DS3231Component),
+        cv.Required(CONF_ALARM): cv.templatable(cv.int_range(min=1, max=2)),
+    }
+)
+
+for _name, _method in (
+    ("ds3231.enable_alarm", "enable_alarm"),
+    ("ds3231.disable_alarm", "disable_alarm"),
+    ("ds3231.clear_alarm", "clear_alarm"),
+):
+    automation.register_apply_action(
+        _name,
+        DS3231_ALARM_ACTION_SCHEMA,
+        automation.ApplyField(CONF_ALARM, _method, cg.uint8),
+    )
+
+automation.register_apply_condition(
+    "ds3231.is_alarm_triggered",
+    DS3231_ALARM_ACTION_SCHEMA,
+    automation.ApplyCall("is_alarm_triggered({})", ((CONF_ALARM, cg.uint8),)),
+)
+
+automation.register_apply_action(
+    "ds3231.enable_square_wave",
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.use_id(DS3231Component),
+            cv.Required(CONF_FREQUENCY): validate_square_wave_frequency,
+        }
+    ),
+    automation.ApplyField(CONF_FREQUENCY, "enable_square_wave", SquareWaveFrequency),
+)
+
+automation.register_apply_action(
+    "ds3231.disable_square_wave",
+    DS3231_ACTION_SCHEMA,
+    automation.ApplyCall("disable_square_wave()"),
+)
+
+automation.register_apply_action(
+    "ds3231.set_32khz_output",
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.use_id(DS3231Component),
+            cv.Required(CONF_STATE): cv.templatable(cv.boolean),
+        }
+    ),
+    automation.ApplyField(CONF_STATE, "set_output_32khz", cg.bool_),
+)
+
+automation.register_apply_action(
+    "ds3231.set_aging_offset",
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.use_id(DS3231Component),
+            cv.Required(CONF_OFFSET): cv.templatable(validate_aging_offset),
+        }
+    ),
+    automation.ApplyField(CONF_OFFSET, "set_aging_offset", cg.int8),
+)

esphome/components/ds3231/binary_sensor/__init__.py

@@ -0,0 +1,47 @@
+import esphome.codegen as cg
+from esphome.components import binary_sensor
+import esphome.config_validation as cv
+from esphome.const import CONF_ID, DEVICE_CLASS_PROBLEM, ENTITY_CATEGORY_DIAGNOSTIC
+from esphome.types import ConfigType
+
+from .. import CONF_DS3231_ID, DS3231Component
+
+DEPENDENCIES = ["ds3231"]
+
+CONF_ALARM_1 = "alarm_1"
+CONF_ALARM_2 = "alarm_2"
+CONF_OSCILLATOR_STOPPED = "oscillator_stopped"
+
+ICON_ALARM = "mdi:alarm"
+
+CONFIG_SCHEMA = cv.All(
+    cv.Schema(
+        {
+            cv.GenerateID(CONF_ID): cv.declare_id(cg.EntityBase),
+            cv.GenerateID(CONF_DS3231_ID): cv.use_id(DS3231Component),
+            cv.Optional(CONF_ALARM_1): binary_sensor.binary_sensor_schema(
+                icon=ICON_ALARM
+            ),
+            cv.Optional(CONF_ALARM_2): binary_sensor.binary_sensor_schema(
+                icon=ICON_ALARM
+            ),
+            cv.Optional(CONF_OSCILLATOR_STOPPED): binary_sensor.binary_sensor_schema(
+                device_class=DEVICE_CLASS_PROBLEM,
+                entity_category=ENTITY_CATEGORY_DIAGNOSTIC,
+            ),
+        }
+    ),
+    cv.has_at_least_one_key(CONF_ALARM_1, CONF_ALARM_2, CONF_OSCILLATOR_STOPPED),
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    hub = await cg.get_variable(config[CONF_DS3231_ID])
+    binary_sensors = binary_sensor.sub_binary_sensors(config)
+    await binary_sensors(CONF_ALARM_1, hub.set_alarm_1_binary_sensor)
+    await binary_sensors(CONF_ALARM_2, hub.set_alarm_2_binary_sensor)
+    await binary_sensors(
+        CONF_OSCILLATOR_STOPPED, hub.set_oscillator_stopped_binary_sensor
+    )
+    if CONF_ALARM_1 in config or CONF_ALARM_2 in config:
+        cg.add(hub.set_monitor_alarms(True))

esphome/components/ds3231/ds3231.cpp

@@ -9,29 +9,184 @@ namespace esphome::ds3231 {
 
 ESPHOME_LOG_TAG(TAG, "ds3231");
 
+static constexpr uint8_t DS3231_REG_SECONDS = 0x00;
+static constexpr uint8_t DS3231_REG_ALARM_1 = 0x07;
+static constexpr uint8_t DS3231_REG_ALARM_2 = 0x0B;
 static constexpr uint8_t DS3231_REG_CONTROL = 0x0E;
+static constexpr uint8_t DS3231_REG_STATUS = 0x0F;
+static constexpr uint8_t DS3231_REG_AGING_OFFSET = 0x10;
 static constexpr uint8_t DS3231_REG_TEMPERATURE = 0x11;
 
+static constexpr uint8_t ALARM_MASK_BIT = 0x80;     // AxMy: this register is ignored when matching
+static constexpr uint8_t ALARM_DAY_OF_WEEK = 0x40;  // DY/DT: match day of week instead of date
+
+/// How long an alarm binary sensor stays on when the flag is cleared automatically.
+static constexpr uint32_t ALARM_PULSE_MS = 1000;
+
+static const LogString *alarm_state_to_string(uint8_t control, uint8_t alarm) {
+  return (control & (alarm == 1 ? 0x01 : 0x02)) != 0 ? LOG_STR("enabled") : LOG_STR("disabled");
+}
+
+static const LogString *square_wave_to_string(SquareWaveFrequency frequency) {
+  switch (frequency) {
+    case SQUARE_WAVE_1HZ:
+      return LOG_STR("1 Hz");
+    case SQUARE_WAVE_1024HZ:
+      return LOG_STR("1.024 kHz");
+    case SQUARE_WAVE_4096HZ:
+      return LOG_STR("4.096 kHz");
+    case SQUARE_WAVE_8192HZ:
+      return LOG_STR("8.192 kHz");
+    default:
+      return LOG_STR("unknown");
+  }
+}
+
+void IRAM_ATTR DS3231Component::interrupt_handler(DS3231Component *arg) { arg->enable_loop_soon_any_context(); }
+
 void DS3231Component::setup() {
   if (!this->read_control_status_()) {
     this->mark_failed(LOG_STR(ESP_LOG_MSG_COMM_FAIL));
     return;
   }
 
-  this->control_reg_ &= ~CONTROL_EOSC;  // keep the oscillator running on battery
-  // INT/SQW is the (unused) interrupt line rather than a square-wave output.
-  this->control_reg_ |= CONTROL_INTCN;
-  if (!this->write_control_()) {
+  // Keep the oscillator running on battery. INT/SQW is the alarm interrupt line unless a square
+  // wave is configured. The alarm interrupt enables (A1IE/A2IE) are kept as they are: the alarms
+  // live on the chip and survive a reboot of the ESP on battery.
+  uint8_t mask = CONTROL_EOSC | CONTROL_INTCN;
+  uint8_t value = CONTROL_INTCN;
+  if (this->square_wave_configured_) {
+    mask |= CONTROL_RS_MASK;
+    value = this->square_wave_frequency_ << CONTROL_RS_SHIFT;
+  }
+  if (this->battery_backed_square_wave_ >= 0) {
+    mask |= CONTROL_BBSQW;
+    assign_bits(value, CONTROL_BBSQW, this->battery_backed_square_wave_ != 0);
+  }
+  if (!this->update_control_(mask, value)) {
     this->mark_failed(LOG_STR(ESP_LOG_MSG_COMM_FAIL));
     return;
   }
+
+  if (this->output_32khz_ >= 0) {
+    assign_bits(this->status_reg_, STATUS_EN32KHZ, this->output_32khz_ != 0);
+    if (!this->write_status_(0)) {
+      this->mark_failed(LOG_STR(ESP_LOG_MSG_COMM_FAIL));
+      return;
+    }
+  }
+
+  if (this->aging_offset_configured_ && !this->write_aging_offset_(this->aging_offset_)) {
+    this->mark_failed(LOG_STR(ESP_LOG_MSG_COMM_FAIL));
+    return;
+  }
+
+  if ((this->status_reg_ & STATUS_OSF) != 0) {
+    ESP_LOGW(TAG, "Oscillator was stopped (battery empty or missing?), the stored time is invalid.");
+  }
+  this->publish_oscillator_stopped_();
+
+  if (!this->monitor_alarms_) {
+    this->disable_loop();
+    return;
+  }
+
+  // Start from a known state; an alarm that fired while the ESP was off is picked up by the first
+  // check, which runs from the loop right after setup.
+  this->publish_alarm_state_(1, false);
+  this->publish_alarm_state_(2, false);
+
+  if (this->interrupt_pin_ != nullptr) {
+    this->interrupt_pin_->setup();
+    // INT/SQW is open drain and active low: a falling edge means an enabled alarm matched.
+    // The handler only wakes the loop; the flags are read from there.
+    this->interrupt_pin_->attach_interrupt(&DS3231Component::interrupt_handler, this, gpio::INTERRUPT_FALLING_EDGE);
+  }
+  // Without an interrupt pin this is how alarms are seen. With one it is a fallback: it picks up an
+  // edge that was missed, and latched flags (auto_clear_alarms: false) that were cleared elsewhere.
+  this->set_interval(this->alarm_check_interval_, [this]() { this->check_alarms_(); });
+}
+
+void DS3231Component::loop() {
+  // Only runs once after setup and when woken by the interrupt pin.
+  this->disable_loop();
+  this->check_alarms_();
 }
 
 void DS3231Component::dump_config() {
   ESP_LOGCONFIG(TAG, "DS3231:");
   LOG_I2C_DEVICE(this);
+  if (this->is_failed())
+    return;
+  LOG_PIN("  Interrupt Pin: ", this->interrupt_pin_);
+  if ((this->control_reg_ & CONTROL_INTCN) == 0) {
+    ESP_LOGCONFIG(TAG, "  INT/SQW: square wave %s",
+                  LOG_STR_ARG(square_wave_to_string(
+                      static_cast<SquareWaveFrequency>((this->control_reg_ & CONTROL_RS_MASK) >> CONTROL_RS_SHIFT))));
+  } else {
+    ESP_LOGCONFIG(TAG, "  INT/SQW: alarm interrupt");
+  }
+  ESP_LOGCONFIG(TAG,
+                "  Battery-backed square wave: %s\n"
+                "  32 kHz output: %s\n"
+                "  Alarm 1: %s\n"
+                "  Alarm 2: %s\n"
+                "  Auto clear alarms: %s",
+                YESNO(this->control_reg_ & CONTROL_BBSQW), ONOFF(this->status_reg_ & STATUS_EN32KHZ),
+                LOG_STR_ARG(alarm_state_to_string(this->control_reg_, 1)),
+                LOG_STR_ARG(alarm_state_to_string(this->control_reg_, 2)), YESNO(this->auto_clear_alarms_));
+  if (this->aging_offset_configured_) {
+    ESP_LOGCONFIG(TAG, "  Aging offset: %d", this->aging_offset_);
+  }
+  if (this->monitor_alarms_) {
+    ESP_LOGCONFIG(TAG, "  Alarm check interval: %" PRIu32 " ms", this->alarm_check_interval_);
+  }
+#ifdef USE_BINARY_SENSOR
+  LOG_BINARY_SENSOR("  ", "Alarm 1", this->alarm_1_binary_sensor_);
+  LOG_BINARY_SENSOR("  ", "Alarm 2", this->alarm_2_binary_sensor_);
+  LOG_BINARY_SENSOR("  ", "Oscillator Stopped", this->oscillator_stopped_binary_sensor_);
+#endif
 }
 
+// ---------------------------------------------------------------------------------------------
+// Clock
+// ---------------------------------------------------------------------------------------------
+
+bool DS3231Component::read_calendar(uint8_t *raw) {
+  if (this->is_failed() || !this->status_comm_result(this->read_bytes(DS3231_REG_SECONDS, raw, CALENDAR_LEN)))
+    return false;
+  // Without a valid status the oscillator-stop flag is unknown, so the time can't be trusted.
+  if (!this->read_control_status_())
+    return false;
+  this->publish_oscillator_stopped_();
+  if ((this->status_reg_ & STATUS_OSF) != 0) {
+    ESP_LOGW(TAG, "Oscillator stop flag set, the RTC time is invalid. Write a valid time first.");
+    return false;
+  }
+  return true;
+}
+
+bool DS3231Component::write_calendar(const uint8_t *raw) {
+  if (this->is_failed() || !this->status_comm_result(this->write_bytes(DS3231_REG_SECONDS, raw, CALENDAR_LEN)))
+    return false;
+
+  // The time is valid again: clear the oscillator stop flag. If that fails, the RTC would keep
+  // reporting its time as invalid, so the write is not reported as successful.
+  if (!this->read_control_status_())
+    return false;
+  if ((this->status_reg_ & STATUS_OSF) != 0) {
+    if (!this->write_status_(STATUS_OSF))
+      return false;
+    this->status_reg_ &= ~STATUS_OSF;
+  }
+  this->publish_oscillator_stopped_();
+  return true;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Temperature
+// ---------------------------------------------------------------------------------------------
+
 bool DS3231Component::read_temperature(float &out) {
   uint8_t raw[2];
   if (this->is_failed() || !this->read_bytes(DS3231_REG_TEMPERATURE, raw, sizeof(raw))) {
@@ -53,26 +208,280 @@ void DS3231Component::force_temperature_conversion() {
     ESP_LOGW(TAG, "A temperature conversion is already in progress.");
     return;
   }
-  this->control_reg_ |= CONTROL_CONV;
-  this->write_control_();
+  // CONV is a one-shot command bit, so it is not kept in the cached value.
+  this->status_comm_result(this->write_byte(DS3231_REG_CONTROL, this->control_reg_ | CONTROL_CONV));
 }
 
+// ---------------------------------------------------------------------------------------------
+// Alarms
+// ---------------------------------------------------------------------------------------------
+
+void DS3231Component::set_alarm_1(AlarmMode mode, uint8_t second, uint8_t minute, uint8_t hour, uint8_t day_of_month,
+                                  uint8_t day_of_week, bool enabled) {
+  if (second > 59 || minute > 59 || hour > 23 || day_of_month < 1 || day_of_month > 31 || day_of_week < 1 ||
+      day_of_week > 7 || mode > ALARM_MODE_WEEKLY) {
+    ESP_LOGE(TAG, "Invalid alarm 1 setting.");
+    return;
+  }
+  // Mask bits A1M1..A1M4: a set bit means the register is ignored when matching.
+  uint8_t regs[4] = {
+      uint8_to_bcd(second),
+      uint8_to_bcd(minute),
+      uint8_to_bcd(hour),
+      mode == ALARM_MODE_WEEKLY ? static_cast<uint8_t>(ALARM_DAY_OF_WEEK | day_of_week) : uint8_to_bcd(day_of_month),
+  };
+  switch (mode) {
+    case ALARM_MODE_EVERY_SECOND:
+      regs[0] |= ALARM_MASK_BIT;
+      [[fallthrough]];
+    case ALARM_MODE_EVERY_MINUTE:
+      regs[1] |= ALARM_MASK_BIT;
+      [[fallthrough]];
+    case ALARM_MODE_HOURLY:
+      regs[2] |= ALARM_MASK_BIT;
+      [[fallthrough]];
+    case ALARM_MODE_DAILY:
+      regs[3] |= ALARM_MASK_BIT;
+      break;
+    default:  // MONTHLY / WEEKLY: everything matches
+      break;
+  }
+  ESP_LOGD(TAG, "Setting alarm 1: mode %u, %02u:%02u:%02u, day of month %u, day of week %u, %s", mode, hour, minute,
+           second, day_of_month, day_of_week, enabled ? LOG_STR_LITERAL("enabled") : LOG_STR_LITERAL("disabled"));
+  this->write_alarm_(1, regs, sizeof(regs), enabled);
+}
+
+void DS3231Component::set_alarm_2(AlarmMode mode, uint8_t minute, uint8_t hour, uint8_t day_of_month,
+                                  uint8_t day_of_week, bool enabled) {
+  if (minute > 59 || hour > 23 || day_of_month < 1 || day_of_month > 31 || day_of_week < 1 || day_of_week > 7 ||
+      mode == ALARM_MODE_EVERY_SECOND || mode > ALARM_MODE_WEEKLY) {
+    ESP_LOGE(TAG, "Invalid alarm 2 setting.");
+    return;
+  }
+  // Mask bits A2M2..A2M4.
+  uint8_t regs[3] = {
+      uint8_to_bcd(minute),
+      uint8_to_bcd(hour),
+      mode == ALARM_MODE_WEEKLY ? static_cast<uint8_t>(ALARM_DAY_OF_WEEK | day_of_week) : uint8_to_bcd(day_of_month),
+  };
+  switch (mode) {
+    case ALARM_MODE_EVERY_MINUTE:
+      regs[0] |= ALARM_MASK_BIT;
+      [[fallthrough]];
+    case ALARM_MODE_HOURLY:
+      regs[1] |= ALARM_MASK_BIT;
+      [[fallthrough]];
+    case ALARM_MODE_DAILY:
+      regs[2] |= ALARM_MASK_BIT;
+      break;
+    default:  // MONTHLY / WEEKLY: everything matches
+      break;
+  }
+  ESP_LOGD(TAG, "Setting alarm 2: mode %u, %02u:%02u, day of month %u, day of week %u, %s", mode, hour, minute,
+           day_of_month, day_of_week, enabled ? LOG_STR_LITERAL("enabled") : LOG_STR_LITERAL("disabled"));
+  this->write_alarm_(2, regs, sizeof(regs), enabled);
+}
+
+void DS3231Component::write_alarm_(uint8_t alarm, const uint8_t *regs, size_t len, bool enabled) {
+  if (this->is_failed())
+    return;
+  if (!this->status_comm_result(this->write_bytes(alarm == 1 ? DS3231_REG_ALARM_1 : DS3231_REG_ALARM_2, regs, len)))
+    return;
+  // Changing the registers may have matched on the way: start from a clean flag. Enabling the
+  // alarm with a stale flag would assert INT/SQW right away.
+  if (!this->clear_alarm_flag_(alarm)) {
+    ESP_LOGW(TAG, "Alarm %u written, but its flag could not be cleared; not changing its enable.", alarm);
+    return;
+  }
+  this->set_alarm_enabled_(alarm, enabled);
+}
+
+void DS3231Component::set_alarm_enabled_(uint8_t alarm, bool enabled) {
+  if (alarm != 1 && alarm != 2) {
+    ESP_LOGE(TAG, "Invalid alarm number %u.", alarm);
+    return;
+  }
+  if (this->is_failed())
+    return;
+  const uint8_t bit = alarm == 1 ? CONTROL_A1IE : CONTROL_A2IE;
+  if (!this->update_control_(bit, enabled ? bit : 0))
+    return;
+  if (enabled && (this->control_reg_ & CONTROL_INTCN) == 0) {
+    ESP_LOGW(TAG, "Alarm %u enabled, but INT/SQW is a square-wave output: only the flag will be set.", alarm);
+  }
+  ESP_LOGD(TAG, "Alarm %u %s.", alarm, enabled ? LOG_STR_LITERAL("enabled") : LOG_STR_LITERAL("disabled"));
+}
+
+void DS3231Component::enable_alarm(uint8_t alarm) {
+  // The chip sets the flag on every match even while the alarm is disabled; enabling with it set
+  // would fire the trigger (and INT/SQW) for that old match right away.
+  if (this->clear_alarm_flag_(alarm))
+    this->set_alarm_enabled_(alarm, true);
+}
+
+void DS3231Component::clear_alarm(uint8_t alarm) { this->clear_alarm_flag_(alarm); }
+
+bool DS3231Component::clear_alarm_flag_(uint8_t alarm) {
+  if (alarm != 1 && alarm != 2) {
+    ESP_LOGE(TAG, "Invalid alarm number %u.", alarm);
+    return false;
+  }
+  if (this->is_failed() || !this->read_control_status_())
+    return false;
+  const uint8_t flag = alarm == 1 ? STATUS_A1F : STATUS_A2F;
+  if ((this->status_reg_ & flag) != 0) {
+    // On failure the flag is still set on the chip: keep reporting the alarm as it is.
+    if (!this->write_status_(flag))
+      return false;
+    this->status_reg_ &= ~flag;
+  }
+  this->alarm_active_[alarm - 1] = false;
+  this->publish_alarm_state_(alarm, false);
+  return true;
+}
+
+bool DS3231Component::is_alarm_triggered(uint8_t alarm) {
+  if (this->is_failed() || !this->read_control_status_())
+    return false;
+  return (this->status_reg_ & (alarm == 1 ? STATUS_A1F : STATUS_A2F)) != 0;
+}
+
+void DS3231Component::check_alarms_() {
+  if (this->is_failed() || !this->read_control_status_())
+    return;
+  this->publish_oscillator_stopped_();
+
+  uint8_t to_clear = 0;
+  for (uint8_t alarm = 1; alarm <= 2; alarm++) {
+    const uint8_t flag = alarm == 1 ? STATUS_A1F : STATUS_A2F;
+    const uint8_t enable = alarm == 1 ? CONTROL_A1IE : CONTROL_A2IE;
+    const bool triggered = (this->status_reg_ & flag) != 0;
+    const bool enabled = (this->control_reg_ & enable) != 0;
+    bool &active = this->alarm_active_[alarm - 1];
+
+    if (!triggered) {
+      if (active && !this->auto_clear_alarms_)
+        this->publish_alarm_state_(alarm, false);
+      active = false;
+      continue;
+    }
+    // The flag is set on every match even when the alarm is disabled; only enabled alarms count.
+    if (enabled && !active) {
+      ESP_LOGI(TAG, "Alarm %u triggered.", alarm);
+      active = true;
+      this->publish_alarm_state_(alarm, true);
+      this->alarm_callback_.call(alarm);
+    }
+    if (this->auto_clear_alarms_)
+      to_clear |= flag;
+  }
+
+  if (to_clear != 0 && this->write_status_(to_clear)) {
+    this->status_reg_ &= ~to_clear;
+    for (uint8_t alarm = 1; alarm <= 2; alarm++) {
+      if ((to_clear & (alarm == 1 ? STATUS_A1F : STATUS_A2F)) == 0 || !this->alarm_active_[alarm - 1])
+        continue;
+      this->alarm_active_[alarm - 1] = false;
+#ifdef USE_BINARY_SENSOR
+      // Keep the binary sensor on long enough for the state to be seen, then turn it off again.
+      this->set_timeout(ALARM_PULSE_TIMEOUT_ID + alarm - 1, ALARM_PULSE_MS,
+                        [this, alarm]() { this->publish_alarm_state_(alarm, false); });
+#endif
+    }
+  }
+}
+
+void DS3231Component::publish_alarm_state_(uint8_t alarm, bool state) {
+#ifdef USE_BINARY_SENSOR
+  auto *sensor = alarm == 1 ? this->alarm_1_binary_sensor_ : this->alarm_2_binary_sensor_;
+  if (sensor != nullptr)
+    sensor->publish_state(state);
+#endif
+}
+
+void DS3231Component::publish_oscillator_stopped_() {
+#ifdef USE_BINARY_SENSOR
+  if (this->oscillator_stopped_binary_sensor_ != nullptr)
+    this->oscillator_stopped_binary_sensor_->publish_state((this->status_reg_ & STATUS_OSF) != 0);
+#endif
+}
+
+// ---------------------------------------------------------------------------------------------
+// Outputs and calibration
+// ---------------------------------------------------------------------------------------------
+
+void DS3231Component::enable_square_wave(SquareWaveFrequency frequency) {
+  if (this->interrupt_pin_ != nullptr) {
+    ESP_LOGE(TAG, "Can't enable the square wave: INT/SQW is used as the alarm interrupt pin.");
+    return;
+  }
+  if (this->is_failed())
+    return;
+  if (this->update_control_(CONTROL_INTCN | CONTROL_RS_MASK, frequency << CONTROL_RS_SHIFT)) {
+    ESP_LOGD(TAG, "Square wave enabled at %s.", LOG_STR_ARG(square_wave_to_string(frequency)));
+  }
+}
+
+void DS3231Component::disable_square_wave() {
+  if (this->is_failed())
+    return;
+  if (this->update_control_(CONTROL_INTCN, CONTROL_INTCN)) {
+    ESP_LOGD(TAG, "Square wave disabled, INT/SQW is the alarm interrupt.");
+  }
+}
+
+void DS3231Component::set_output_32khz(bool enabled) {
+  if (this->is_failed() || !this->read_control_status_())
+    return;
+  assign_bits(this->status_reg_, STATUS_EN32KHZ, enabled);
+  if (this->write_status_(0)) {
+    ESP_LOGD(TAG, "32 kHz output %s.", ONOFF(enabled));
+  }
+}
+
+void DS3231Component::set_aging_offset(int8_t offset) {
+  if (this->is_failed())
+    return;
+  if (!this->write_aging_offset_(offset))
+    return;
+  ESP_LOGD(TAG, "Aging offset set to %d.", offset);
+  // The new offset takes effect with the next temperature conversion.
+  this->force_temperature_conversion();
+}
+
+// ---------------------------------------------------------------------------------------------
+// Register access
+// ---------------------------------------------------------------------------------------------
+
 bool DS3231Component::read_control_status_() {
   uint8_t raw[2];
-  if (!this->read_bytes(DS3231_REG_CONTROL, raw, sizeof(raw))) {
-    ESP_LOGW(TAG, "Can't read control/status registers.");
+  if (!this->status_comm_result(this->read_bytes(DS3231_REG_CONTROL, raw, sizeof(raw))))
     return false;
-  }
-  this->control_reg_ = raw[0];
+  this->control_reg_ = raw[0] & ~CONTROL_CONV;
   this->status_reg_ = raw[1];
   return true;
 }
 
-bool DS3231Component::write_control_() {
-  if (!this->write_byte(DS3231_REG_CONTROL, this->control_reg_)) {
-    ESP_LOGW(TAG, "Can't write control register.");
+bool DS3231Component::update_control_(uint8_t mask, uint8_t value) {
+  // CONV is a one-shot command bit: always write it back as 0 so a control change never starts
+  // a temperature conversion.
+  if (!this->status_comm_result(this->update_register(DS3231_REG_CONTROL, mask | CONTROL_CONV, value)))
     return false;
-  }
+  this->control_reg_ = (this->control_reg_ & ~mask) | (value & mask);
+  return true;
+}
+
+bool DS3231Component::write_status_(uint8_t clear) {
+  // The flags can only be written to 0; writing 1 leaves them unchanged, so a flag that was set
+  // between the read and this write is never lost.
+  const uint8_t value = ((this->status_reg_ & STATUS_EN32KHZ) | STATUS_FLAGS) & ~clear;
+  return this->status_comm_result(this->write_byte(DS3231_REG_STATUS, value));
+}
+
+bool DS3231Component::write_aging_offset_(int8_t offset) {
+  if (!this->status_comm_result(this->write_byte(DS3231_REG_AGING_OFFSET, static_cast<uint8_t>(offset))))
+    return false;
+  this->aging_offset_ = offset;
   return true;
 }
 

esphome/components/ds3231/ds3231.h

@@ -1,32 +1,163 @@
 #pragma once
 
 #include "esphome/core/component.h"
+#include "esphome/core/defines.h"
+#include "esphome/core/hal.h"
+#include "esphome/core/helpers.h"
 #include "esphome/components/i2c/i2c.h"
 
+#ifdef USE_BINARY_SENSOR
+#include "esphome/components/binary_sensor/binary_sensor.h"
+#endif
+
 namespace esphome::ds3231 {
 
+/// When an alarm fires. Alarm 1 supports every mode, alarm 2 has no seconds register and so no EVERY_SECOND.
+enum AlarmMode : uint8_t {
+  ALARM_MODE_EVERY_SECOND = 0,  ///< Alarm 1 only.
+  ALARM_MODE_EVERY_MINUTE,      ///< Alarm 1: when the seconds match. Alarm 2: at second 00 of every minute.
+  ALARM_MODE_HOURLY,            ///< When minutes (and seconds) match.
+  ALARM_MODE_DAILY,             ///< When hours, minutes (and seconds) match.
+  ALARM_MODE_MONTHLY,           ///< When date, hours, minutes (and seconds) match.
+  ALARM_MODE_WEEKLY,            ///< When day of week, hours, minutes (and seconds) match.
+};
+
+/// Frequency of the INT/SQW pin when it is a square-wave output (RS2:RS1 in the control register).
+enum SquareWaveFrequency : uint8_t {
+  SQUARE_WAVE_1HZ = 0,
+  SQUARE_WAVE_1024HZ = 1,
+  SQUARE_WAVE_4096HZ = 2,
+  SQUARE_WAVE_8192HZ = 3,
+};
+
 /// Hub for a single DS3231 real-time clock. Owns all register access; the platforms talk to the
 /// chip through this class.
 class DS3231Component final : public Component, public i2c::I2CDevice {
  public:
+  /// Seconds through year, the 7-byte BCD calendar the time platform decodes with time::DS_BCD_CALENDAR.
+  static constexpr size_t CALENDAR_LEN = 7;
+
   void setup() override;
+  void loop() override;
   void dump_config() override;
 
+  // ---- Configuration (set from codegen) ----
+  void set_interrupt_pin(InternalGPIOPin *pin) { this->interrupt_pin_ = pin; }
+  void set_square_wave_frequency(SquareWaveFrequency frequency) {
+    this->square_wave_frequency_ = frequency;
+    this->square_wave_configured_ = true;
+  }
+  void set_battery_backed_square_wave(bool enabled) { this->battery_backed_square_wave_ = enabled ? 1 : 0; }
+  void set_output_32khz_config(bool enabled) { this->output_32khz_ = enabled ? 1 : 0; }
+  void set_aging_offset_config(int8_t offset) {
+    this->aging_offset_ = offset;
+    this->aging_offset_configured_ = true;
+  }
+  void set_auto_clear_alarms(bool auto_clear) { this->auto_clear_alarms_ = auto_clear; }
+  void set_alarm_check_interval(uint32_t interval) { this->alarm_check_interval_ = interval; }
+  void set_monitor_alarms(bool monitor) { this->monitor_alarms_ = monitor; }
+
+  /// Register a void(uint8_t alarm) callback that runs when an enabled alarm (1 or 2) matches.
+  template<typename F> void add_on_alarm_callback(F &&callback) {
+    this->alarm_callback_.add(std::forward<F>(callback));
+  }
+
+#ifdef USE_BINARY_SENSOR
+  SUB_BINARY_SENSOR(alarm_1)
+  SUB_BINARY_SENSOR(alarm_2)
+  SUB_BINARY_SENSOR(oscillator_stopped)
+#endif
+
+  // ---- Clock registers (used by the time platform) ----
+  /// Read the calendar registers into @p raw. Fails if the oscillator was stopped since the time was last set.
+  bool read_calendar(uint8_t *raw);
+  /// Write the calendar registers from @p raw and clear the oscillator-stop flag.
+  bool write_calendar(const uint8_t *raw);
+
+  // ---- Temperature ----
   bool read_temperature(float &out);
   void force_temperature_conversion();
 
+  // ---- Alarms ----
+  /// Program alarm 1. @p day_of_month is used in MONTHLY mode, @p day_of_week (1 = Sunday) in WEEKLY mode.
+  void set_alarm_1(AlarmMode mode, uint8_t second, uint8_t minute, uint8_t hour, uint8_t day_of_month,
+                   uint8_t day_of_week, bool enabled);
+  /// Program alarm 2 (minute resolution, fires at second 00).
+  void set_alarm_2(AlarmMode mode, uint8_t minute, uint8_t hour, uint8_t day_of_month, uint8_t day_of_week,
+                   bool enabled);
+  /// Enable @p alarm. A match from while it was disabled is cleared first, so only the next one fires.
+  void enable_alarm(uint8_t alarm);
+  void disable_alarm(uint8_t alarm) { this->set_alarm_enabled_(alarm, false); }
+  /// Clear the alarm flag, which also releases the INT/SQW line.
+  void clear_alarm(uint8_t alarm);
+  /// True while the alarm flag of @p alarm (1 or 2) is set on the chip.
+  bool is_alarm_triggered(uint8_t alarm);
+
+  // ---- Outputs and calibration ----
+  /// Switch INT/SQW to a square-wave output at @p frequency. Alarms then no longer drive the pin.
+  void enable_square_wave(SquareWaveFrequency frequency);
+  /// Switch INT/SQW back to the (active-low) alarm interrupt output.
+  void disable_square_wave();
+  void set_output_32khz(bool enabled);
+  /// Aging offset in LSB (about 0.1 ppm each at 25 degC); positive values slow the clock down.
+  void set_aging_offset(int8_t offset);
+
  protected:
+  static constexpr uint8_t CONTROL_A1IE = 0x01;
+  static constexpr uint8_t CONTROL_A2IE = 0x02;
   static constexpr uint8_t CONTROL_INTCN = 0x04;
+  static constexpr uint8_t CONTROL_RS_MASK = 0x18;
+  static constexpr uint8_t CONTROL_RS_SHIFT = 3;
   static constexpr uint8_t CONTROL_CONV = 0x20;
+  static constexpr uint8_t CONTROL_BBSQW = 0x40;
   static constexpr uint8_t CONTROL_EOSC = 0x80;
 
+  static constexpr uint8_t STATUS_A1F = 0x01;
+  static constexpr uint8_t STATUS_A2F = 0x02;
   static constexpr uint8_t STATUS_BSY = 0x04;
+  static constexpr uint8_t STATUS_EN32KHZ = 0x08;
+  static constexpr uint8_t STATUS_OSF = 0x80;
+  static constexpr uint8_t STATUS_FLAGS = STATUS_A1F | STATUS_A2F | STATUS_OSF;
 
+  /// Scheduler ids: one pulse timer per alarm (id + alarm - 1).
+  static constexpr uint32_t ALARM_PULSE_TIMEOUT_ID = 0;
+
+  static void interrupt_handler(DS3231Component *arg);
+
+  /// Read the control and status registers into the cached copies. Sets the warning flag on failure.
   bool read_control_status_();
-  bool write_control_();
+  /// Replace the bits in @p mask of the control register with @p value, on the chip and in the cache.
+  bool update_control_(uint8_t mask, uint8_t value);
+  /// Write the status register, clearing the flags in @p clear (writing 1 to a flag leaves it unchanged).
+  bool write_status_(uint8_t clear);
+  bool write_aging_offset_(int8_t offset);
+  /// Clear the flag of @p alarm and report it off. Returns false (state unchanged) if that fails.
+  bool clear_alarm_flag_(uint8_t alarm);
+  void set_alarm_enabled_(uint8_t alarm, bool enabled);
+  /// Write the alarm registers, clear the stale flag and set the interrupt enable.
+  void write_alarm_(uint8_t alarm, const uint8_t *regs, size_t len, bool enabled);
+  /// Read the flags, fire triggers and update the binary sensors.
+  void check_alarms_();
+  void publish_alarm_state_(uint8_t alarm, bool state);
+  void publish_oscillator_stopped_();
 
+  InternalGPIOPin *interrupt_pin_{nullptr};
+  LazyCallbackManager<void(uint8_t)> alarm_callback_;
+
+  uint32_t alarm_check_interval_{1000};
   uint8_t control_reg_{0};
   uint8_t status_reg_{0};
+  int8_t aging_offset_{0};
+  SquareWaveFrequency square_wave_frequency_{SQUARE_WAVE_1HZ};
+  /// -1: leave the chip as it is, 0: off, 1: on.
+  int8_t battery_backed_square_wave_{-1};
+  int8_t output_32khz_{-1};
+  bool square_wave_configured_{false};
+  bool aging_offset_configured_{false};
+  bool auto_clear_alarms_{true};
+  bool monitor_alarms_{false};
+  /// Set while an alarm flag has been reported, so a latched flag fires its trigger only once.
+  bool alarm_active_[2]{false, false};
 };
 
 }  // namespace esphome::ds3231

esphome/components/ds3231/time/__init__.py

@@ -0,0 +1,40 @@
+from esphome import automation
+import esphome.codegen as cg
+from esphome.components import time
+import esphome.config_validation as cv
+from esphome.const import CONF_ID
+from esphome.types import ConfigType
+
+from .. import CONF_DS3231_ID, DS3231Component, ds3231_ns
+
+DEPENDENCIES = ["ds3231"]
+
+DS3231Time = ds3231_ns.class_(
+    "DS3231Time", time.RealTimeClock, cg.Parented.template(DS3231Component)
+)
+
+CONFIG_SCHEMA = time.TIME_SCHEMA.extend(
+    {
+        cv.GenerateID(): cv.declare_id(DS3231Time),
+        cv.GenerateID(CONF_DS3231_ID): cv.use_id(DS3231Component),
+    }
+)
+
+DS3231_TIME_ACTION_SCHEMA = automation.maybe_simple_id(
+    {cv.GenerateID(): cv.use_id(DS3231Time)}
+)
+
+automation.register_apply_action(
+    "ds3231.write_time", DS3231_TIME_ACTION_SCHEMA, automation.ApplyCall("write_time()")
+)
+
+automation.register_apply_action(
+    "ds3231.read_time", DS3231_TIME_ACTION_SCHEMA, automation.ApplyCall("read_time()")
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    var = cg.new_Pvariable(config[CONF_ID])
+    await cg.register_component(var, config)
+    await cg.register_parented(var, config[CONF_DS3231_ID])
+    await time.register_time(var, config)

esphome/components/ds3231/time/ds3231_time.cpp

@@ -0,0 +1,48 @@
+#include "ds3231_time.h"
+#include "esphome/core/log.h"
+
+namespace esphome::ds3231 {
+
+ESPHOME_LOG_TAG(TAG, "ds3231.time");
+
+void DS3231Time::update() { this->read_time(); }
+
+void DS3231Time::dump_config() {
+  ESP_LOGCONFIG(TAG, "DS3231 Time:");
+  RealTimeClock::dump_config();
+}
+
+void DS3231Time::read_time() {
+  uint8_t raw[DS3231Component::CALENDAR_LEN];
+  if (!this->status_comm_result(this->parent_->read_calendar(raw), LOG_STR("No valid time from the RTC")))
+    return;
+  const ESPTime rtc_time = time::decode_bcd_calendar<time::DS_BCD_CALENDAR>(raw);
+  ESP_LOGD(TAG, "Read UTC time: %04u-%02u-%02u %02u:%02u:%02u (day of week %u)", rtc_time.year, rtc_time.month,
+           rtc_time.day_of_month, rtc_time.hour, rtc_time.minute, rtc_time.second, rtc_time.day_of_week);
+  // The day of week is a free-running counter on the DS3231 and may have been set with a different
+  // numbering by other software, so it is not used to validate the time.
+  if (!this->status_comm_result(rtc_time.is_valid(/*check_day_of_week=*/false, /*check_day_of_year=*/false),
+                                LOG_STR("Invalid RTC time")))
+    return;
+  this->synchronize_epoch_(rtc_time.timestamp);
+}
+
+void DS3231Time::write_time() {
+  auto now = this->utcnow();
+  if (!now.is_valid()) {
+    ESP_LOGE(TAG, "Invalid system time, not syncing to RTC.");
+    return;
+  }
+  if (now.year > 2199) {
+    ESP_LOGE(TAG, "Year %u is out of the DS3231 range (2000-2199).", now.year);
+    return;
+  }
+  uint8_t raw[DS3231Component::CALENDAR_LEN];
+  time::encode_bcd_calendar<time::DS_BCD_CALENDAR>(now, raw);
+  if (!this->status_comm_result(this->parent_->write_calendar(raw)))
+    return;
+  ESP_LOGD(TAG, "Wrote UTC time: %04u-%02u-%02u %02u:%02u:%02u", now.year, now.month, now.day_of_month, now.hour,
+           now.minute, now.second);
+}
+
+}  // namespace esphome::ds3231

esphome/components/ds3231/time/ds3231_time.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include "esphome/core/component.h"
+#include "esphome/core/helpers.h"
+#include "esphome/components/time/real_time_clock.h"
+
+#include "../ds3231.h"
+
+namespace esphome::ds3231 {
+
+class DS3231Time final : public time::RealTimeClock, public Parented<DS3231Component> {
+ public:
+  void update() override;
+  void dump_config() override;
+
+  /// Set the system clock from the RTC.
+  void read_time();
+  /// Store the system clock in the RTC.
+  void write_time();
+};
+
+}  // namespace esphome::ds3231

esphome/components/duco/__init__.py

@@ -0,0 +1,87 @@
+import esphome.codegen as cg
+from esphome.components import time, uart
+import esphome.config_validation as cv
+from esphome.const import CONF_DISCOVERY, CONF_ID, CONF_TIME, CONF_TIME_ID
+from esphome.core import ID
+from esphome.types import ConfigType
+
+CODEOWNERS = ["@kokx"]
+DEPENDENCIES = ["uart"]
+DOMAIN = "duco"
+MULTI_CONF = True
+
+CONF_DISABLE_CRC = "disable_crc"
+CONF_DUCO_ID = "duco_id"
+
+duco_ns = cg.esphome_ns.namespace("duco")
+Duco = duco_ns.class_("Duco", cg.Component, uart.UARTDevice)
+# Base of every class that sends requests through the hub
+DucoDevice = duco_ns.class_(
+    "DucoDevice", cg.PollingComponent, cg.Parented.template(Duco)
+)
+DucoDiscovery = duco_ns.class_("DucoDiscovery", DucoDevice)
+DucoTime = duco_ns.class_("DucoTime", cg.PollingComponent, cg.Parented.template(Duco))
+
+# Entities of the platforms take the hub with this
+DUCO_COMPONENT_SCHEMA = cv.Schema({cv.GenerateID(CONF_DUCO_ID): cv.use_id(Duco)})
+
+DISCOVERY_SCHEMA = cv.Schema({cv.GenerateID(): cv.declare_id(DucoDiscovery)}).extend(
+    cv.COMPONENT_SCHEMA
+)
+
+TIME_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(): cv.declare_id(DucoTime),
+        cv.GenerateID(CONF_TIME_ID): cv.use_id(time.RealTimeClock),
+    }
+).extend(cv.polling_component_schema("15min"))
+
+CONFIG_SCHEMA = (
+    cv.Schema(
+        {
+            cv.GenerateID(): cv.declare_id(Duco),
+            cv.Optional(CONF_DISABLE_CRC, default=False): cv.boolean,
+            cv.Optional(CONF_DISCOVERY): DISCOVERY_SCHEMA,
+            cv.Optional(CONF_TIME): TIME_SCHEMA,
+        }
+    )
+    .extend(cv.COMPONENT_SCHEMA)
+    .extend(uart.UART_DEVICE_SCHEMA)
+)
+
+FINAL_VALIDATE_SCHEMA = uart.final_validate_device_schema(
+    DOMAIN,
+    baud_rate=57600,
+    require_tx=True,
+    require_rx=True,
+    data_bits=8,
+    parity="NONE",
+    stop_bits=1,
+)
+
+
+_request_device_slot = cg.slot_counter("DUCO_DEVICE_COUNT")
+
+
+async def register_duco_device(var: cg.MockObj, config: ConfigType, hub_id: ID) -> None:
+    """Register a device that sends requests, and give it an open request slot on its hub."""
+    await cg.register_component(var, config)
+    hub = await cg.get_variable(hub_id)
+    await cg.register_parented(var, hub)
+    _request_device_slot(str(hub_id))
+    cg.add(hub.register_device(var))
+
+
+async def to_code(config: ConfigType) -> None:
+    var = await uart.new_uart_component(config)
+    cg.add(var.set_disable_crc(config[CONF_DISABLE_CRC]))
+
+    if (discovery := config.get(CONF_DISCOVERY)) is not None:
+        discovery_var = cg.new_Pvariable(discovery[CONF_ID])
+        await register_duco_device(discovery_var, discovery, config[CONF_ID])
+
+    if (time_config := config.get(CONF_TIME)) is not None:
+        clock = await cg.get_variable(time_config[CONF_TIME_ID])
+        time_var = cg.new_Pvariable(time_config[CONF_ID], clock)
+        await cg.register_component(time_var, time_config)
+        await cg.register_parented(time_var, var)

esphome/components/duco/duco.cpp

@@ -0,0 +1,273 @@
+#include "duco.h"
+
+#include "esphome/core/application.h"
+#include "esphome/core/log.h"
+
+namespace esphome::duco {
+
+ESPHOME_LOG_TAG(TAG, "duco");
+
+static constexpr uint8_t HEADER_START = 0xAA;
+static constexpr uint8_t HEADER_END = 0x55;
+static constexpr uint8_t STUFFING = 0x01;  // follows an 0xAA inside a message, not part of it
+static constexpr uint32_t FRAME_GAP_MS = 50;
+
+static constexpr uint32_t DISCOVERY_START_ID = 0;
+static constexpr uint32_t DISCOVERY_STEP_ID = 1;
+static constexpr uint32_t DISCOVERY_START_MS = 16000;
+static constexpr uint32_t DISCOVERY_STEP_MS = 1600;
+static constexpr uint8_t DISCOVERY_MAX_ATTEMPTS = 3;
+
+void Duco::loop() {
+  const uint32_t now = App.get_loop_component_start_time();
+  // Read first: after a slow loop pass the rest of a message is already waiting, which is not silence
+  this->read_available([this, now](uint8_t byte) {
+    if (this->parse_byte_(byte)) {
+      this->last_byte_ = now;
+    } else {
+      this->reset_frame_();
+    }
+  });
+
+  // The last message of a burst has no header after it, so it ends on silence
+  if (this->rx_size_ != 0 && now - this->last_byte_ > FRAME_GAP_MS) {
+    this->finalize_message_();
+    this->reset_frame_();
+  }
+}
+
+void Duco::reset_frame_() {
+  this->rx_size_ = 0;
+  this->escaped_ = false;
+}
+
+void Duco::close_request(DucoDevice *device) {
+#ifdef DUCO_DEVICE_COUNT
+  for (auto &pending : this->pending_) {
+    if (pending.device == device) {
+      pending.function = 0;
+      pending.missed = false;
+      this->update_warning_();
+      return;
+    }
+  }
+#endif
+}
+
+bool Duco::parse_byte_(uint8_t byte) {
+  const size_t at = this->rx_size_;
+  if (at >= MAX_FRAME_SIZE) {
+    ESP_LOGV(TAG, "Message longer than %u bytes dropped", static_cast<unsigned>(MAX_FRAME_SIZE));
+    return false;
+  }
+  const uint8_t prev = at > 0 ? this->rx_buffer_[at - 1] : 0;
+
+  if (at == 1 && prev == HEADER_START && byte == HEADER_END)
+    return false;  // header of the next message
+
+  if (at >= 2) {
+    const bool escaped = this->escaped_;
+    this->escaped_ = false;
+    if (prev == HEADER_START && !escaped) {
+      if (byte == STUFFING) {
+        this->escaped_ = true;
+        return true;
+      }
+      if (at >= 3 && byte == HEADER_END) {
+        this->rx_size_--;  // drop the 0xAA of the header
+        this->finalize_message_();
+        return false;
+      }
+    }
+  }
+
+  this->rx_buffer_[this->rx_size_++] = byte;
+  return true;
+}
+
+void Duco::finalize_message_() {
+  const uint8_t *raw = this->rx_buffer_.data();
+  // length (function, id and data), function, id, data, CRC low, CRC high
+  if (this->rx_size_ < 5 || raw[0] < 2 || this->rx_size_ < raw[0] + 3u) {
+    ESP_LOGV(TAG, "Malformed message dropped: %u bytes, length byte %u", this->rx_size_, raw[0]);
+    return;
+  }
+  const uint8_t length = raw[0];
+
+  const uint16_t computed_crc = crc16(raw, length + 1);
+  const uint16_t remote_crc = encode_uint16(raw[length + 2], raw[length + 1]);
+  if (computed_crc != remote_crc) {
+    if (!this->disable_crc_) {
+      ESP_LOGV(TAG, "CRC check failed: %04X != %04X", computed_crc, remote_crc);
+      return;
+    }
+    ESP_LOGV(TAG, "CRC check failed, ignored: %04X != %04X", computed_crc, remote_crc);
+  }
+
+#ifdef DUCO_DEVICE_COUNT
+  // The box first acknowledges a request with function + 1, then answers with function + 2
+  const DucoMessage message{raw[2], raw + 3, static_cast<uint8_t>(length - 2)};
+  for (auto &pending : this->pending_) {
+    if (pending.function != 0 && pending.id == message.id && pending.function + 2 == raw[1]) {
+      pending.function = 0;
+      pending.missed = false;
+      this->update_warning_();
+      pending.device->receive_response(message);
+      return;
+    }
+  }
+  // Acknowledgements (odd function codes) are expected and never match
+  if ((raw[1] & 1) == 0) {
+    ESP_LOGV(TAG, "Answer %02X with id %u matches no open request", raw[1], message.id);
+  }
+#endif
+}
+
+#ifdef DUCO_DEVICE_COUNT
+void Duco::update_warning_() {
+  for (const auto &pending : this->pending_) {
+    if (pending.missed) {
+      this->status_set_warning(LOG_STR("No answer from the box"));
+      return;
+    }
+  }
+  this->status_clear_warning();
+}
+#endif
+
+void Duco::dump_config() {
+  ESP_LOGCONFIG(TAG,
+                "Duco:\n"
+                "  CRC Disabled: %s",
+                YESNO(this->disable_crc_));
+}
+
+uint8_t Duco::next_id_() {
+  do {
+    this->last_id_++;
+  } while (this->last_id_ == HEADER_START || this->last_id_ == HEADER_END);
+  return this->last_id_;
+}
+
+void Duco::send(DucoDevice *device, uint8_t function, std::initializer_list<uint8_t> data) {
+  if (data.size() > MAX_REQUEST_DATA) {
+    ESP_LOGE(TAG, "Request of %u bytes is too long", static_cast<unsigned>(data.size()));
+    return;
+  }
+  // Not byte stuffed, as in the author's original and no capture shows a request with 0xAA. An 0xAA followed by any
+  // byte but 0x01 or 0x55 reads the same with or without unstuffing on the box, so only those rare pairs are
+  // unverified.
+  const size_t size = data.size();
+  const uint8_t id = this->next_id_();
+  uint8_t frame[5 + MAX_REQUEST_DATA + 2] = {HEADER_START, HEADER_END, static_cast<uint8_t>(size + 2), function, id};
+  std::copy_n(data.begin(), size, frame + 5);
+  const uint16_t crc = crc16(frame + 2, size + 3);
+  frame[size + 5] = crc & 0xFF;
+  frame[size + 6] = crc >> 8;
+  this->write_array(frame, size + 7);
+  this->flush();
+
+#ifdef DUCO_DEVICE_COUNT
+  for (auto &pending : this->pending_) {
+    if (pending.device == device) {
+      pending.missed = pending.function != 0;
+      if (pending.missed) {
+        ESP_LOGV(TAG, "No answer to request %02X with id %u", pending.function, pending.id);
+        this->update_warning_();
+      }
+      pending.id = id;
+      pending.function = function;
+      break;
+    }
+  }
+#endif
+
+  ESP_LOGV_HEX(TAG, frame + 2, size + 5, sizeof(frame), "Sent %s");
+}
+
+static const LogString *node_type_name(uint8_t type) {
+  switch (type) {
+    case 8:
+      return LOG_STR("UCBAT");
+    case 9:
+      return LOG_STR("UC");
+    case 10:
+      return LOG_STR("UCRH");
+    case 12:
+      return LOG_STR("UCCO2");
+    case 13:
+      return LOG_STR("VLV");
+    case 17:
+      return LOG_STR("BOX");
+    case 18:
+      return LOG_STR("SWITCH");
+    default:
+      return LOG_STR("UNKNOWN");
+  }
+}
+
+void DucoDiscovery::setup() {
+  // Give the box time to start before walking its node addresses
+  this->set_timeout(DISCOVERY_START_ID, DISCOVERY_START_MS, [this]() {
+    this->set_interval(DISCOVERY_STEP_ID, DISCOVERY_STEP_MS, [this]() { this->update(); });
+  });
+}
+
+void DucoDiscovery::update() {
+  if (this->attempts_ == DISCOVERY_MAX_ATTEMPTS) {
+    ESP_LOGV(TAG, "No answer for node %u", this->next_node_);
+    this->next_node_++;
+    this->attempts_ = 0;
+  }
+  if (this->next_node_ >= NODE_COUNT) {
+    this->cancel_interval(DISCOVERY_STEP_ID);
+    this->parent_->close_request(this);
+    return;
+  }
+  // Without an answer by the next step the same node is asked again; a retry is not a missed answer
+  if (this->attempts_ > 0)
+    this->parent_->close_request(this);
+  ESP_LOGV(TAG, "Discovering node %u", this->next_node_);
+  this->attempts_++;
+  this->parent_->send(this, FUNCTION_NODE, {0x01, this->next_node_});
+}
+
+void DucoDiscovery::receive_response(const DucoMessage &message) {
+  // Only the latest attempt is open, so a late answer to an earlier one never arrives here
+  if (message.size >= 1 && this->next_node_ < NODE_COUNT) {
+    if (message.data[0] != 0) {
+      ESP_LOGV(TAG, "Found node %u: type %u", this->next_node_, message.data[0]);
+    }
+    this->node_types_[this->next_node_++] = message.data[0];
+    this->attempts_ = 0;
+  }
+}
+
+void DucoDiscovery::dump_config() {
+  ESP_LOGCONFIG(TAG, "Discovered nodes:");
+  for (uint8_t node = 0; node < NODE_COUNT; node++) {
+    const uint8_t type = this->node_types_[node];
+    if (type != 0) {
+      ESP_LOGCONFIG(TAG, "  Node %u: type %u (%s)", node, type, LOG_STR_ARG(node_type_name(type)));
+    }
+  }
+  if (this->next_node_ < NODE_COUNT) {
+    ESP_LOGCONFIG(TAG, "  Still discovering, at node %u", this->next_node_);
+  }
+}
+
+#ifdef USE_TIME
+void DucoTime::update() {
+  const ESPTime now = this->clock_->now();
+  if (!now.is_valid()) {
+    ESP_LOGV(TAG, "Time is not valid yet");
+    return;
+  }
+  const uint32_t ts = now.timestamp;
+  this->parent_->send(nullptr, FUNCTION_PARAMETER,
+                      {0x05, static_cast<uint8_t>(ts), static_cast<uint8_t>(ts >> 8), static_cast<uint8_t>(ts >> 16),
+                       static_cast<uint8_t>(ts >> 24), 0x00, 0x00, 0x00, 0x00});
+}
+#endif
+
+}  // namespace esphome::duco

esphome/components/duco/duco.h

@@ -0,0 +1,113 @@
+#pragma once
+
+#include <array>
+#include <initializer_list>
+
+#include "esphome/components/uart/uart.h"
+#include "esphome/core/component.h"
+#include "esphome/core/helpers.h"
+
+#ifdef USE_TIME
+#include "esphome/components/time/real_time_clock.h"
+#endif
+
+namespace esphome::duco {
+
+// Function codes of the requests; the box answers a request with function + 2
+static constexpr uint8_t FUNCTION_NODE = 0x0c;       // discovery, status and mode of a node
+static constexpr uint8_t FUNCTION_NODE_DATA = 0x10;  // a block of a node's data (sensors, serial number)
+static constexpr uint8_t FUNCTION_PARAMETER = 0x24;  // read or write a box parameter, set the clock
+
+/// A received message; data points into the receive buffer and is valid only during the callback.
+struct DucoMessage {
+  uint8_t id;
+  const uint8_t *data;
+  uint8_t size;
+};
+
+class DucoDevice;
+
+/// The open request of one device: the answer to it is function + 2 with the same message id.
+struct DucoPendingRequest {
+  DucoDevice *device;
+  uint8_t id;
+  uint8_t function;  // 0 while nothing is open
+  bool missed;       // the request before this one got no answer; sits in padding
+};
+
+class Duco : public uart::UARTDevice, public Component {
+ public:
+  void loop() override;
+  void dump_config() override;
+
+  void set_disable_crc(bool disable_crc) { this->disable_crc_ = disable_crc; }
+
+#ifdef DUCO_DEVICE_COUNT
+  void register_device(DucoDevice *device) { this->pending_.push_back({device, 0, 0, false}); }
+#endif
+
+  /// Forget device's open request, for a device that will not send again.
+  void close_request(DucoDevice *device);
+
+  /// Send a request; its answer goes to device, or nowhere if nullptr. A device's new request replaces its
+  /// open one, so an answer is never lost to another device's traffic.
+  void send(DucoDevice *device, uint8_t function, std::initializer_list<uint8_t> data);
+
+ protected:
+  // The longest answer to a request sent here is 25 bytes (node status), the longest request 9
+  static constexpr size_t MAX_FRAME_SIZE = 32;
+  static constexpr size_t MAX_REQUEST_DATA = 9;
+
+  bool parse_byte_(uint8_t byte);
+  void reset_frame_();
+#ifdef DUCO_DEVICE_COUNT
+  void update_warning_();  // warn while any device's previous request went unanswered
+#endif
+  void finalize_message_();
+  uint8_t next_id_();
+
+#ifdef DUCO_DEVICE_COUNT
+  StaticVector<DucoPendingRequest, DUCO_DEVICE_COUNT> pending_;
+#endif
+  std::array<uint8_t, MAX_FRAME_SIZE> rx_buffer_{};
+  uint32_t last_byte_{0};
+  uint8_t rx_size_{0};
+  uint8_t last_id_{10};
+  bool escaped_{false};  // the last 0xAA was followed by a stuffing byte, so it starts no header
+  bool disable_crc_{false};
+};
+
+/// Every entity polls the box; deriving from PollingComponent shares its vtable.
+class DucoDevice : public PollingComponent, public Parented<Duco> {
+ public:
+  virtual void receive_response(const DucoMessage &message) = 0;
+};
+
+/// Walks the node addresses once after boot; the nodes found are listed in the config dump.
+class DucoDiscovery : public DucoDevice {
+ public:
+  void setup() override;
+  void dump_config() override;
+  void update() override;  // one discovery step, run by the step interval
+  void receive_response(const DucoMessage &message) override;
+
+ protected:
+  static constexpr uint8_t NODE_COUNT = 0x45;
+
+  std::array<uint8_t, NODE_COUNT> node_types_{};  // 0 when no node answered at that address
+  uint8_t next_node_{0};
+  uint8_t attempts_{0};
+};
+
+#ifdef USE_TIME
+class DucoTime : public PollingComponent, public Parented<Duco> {
+ public:
+  explicit DucoTime(time::RealTimeClock *clock) : clock_(clock) {}
+  void update() override;
+
+ protected:
+  time::RealTimeClock *clock_;
+};
+#endif
+
+}  // namespace esphome::duco

esphome/components/duco/number/__init__.py

@@ -0,0 +1,34 @@
+from esphome.components import number
+import esphome.config_validation as cv
+from esphome.const import DEVICE_CLASS_TEMPERATURE, UNIT_CELSIUS
+from esphome.types import ConfigType
+
+from .. import (
+    CONF_DUCO_ID,
+    DUCO_COMPONENT_SCHEMA,
+    DucoDevice,
+    duco_ns,
+    register_duco_device,
+)
+
+DEPENDENCIES = ["duco"]
+CODEOWNERS = ["@kokx"]
+
+DucoComfortTemperature = duco_ns.class_(
+    "DucoComfortTemperature", DucoDevice, number.Number
+)
+
+CONFIG_SCHEMA = (
+    number.number_schema(
+        DucoComfortTemperature,
+        unit_of_measurement=UNIT_CELSIUS,
+        device_class=DEVICE_CLASS_TEMPERATURE,
+    )
+    .extend(DUCO_COMPONENT_SCHEMA)
+    .extend(cv.polling_component_schema("60s"))
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    var = await number.new_number(config, min_value=10.0, max_value=25.5, step=0.1)
+    await register_duco_device(var, config, config[CONF_DUCO_ID])

esphome/components/duco/number/number.cpp

@@ -0,0 +1,26 @@
+#include "number.h"
+
+#include <cmath>
+
+namespace esphome::duco {
+
+static constexpr uint8_t PARAMETER_COMFORT_TEMPERATURE = 0x12;
+static constexpr uint8_t GROUP_COMFORT_TEMPERATURE = 0x0a;
+
+void DucoComfortTemperature::update() {
+  this->parent_->send(this, FUNCTION_PARAMETER, {0x00, PARAMETER_COMFORT_TEMPERATURE, GROUP_COMFORT_TEMPERATURE});
+}
+
+void DucoComfortTemperature::receive_response(const DucoMessage &message) {
+  // Reads and writes get the same answer: one byte in tenths of a degree, below 10.0 is invalid
+  if (message.size >= 4 && message.data[3] >= 100)
+    this->publish_state(message.data[3] / 10.0f);
+}
+
+void DucoComfortTemperature::control(float value) {
+  const auto tenths = static_cast<uint8_t>(lroundf(value * 10.0f));
+  this->parent_->send(this, FUNCTION_PARAMETER,
+                      {0x01, PARAMETER_COMFORT_TEMPERATURE, GROUP_COMFORT_TEMPERATURE, tenths, 0x00, 0x00, 0x00});
+}
+
+}  // namespace esphome::duco

esphome/components/duco/number/number.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include "esphome/components/number/number.h"
+
+#include "../duco.h"
+
+namespace esphome::duco {
+
+class DucoComfortTemperature : public DucoDevice, public number::Number {
+ public:
+  void update() override;
+  void receive_response(const DucoMessage &message) override;
+
+ protected:
+  void control(float value) override;
+};
+
+}  // namespace esphome::duco

esphome/components/duco/select/__init__.py

@@ -0,0 +1,45 @@
+from esphome.components import select
+import esphome.config_validation as cv
+from esphome.types import ConfigType
+
+from .. import (
+    CONF_DUCO_ID,
+    DUCO_COMPONENT_SCHEMA,
+    DucoDevice,
+    duco_ns,
+    register_duco_device,
+)
+
+DEPENDENCIES = ["duco"]
+CODEOWNERS = ["@kokx"]
+
+# Same order as MODE_CODES in select.cpp
+DUCO_MODE_OPTIONS = [
+    "AUTO",
+    "MAN1",
+    "MAN2",
+    "MAN3",
+    "EMPT",
+    "CNT1",
+    "CNT2",
+    "CNT3",
+    "MAN1x2",
+    "MAN2x2",
+    "MAN3x2",
+    "MAN1x3",
+    "MAN2x3",
+    "MAN3x3",
+]
+
+DucoSelect = duco_ns.class_("DucoSelect", DucoDevice, select.Select)
+
+CONFIG_SCHEMA = (
+    select.select_schema(DucoSelect)
+    .extend(cv.polling_component_schema("3s"))
+    .extend(DUCO_COMPONENT_SCHEMA)
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    var = await select.new_select(config, options=DUCO_MODE_OPTIONS)
+    await register_duco_device(var, config, config[CONF_DUCO_ID])

esphome/components/duco/select/select.cpp

@@ -0,0 +1,47 @@
+#include "select.h"
+
+#include "esphome/core/hal.h"
+#include "esphome/core/log.h"
+
+namespace esphome::duco {
+
+ESPHOME_LOG_TAG(TAG, "duco.select");
+
+// Box code of each option, in the order of DUCO_MODE_OPTIONS in __init__.py
+static constexpr uint8_t MODE_CODES[] PROGMEM = {
+    0x00,  // AUTO
+    0x04,  // MAN1
+    0x05,  // MAN2
+    0x06,  // MAN3
+    0x07,  // EMPT
+    0x08,  // CNT1
+    0x09,  // CNT2
+    0x0a,  // CNT3
+    0x84,  // MAN1x2
+    0x85,  // MAN2x2
+    0x86,  // MAN3x2
+    0xc4,  // MAN1x3
+    0xc5,  // MAN2x3
+    0xc6,  // MAN3x3
+};
+
+void DucoSelect::update() { this->parent_->send(this, FUNCTION_NODE, {0x02, 0x01}); }
+
+void DucoSelect::receive_response(const DucoMessage &message) {
+  if (message.size < 1)
+    return;
+  for (size_t i = 0; i < sizeof(MODE_CODES); i++) {
+    if (progmem_read_byte(&MODE_CODES[i]) == message.data[0]) {
+      this->publish_state(i);
+      return;
+    }
+  }
+  ESP_LOGV(TAG, "Unknown mode %02X", message.data[0]);
+}
+
+void DucoSelect::control(size_t index) {
+  // The next update reads the new mode back
+  this->parent_->send(nullptr, FUNCTION_NODE, {0x04, 0x01, progmem_read_byte(&MODE_CODES[index])});
+}
+
+}  // namespace esphome::duco

esphome/components/duco/select/select.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include "esphome/components/select/select.h"
+
+#include "../duco.h"
+
+namespace esphome::duco {
+
+class DucoSelect : public DucoDevice, public select::Select {
+ public:
+  void update() override;
+  void receive_response(const DucoMessage &message) override;
+
+ protected:
+  void control(size_t index) override;
+};
+
+}  // namespace esphome::duco

esphome/components/duco/sensor/__init__.py

@@ -0,0 +1,156 @@
+from esphome.components import sensor
+import esphome.config_validation as cv
+from esphome.const import (
+    CONF_ADDRESS,
+    CONF_CO2,
+    CONF_HUMIDITY,
+    CONF_TEMPERATURE,
+    DEVICE_CLASS_CARBON_DIOXIDE,
+    DEVICE_CLASS_DURATION,
+    DEVICE_CLASS_HUMIDITY,
+    DEVICE_CLASS_TEMPERATURE,
+    STATE_CLASS_MEASUREMENT,
+    UNIT_CELSIUS,
+    UNIT_PARTS_PER_MILLION,
+    UNIT_PERCENT,
+    UNIT_SECOND,
+)
+from esphome.types import ConfigType
+
+from .. import (
+    CONF_DUCO_ID,
+    DUCO_COMPONENT_SCHEMA,
+    DucoDevice,
+    duco_ns,
+    register_duco_device,
+)
+
+DEPENDENCIES = ["duco"]
+CODEOWNERS = ["@kokx"]
+
+UNIT_DAYS = "d"
+
+CONF_BYPASS = "bypass"
+CONF_FILTER_REMAINING = "filter_remaining"
+CONF_FLOW_LEVEL = "flow_level"
+CONF_TEMPERATURE_EHA = "temperature_eha"
+CONF_TEMPERATURE_ETA = "temperature_eta"
+CONF_TEMPERATURE_ODA = "temperature_oda"
+CONF_TEMPERATURE_SUP = "temperature_sup"
+CONF_TIME_REMAINING = "time_remaining"
+
+DucoSensor = duco_ns.class_("DucoSensor", DucoDevice, sensor.Sensor)
+DucoReading = duco_ns.enum("DucoReading", is_class=True)
+
+BOX_NODE = 1
+
+
+def _schema(update_interval: str = "60s", **kwargs) -> cv.Schema:
+    return sensor.sensor_schema(
+        DucoSensor, state_class=STATE_CLASS_MEASUREMENT, **kwargs
+    ).extend(cv.polling_component_schema(update_interval))
+
+
+def _node_schema(**kwargs) -> cv.All:
+    """A list of sensors, one per node address."""
+    return cv.ensure_list(
+        _schema(**kwargs).extend({cv.Required(CONF_ADDRESS): cv.int_range(0, 68)})
+    )
+
+
+_TEMPERATURE = {
+    "unit_of_measurement": UNIT_CELSIUS,
+    "accuracy_decimals": 1,
+    "device_class": DEVICE_CLASS_TEMPERATURE,
+}
+
+# key: (what is read, request argument or None for the node address, schema)
+SENSORS = {
+    CONF_CO2: (
+        DucoReading.DUCO_READING_CO2,
+        None,
+        _node_schema(
+            unit_of_measurement=UNIT_PARTS_PER_MILLION,
+            accuracy_decimals=0,
+            device_class=DEVICE_CLASS_CARBON_DIOXIDE,
+        ),
+    ),
+    CONF_TEMPERATURE: (
+        DucoReading.DUCO_READING_NODE_TEMPERATURE,
+        None,
+        _node_schema(**_TEMPERATURE),
+    ),
+    CONF_HUMIDITY: (
+        DucoReading.DUCO_READING_HUMIDITY,
+        None,
+        _node_schema(
+            unit_of_measurement=UNIT_PERCENT,
+            accuracy_decimals=1,
+            device_class=DEVICE_CLASS_HUMIDITY,
+        ),
+    ),
+    CONF_FILTER_REMAINING: (
+        DucoReading.DUCO_READING_FILTER_REMAINING,
+        0x30,
+        _schema(
+            "1200s",
+            unit_of_measurement=UNIT_DAYS,
+            accuracy_decimals=0,
+            device_class=DEVICE_CLASS_DURATION,
+        ),
+    ),
+    CONF_FLOW_LEVEL: (
+        DucoReading.DUCO_READING_FLOW_LEVEL,
+        BOX_NODE,
+        _schema(unit_of_measurement=UNIT_PERCENT, accuracy_decimals=0),
+    ),
+    CONF_TIME_REMAINING: (
+        DucoReading.DUCO_READING_TIME_REMAINING,
+        BOX_NODE,
+        _schema(
+            unit_of_measurement=UNIT_SECOND,
+            accuracy_decimals=0,
+            device_class=DEVICE_CLASS_DURATION,
+        ),
+    ),
+    CONF_TEMPERATURE_ODA: (
+        DucoReading.DUCO_READING_BOX_TEMPERATURE,
+        0x00,
+        _schema(**_TEMPERATURE),
+    ),
+    CONF_TEMPERATURE_SUP: (
+        DucoReading.DUCO_READING_BOX_TEMPERATURE,
+        0x01,
+        _schema(**_TEMPERATURE),
+    ),
+    CONF_TEMPERATURE_ETA: (
+        DucoReading.DUCO_READING_BOX_TEMPERATURE,
+        0x02,
+        _schema(**_TEMPERATURE),
+    ),
+    CONF_TEMPERATURE_EHA: (
+        DucoReading.DUCO_READING_BOX_TEMPERATURE,
+        0x03,
+        _schema(**_TEMPERATURE),
+    ),
+    CONF_BYPASS: (
+        DucoReading.DUCO_READING_BYPASS,
+        0x10,
+        _schema(unit_of_measurement=UNIT_PERCENT, accuracy_decimals=0),
+    ),
+}
+
+CONFIG_SCHEMA = DUCO_COMPONENT_SCHEMA.extend(
+    {cv.Optional(key): schema for key, (_, _, schema) in SENSORS.items()}
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    for key, (reading, argument, _) in SENSORS.items():
+        if (confs := config.get(key)) is None:
+            continue
+        for conf in confs if isinstance(confs, list) else [confs]:
+            var = await sensor.new_sensor(
+                conf, reading, conf.get(CONF_ADDRESS, argument)
+            )
+            await register_duco_device(var, conf, config[CONF_DUCO_ID])

esphome/components/duco/sensor/sensor.cpp

@@ -0,0 +1,78 @@
+#include "sensor.h"
+
+#include "esphome/core/hal.h"
+#include "esphome/core/log.h"
+
+namespace esphome::duco {
+
+ESPHOME_LOG_TAG(TAG, "duco.sensor");
+
+enum class DucoValueFormat : uint8_t {
+  DUCO_VALUE_FORMAT_UINT8,
+  DUCO_VALUE_FORMAT_UINT16,
+  DUCO_VALUE_FORMAT_INT16,
+};
+
+/// A little endian field at offset in the answer. Values outside [minimum, maximum] are dropped;
+/// the box reports those for sensors that are missing or still starting.
+struct ReadingLayout {
+  uint8_t function;
+  uint8_t offset;
+  DucoValueFormat format;
+  uint8_t divisor;
+  int16_t minimum;
+  uint16_t maximum;
+};
+
+// Indexed by DucoReading
+static constexpr ReadingLayout READINGS[] PROGMEM = {
+    {FUNCTION_NODE_DATA, 4, DucoValueFormat::DUCO_VALUE_FORMAT_UINT16, 1, 300, 10000},  // CO2
+    {FUNCTION_NODE_DATA, 2, DucoValueFormat::DUCO_VALUE_FORMAT_UINT16, 10, 0, 1000},    // node temperature
+    {FUNCTION_NODE_DATA, 6, DucoValueFormat::DUCO_VALUE_FORMAT_UINT16, 100, 0, 10000},  // humidity
+    {FUNCTION_PARAMETER, 3, DucoValueFormat::DUCO_VALUE_FORMAT_UINT8, 1, 0, 255},       // filter remaining
+    {FUNCTION_NODE, 2, DucoValueFormat::DUCO_VALUE_FORMAT_UINT8, 1, 0, 255},            // flow level
+    {FUNCTION_NODE, 12, DucoValueFormat::DUCO_VALUE_FORMAT_UINT16, 1, 0, 65535},        // time remaining
+    {FUNCTION_PARAMETER, 3, DucoValueFormat::DUCO_VALUE_FORMAT_INT16, 10, -999, 1000},  // box temperature
+    {FUNCTION_PARAMETER, 3, DucoValueFormat::DUCO_VALUE_FORMAT_UINT8, 1, 0, 100},       // bypass
+};
+
+static ReadingLayout layout_of(DucoReading reading) {
+  ReadingLayout layout;
+  progmem_memcpy(&layout, &READINGS[static_cast<uint8_t>(reading)], sizeof(layout));
+  return layout;
+}
+
+void DucoSensor::update() {
+  switch (layout_of(this->reading_).function) {
+    case FUNCTION_NODE_DATA:
+      this->parent_->send(this, FUNCTION_NODE_DATA, {0x01, this->argument_, 0x00, 0x49, 0x04});
+      break;
+    case FUNCTION_PARAMETER:
+      this->parent_->send(this, FUNCTION_PARAMETER, {0x00, this->argument_, 0x09});
+      break;
+    case FUNCTION_NODE:
+      this->parent_->send(this, FUNCTION_NODE, {0x02, this->argument_});
+      break;
+  }
+}
+
+void DucoSensor::receive_response(const DucoMessage &message) {
+  const ReadingLayout layout = layout_of(this->reading_);
+  const bool wide = layout.format != DucoValueFormat::DUCO_VALUE_FORMAT_UINT8;
+  if (message.size < layout.offset + (wide ? 2 : 1)) {
+    ESP_LOGV(TAG, "Answer of %u bytes is too short", message.size);
+    return;
+  }
+
+  const uint8_t *field = message.data + layout.offset;
+  int32_t value = field[0];
+  if (layout.format == DucoValueFormat::DUCO_VALUE_FORMAT_UINT16) {
+    value = encode_value_le<uint16_t>(field);
+  } else if (layout.format == DucoValueFormat::DUCO_VALUE_FORMAT_INT16) {
+    value = encode_value_le<int16_t>(field);
+  }
+  if (value >= layout.minimum && value <= layout.maximum)
+    this->publish_state(static_cast<float>(value) / layout.divisor);
+}
+
+}  // namespace esphome::duco

esphome/components/duco/sensor/sensor.h

@@ -0,0 +1,34 @@
+#pragma once
+
+#include "esphome/components/sensor/sensor.h"
+
+#include "../duco.h"
+
+namespace esphome::duco {
+
+/// What a sensor reads; the request and where the value is in the answer are in READINGS in sensor.cpp.
+enum class DucoReading : uint8_t {
+  DUCO_READING_CO2,
+  DUCO_READING_NODE_TEMPERATURE,
+  DUCO_READING_HUMIDITY,
+  DUCO_READING_FILTER_REMAINING,
+  DUCO_READING_FLOW_LEVEL,
+  DUCO_READING_TIME_REMAINING,
+  DUCO_READING_BOX_TEMPERATURE,
+  DUCO_READING_BYPASS,
+};
+
+class DucoSensor : public DucoDevice, public sensor::Sensor {
+ public:
+  /// argument is the node address, or the parameter number for a box parameter.
+  DucoSensor(DucoReading reading, uint8_t argument) : reading_(reading), argument_(argument) {}
+
+  void update() override;
+  void receive_response(const DucoMessage &message) override;
+
+ protected:
+  DucoReading reading_;
+  uint8_t argument_;
+};
+
+}  // namespace esphome::duco

esphome/components/duco/text_sensor/__init__.py

@@ -0,0 +1,27 @@
+from esphome.components import text_sensor
+import esphome.config_validation as cv
+from esphome.types import ConfigType
+
+from .. import (
+    CONF_DUCO_ID,
+    DUCO_COMPONENT_SCHEMA,
+    DucoDevice,
+    duco_ns,
+    register_duco_device,
+)
+
+DEPENDENCIES = ["duco"]
+CODEOWNERS = ["@kokx"]
+
+DucoSerial = duco_ns.class_("DucoSerial", DucoDevice, text_sensor.TextSensor)
+
+CONFIG_SCHEMA = (
+    text_sensor.text_sensor_schema(DucoSerial)
+    .extend(cv.polling_component_schema("300s"))
+    .extend(DUCO_COMPONENT_SCHEMA)
+)
+
+
+async def to_code(config: ConfigType) -> None:
+    var = await text_sensor.new_text_sensor(config)
+    await register_duco_device(var, config, config[CONF_DUCO_ID])

esphome/components/duco/text_sensor/serial.cpp

@@ -0,0 +1,17 @@
+#include "serial.h"
+
+#include <cstring>
+
+namespace esphome::duco {
+
+void DucoSerial::update() { this->parent_->send(this, FUNCTION_NODE_DATA, {0x01, 0x01, 0x00, 0x1a, 0x10}); }
+
+void DucoSerial::receive_response(const DucoMessage &message) {
+  if (message.size > 2) {
+    // The serial number starts at byte 2 and is padded with zeros
+    const char *serial = reinterpret_cast<const char *>(message.data + 2);
+    this->publish_state(serial, strnlen(serial, message.size - 2));
+  }
+}
+
+}  // namespace esphome::duco

esphome/components/duco/text_sensor/serial.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include "esphome/components/text_sensor/text_sensor.h"
+
+#include "../duco.h"
+
+namespace esphome::duco {
+
+class DucoSerial : public DucoDevice, public text_sensor::TextSensor {
+ public:
+  void update() override;
+  void receive_response(const DucoMessage &message) override;
+};
+
+}  // namespace esphome::duco

esphome/components/ecocomfort2/ecocomfort2_fan.cpp

@@ -1,5 +1,5 @@
 #include "esphome/core/defines.h"
-#ifdef USE_ESP32
+#if defined(USE_ESP32) && defined(USE_FAN)
 #include "ecocomfort2_fan.h"
 #include "esphome/core/log.h"
 
@@ -138,4 +138,4 @@ void Ecocomfort2Fan::on_status() {
 
 }  // namespace esphome::ecocomfort2
 
-#endif  // USE_ESP32
+#endif  // USE_ESP32 && USE_FAN