Derive the ltr390 resolution values and keep the gains in flash

# Conflicts:
#	esphome/components/ltr390/ltr390.cpp

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

@@ -15,19 +15,26 @@ driven, what the logs show, and the same flow on a `dev` build when a quirk coul
 1. **Serial ports cannot be shared.** One bounded capture per port, stopped before any flash on that
    port, never an open-ended `esphome logs`. Stop a capture with `pkill -f "[s]erial_capture.py <port> "`,
    naming the port so a capture on another board survives; the bracket keeps the pattern from matching
-   the shell that runs it. Never run `esphome logs` in a
-   `while true` loop: the loop respawns it and holds the port.
+   the shell that runs it. When more than one agent session shares the bench, run a copy of the script
+   under a session-specific name (`cap<topic>.py`) so another session's `pkill` cannot take your capture
+   down. Never run `esphome logs` in a `while true` loop: the loop respawns it and holds the port.
 2. **Credentials stay local.** Put a `secrets.yaml` next to the scratch configs and reference it with
-   `!secret`. Never paste a config with credentials into a PR, never commit scratch configs or logs.
+   `!secret`. A copy of a device's own config keeps using the secrets file next to that config: two
+   checkouts can hold different networks, and the wrong one leaves the device unreachable after the OTA. Never paste a config with credentials into a PR, never commit scratch configs or logs.
 3. **Build from the tree under test.** `python -m esphome` puts the current directory first on
    `sys.path`, so run it with the checkout or worktree as the working directory and pass the yaml by
    its absolute path. A venv `esphome` entry point may import an installed snapshot instead of the
    checkout. Confirm with `python -c 'import esphome; print(esphome.__file__)'`, and for an A/B grep
-   the build's `src/` for the change before trusting any number.
+   the build's `src/` for the change before trusting any number. Tool calls sent together share one
+   shell, so a `cd` in one can land another's compile in the wrong tree: pass `PYTHONPATH=<worktree>` on
+   every compile and upload command and print `esphome.__file__` into the compile log.
 4. **PR build and baseline build get different `name:` values.** Builds share
    `.esphome/build/<name>`, so the same name means `esphome upload` can flash the wrong binary. Saved
-   Wi-Fi credentials are keyed by the name too, so a test that must start unprovisioned gets a fresh
-   name every run.
+   Wi-Fi credentials are keyed by the config hash when the config has `networks:`, so a test that must
+   start unprovisioned gets a fresh name every run. A config with `ap:` only and no `networks:` uses one
+   fixed key shared by every such config on the board, so a new name does not help there: wipe once at
+   boot with an `on_boot` lambda that resets the preferences and saves a marker key
+   (`templates/dut-ap-only-wipe-once-bk72xx.yaml`).
 5. **Flash and RAM deltas are measured against the PR's merge base** (`git merge-base origin/dev HEAD`
    checked out in a throwaway worktree), with the baseline commit named in the table. When a delta
    looks odd, diff symbol sizes (`nm -S -C --size-sort` from the matching toolchain) before quoting it.
@@ -73,7 +80,7 @@ driven, what the logs show, and the same flow on a `dev` build when a quirk coul
 | ESP32-S3, C3, C6, H2 native USB | `esphome upload --device /dev/cu.usbmodem*` | `logger: hardware_uart: USB_SERIAL_JTAG`. The USB console can wedge when the app takes over the console (0 bytes, esptool `No serial data received`); replug, or watch through `esphome logs --device <name>.local` |
 | Pico W / Pico 2 W | `esphome upload --device <port>` (1200 baud touch); first flash ever via BOOTSEL and `--device /Volumes/RPI-RP2` or `RP2350` | port re-enumerates after upload: `ports.py --wait 2e8a` then capture |
 | BW15 kit (RTL8720CF, rtl87xx) | `~/.platformio/penv/.libretiny/bin/python $SKILL/scripts/flash_rtl87xx_kit.py flash write -d <port> <build>/.pioenvs/<name>/*.uf2`. Plain `esphome upload` and plain ltchiptool time out because opening the port asserts DTR/RTS and holds the chip in reset | `serial_capture.py --released`, never `esphome logs` |
-| BK7238 / CB3S (bk72xx, RTS on CEN) | `~/.platformio/penv/.libretiny/bin/python $SKILL/scripts/flash_bk72xx.py flash write -d <port> <uf2>` (about 75 s) | logs are on UART2 by default; `logger: hardware_uart: UART1` puts them on the flashing adapter. Opening the port resets the chip, so keep one capture open for the whole test |
+| BK7238 / CB3S (bk72xx, RTS on CEN) | `~/.platformio/penv/.libretiny/bin/python $SKILL/scripts/flash_bk72xx.py flash write -d <port> <uf2>` (about 75 s) | logs are on UART2 by default; `logger: hardware_uart: UART1` puts them on the flashing adapter. `serial_capture.py --reset` gives a chip-enable reset; a plain open may or may not reset it, check for the bootloader banner |
 | LN882H | ltchiptool forces 1 Mbaud for writes; weak adapters need `LN882H_YM_BAUDRATE` patched to 115200 in the penv's `ln882htool.py`; short BOOT to GND while the tool connects | OTA after the first flash |
 | nRF52840 Dongle (PCA10059) | Nordic `nrfutil nrf5sdk-tools dfu usb-serial` on the bootloader port, or `dfu: true` in the config so the 1200 baud touch pin-resets into the bootloader; adafruit-nrfutil is refused | app has two CDC ports, ESPHome log on the second |
 | Adafruit-style nRF52 (UF2 bootloader) | `UF2BOOT` volume or adafruit-nrfutil; `dfu: true` works through GPREGRET | single CDC port |
@@ -86,12 +93,15 @@ ESP-IDF OTA image: `.esphome/build/<name>/build/firmware.ota.bin`. LibreTiny OTA
 - `ports.py`: list ports with VID:PID, product, serial and a board guess; `--wait VID[:PID]`,
   `--product NAME`, `--serial SN` (one specific board, whatever path it comes back under) and
   `--serial-of PORT` (the serial number behind a path).
-- `serial_capture.py PORT SECONDS OUT [--baud] [--released] [--reset] [--append]`: bounded timestamped
-  capture, ANSI stripped, `LOG_SECRET` text written as `<secret>`, reopens a vanished port, exits at the
+- `serial_capture.py PORT SECONDS OUT [--baud] [--released] [--reset] [--append] [--ms]`: bounded timestamped
+  capture (`--ms` adds milliseconds for timing work), ANSI stripped, `LOG_SECRET` text written as `<secret>`, reopens a vanished port, exits at the
   deadline. OUT is truncated unless `--append` is given, so counts over it cover one run.
 - `flash_rtl87xx_kit.py`: ltchiptool wrapper for the BW15 kit whose CH340 drives CEN (RTS) and the boot
   strap (DTR). `flash read` needs the family `realtek-ambz2`; `flash write` does not.
-- `flash_bk72xx.py`: ltchiptool wrapper for BK72xx boards whose RTS drives CEN.
+- `flash_bk72xx.py`: ltchiptool wrapper for BK72xx boards whose RTS drives CEN. It misses the link now
+  and then; retry up to three times.
+- `api_button.py HOST KEY list|press NAME [...]`: list a device's template buttons or press them over the API; the
+  recipes drive their test configs with it.
 - `wifisave_hammer.sh KIND DUT_PORT DUT_YAML DUT_TREE CLIENT_PORT CLIENT_YAML CLIENT_TREE [SETTLE]`:
   the fallback AP plus captive portal hammer end to end (compile, flash, capture, counts) with the
   templates below. KIND is `esp`, `pico`, `bw15` or `bk`. It ends with `RESULT PASS` (exit 0),
@@ -100,6 +110,13 @@ ESP-IDF OTA image: `.esphome/build/<name>/build/firmware.ota.bin`. LibreTiny OTA
   (exit 2: a precondition was missed, the stimulus was insufficient, or a capture did not last the run)
   or exits 1 when a build, flash or port step failed.
 
+Per-topic scripts, each described in the matching `reference/recipes/<component>.md`: `online_image/`
+(server, image generator, API driver), `zwave_proxy/` (checksum verifier, device info), `usb_cdc_acm/`
+(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).
+
 ## Templates in `$SKILL/templates`
 
 - `dut-fallback-ap.yaml` (package): a device that never finds its network, falls back to its AP and
@@ -107,17 +124,29 @@ ESP-IDF OTA image: `.esphome/build/<name>/build/firmware.ota.bin`. LibreTiny OTA
 - `client-wifisave.yaml` (package): joins that AP, posts N bogus `/wifisave` requests, then the real
   credentials from `!secret`. `example-client.yaml` is the per-run file. `bogus_saves: "1"` gives a
   plain provisioning check.
+- Per-topic device configs, each described in `reference/recipes/<component>.md`: `online-image-dut.yaml`,
+  `usb-cdc-acm-dongle-dut.yaml`, `nrf52-preferences-dut.yaml`, `rtsp-waveshare-s3-eth-dut.yaml`,
+  `waveshare-s3-eth-camdiag.yaml`, `s31-cse7766-dut.yaml`, `nrf52-coredump-crash-dut.yaml`,
+  `bk72xx-rtc-prefs-dut.yaml`, `bk72xx-crash-probe-dut.yaml`, `dut-ap-only-wipe-once-bk72xx.yaml`,
+  `homeassistant-light-dut.yaml`, `deep-sleep-outgoing-dut.yaml`, `outgoing-wifi-drop-dut.yaml`,
+  `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`.
 
 ## When something looks wrong
 
 - A capture stopped early or a line is missing: check the timestamps before trusting it.
 - The client never joins the AP: another board may still run an AP with the same SSID, or the device
   booted with saved credentials because the name was reused. One AP device at a time on the bench.
-- Builds come out byte-identical between branches: the wrong tree was imported (rule 3).
+- Builds come out byte-identical between branches: the wrong tree was imported (rule 3). The reverse
+  too: two binaries that differ only in the build timestamp and in `__LINE__` values of log calls below
+  the changed code are the same build; map the offsets with `objdump -h` and `addr2line` first.
+- A boot the host cannot capture (a power cut, an OTA-only board): keep the boot report in a flash
+  preference and repeat it in a periodic alive line, as `scripts/libretiny_prefs/ltprefs.hpp` does.
 - Multicast from the host never arrives on some access points: test it device to device. Broadcast
   is lossy under Wi-Fi power save, unicast is not. Throttle UDP floods to a fixed packet rate.
 - `api:` reboots a board after 15 min without a client: `reboot_timeout: 0s` on `api:` and `mqtt:` for
   soak tests.
 
-`reference/boards.md` has per-chip facts and crash decoding; `reference/recipes.md` has the proven
+`reference/boards.md` has per-chip facts and crash decoding; `reference/recipes/` has the proven
 flows. Add new findings there.

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

@@ -88,8 +88,28 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
   pulses the reset right before the link checks. A write takes about 75 s. Only a CEN or power reset
   reaches the downloader; no software reboot does.
 - ESPHome logs on UART2 by default; `logger: hardware_uart: UART1` puts them on the flashing adapter.
-- Opening the port resets the chip (bootloader banner on every open, even with DTR/RTS low), so keep one
-  capture open for the whole test and never reopen mid-phase.
+- Opening the port may reset the chip (bootloader banner on open) or may not, depending on the adapter and
+  what pyserial does with DTR and RTS; `serial_capture.py --reset` pulses RTS on CEN and always does, and
+  `lt_get_reboot_reason()` reports that as Power-On. Check for the banner at the start of a capture before
+  assuming either.
+- `flash_bk72xx.py` misses the link now and then (`Timed out attempting to link with chip`); retry up to 3
+  times before suspecting the board.
+- Crashes: `__builtin_trap()` and a call into unmapped memory both end as an undefined-instruction trap
+  (`bk_misc_get_start_type()` 6, `lt_get_reboot_reason()` Crash); reads, unaligned loads and stores to
+  unmapped addresses never fault on the ARM968. Without Wi-Fi the SDK trap handler spins with interrupts off
+  for 10 s and the hardware watchdog resets the chip. With Wi-Fi connected a dev build hangs forever after a
+  crash, and never resets from a plain `portDISABLE_INTERRUPTS(); while (1) {}` either: the boot-time
+  watchdog is dead once Wi-Fi is up, for any lockup. The crash handler fix (#21012) re-arms the watchdog
+  from its wrapper, after which the reboot comes within a second (BK7238 and BK7231N).
+- The SDK prints nothing on UART1 under `sdk_silent: all`; the bootloader then prints the banked
+  `cpsr/spsr/r13/r14` of SVC, IRQ, FIQ and SYS plus `ST:` (the retention register) before `go os_addr`.
+  A CEN or power reset wipes ITCM (reads `0xaaaaaaaa`), so only a watchdog reset keeps a record there. What
+  survives that reboot on the BK7238: ITCM (`0x3F0000..0x3F4000`) and the top 96 KB of SRAM
+  (`0x428000..0x440000`, the heap); the bootloader zeroes SRAM up to about `0x420000` and rewrites
+  `0x400024..0x4000FF` with its own register dump every boot, so neither a `.noinit` after `.bss` nor the
+  SDK's saved register banks are usable. Code is compiled Thumb, the SDK assembly is ARM; in an exception
+  handler only r0 to r3 are shared by all modes. BK7231N ITCM is `0x3FEE00..0x400000` (4.5 KB); a `.noinit`
+  placed there after `.itcm.code` works for a crash record.
 - Callbacks run on the `async_tcp` task and log lines can lose a byte. Wi-Fi connect takes tens of ms;
   radio enable 160 to 278 ms, disable about 200 ms.
 
@@ -123,6 +143,38 @@ Ports are not listed on purpose: they follow the USB hub port and change on ever
 - Makerdiary MDK USB dongle: UF2 bootloader without SoftDevice, app at 0x1000, `UF2BOOT` volume,
   adafruit-nrfutil, GPREGRET 0x57 works. RGB LED active low (red P0.23, green P0.22, blue P0.24),
   button P0.18.
+- Adafruit ItsyBitsy nRF52840 Express (UF2 bootloader with S140, bootloader port `239a:0051` plus an
+  `ITSY840BOOT` volume): the board DTS already has `cdc_acm_uart0`, so the logger port is the first CDC
+  port and a `usb_cdc_acm` interface 1 the second. A `dfu: true` build enters the bootloader on the
+  1200 bps touch (an app without it needs a double tap on RESET); `adafruit-nrfutil` over the bootloader
+  serial port can fail, copying `.pioenvs/<name>/zephyr/zephyr.uf2` to the volume works (the copy reports
+  an I/O error as the board reboots, which is normal). Reboot a running `dfu: true` app with a 2001 bps touch.
+- The PCA10059 board DTS already defines a `cdc_acm_uart` node, so every ESPHome CDC port is one USB port
+  later than its number (log on `cdc_acm_uart0` is the second port). A third CDC instance needs
+  `CONFIG_USB_MAX_NUM_TRANSFERS` above 4 or it never moves data (see `recipes/usb_cdc_acm.md`).
+- USB CDC boot output: the Zephyr legacy stack's `cdc_acm` TX ring is 1 KB and `uart_poll_out` drops when it
+  is full, so anything printed in one burst beyond about 1 KB (a coredump, a long table) is lost even with
+  the port open, and the logger warns `logger took a long time`. Print one line per `loop()` instead.
+- Zephyr settings survive a reflash: key a `restore_value` global by a `run` substitution when a test needs
+  a never-saved value.
+
+## Waveshare ESP32-S3-ETH with the OV5640 camera module
+
+- Native USB console (`303a:1001`), ESP32-S3R8, 16 MB flash, 8 MB octal PSRAM, W5500 on SPI (MOSI 11,
+  MISO 12, SCLK 13, CS 14, INT 10, RST 9), TF card on 4..7, WS2812 on 21.
+- Camera header (vendor schematic): XCLK 3, SIOD 48, SIOC 47, VSYNC 1, HREF 2, PCLK 39, D0..D7 = 41, 45,
+  46, 42, 40, 38, 15, 18. PWDN is tied to GND and RESET is an RC to 3.3 V on the board, so no reset or
+  power-down GPIO exists.
+- GPIO8 switches the camera 3.3 V rail through a P-channel MOSFET: LOW = camera powered, gate pulled up so
+  the camera is off by default. `power_down_pin: GPIO8` only pulls it low 10 ms before the probe, which is
+  not enough; use `switch: gpio GPIO8 restore_mode: ALWAYS_OFF setup_priority: 800` plus `on_boot:
+  priority: 700` with `delay(1200)` and `esp32_camera: setup_priority: 200`
+  (`templates/rtsp-waveshare-s3-eth-dut.yaml`). `esphome config` rejects a config that uses GPIO8 for both the switch
+  and `power_down_pin` (pin reuse), so it is one or the other.
+- The sensor at SCCB 0x3C answers only with XCLK running, so the ESPHome i2c scan at boot (before XCLK)
+  reporting no devices on 48/47 is expected. If the SCCB ID register (0x3100 = 0x78) reads fine but every
+  0x30xx register reads 0x00 (`Detected camera not supported`, 0x106), reseat the ribbon before blaming
+  software; `templates/waveshare-s3-eth-camdiag.yaml` runs that probe with LEDC XCLK and raw SCCB reads.
 
 ## ESP Thread Border Router board v1.2 (S3 host + H2 RCP)
 

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

@@ -1,117 +0,0 @@
-# Proven test flows
-
-Each flow names the pull requests it was used on, so their result tables show what to post.
-
-## Captive portal `/wifisave` hammer (#20802, #20784)
-
-Reproduces a `/wifisave` arriving during the STA cooldown, and proves a fix on every board.
-Device under test: `templates/example-dut.yaml` (bogus network, `ap:` with `ap_timeout: 15s`,
-`captive_portal:`). Client: `templates/example-client.yaml` on an ESP32 or a D1 mini; it joins the
-device's AP, posts 15 bogus saves 3 s apart, then the real credentials. With the portal up the cooldown
-is 30 s, so nearly every save lands inside one. Driver: `scripts/wifisave_hammer.sh`. Settle 40 s on
-ESP boards, 90 s on the BW15 (its first attempt on the real network fails, see boards.md).
-
-Counts that matter: `Requested WiFi Settings Change` (saves received), `Exiting cooldown early`, crash
-markers, boots (`Log initialized`), and the client's `bogus save status 200` and `real save status 200`.
-A healthy run: every save answered 200, one cooldown exit per save (two on the BW15, whose retry enters
-the adapter restart), no panic, and the real credentials connect the device within about 10 s.
-
-Fault injection for AP start failures: wrap `this->ap_setup_ = this->wifi_start_ap_(this->ap_)` in
-`setup_ap_config_()` with an `HWTEST_AP_FAIL_COUNT` build flag
-(`esphome: platformio_options: build_flags: -DHWTEST_AP_FAIL_COUNT=2`), raise the portal's "Captive
-portal started" from LOGV to LOGI, and after provisioning curl the device's STA address: connection
-refused proves the portal's server is gone.
-
-## `reboot_timeout` with a fallback AP (#9958)
-
-Only one board runs the AP at a time, or stations join the wrong one. AP probe: bogus network,
-`ap: {ssid, password, ap_timeout: 5s}`, `reboot_timeout: 60s`, `logger: level: VERBOSE` (ESP32 and
-ESP8266 log `AP client connected MAC=` at verbose), `on_boot: logger.log: BOOT`. Station probes:
-`reboot_timeout: 0s`, `interval: 150s` running `wifi.disable`, `delay: 20s`, `wifi.enable` (60 s cycles
-are too short to cover the due moment). Pass pattern: "Can't connect; rebooting" exactly 60 s after boot
-with no station joined, no reboot for minutes while one is, then a reboot within a second of the last
-disconnect. The BW15 restarts its AP on every STA retry and cannot be tested this way.
-
-## MQTT (#20433, #17935, #20762, #20767, #20768)
-
-A local mosquitto with `allow_anonymous true`, `log_type all` and `log_dest file`: the broker log gives
-each subscription's QoS, the device address (`New client connected from <ip> as <name>-<mac>`) and exact
-subscribe counts. Kill and restart mosquitto to exercise `on_disconnect` (reason 0) and resubscription.
-Keep `reboot_timeout: 0s` on `api:` and `mqtt:`. The ESP-IDF outbox swings free heap about 2 kB right
-after bulk subscribe and unsubscribe; read the heap seconds later over several rounds before calling a
-leak. Spawned subscriptions need about 2.5 s to reach the broker before the next publish.
-`esphome logs --device MQTT` only uses the MQTT transport when the config has no `api:`. Driver pattern: a
-paho script publishes and polls the serial capture file.
-
-## UDP, multicast, sockets (#20556 to #20559, #20585, #20590)
-
-A listener on port 9 needs no privileges on macOS. Test multicast device to device; host to device
-multicast never arrives on some access points, and `239.255.x.x` groups are unreliable even to a stock
-listener. Broadcast to boards is lossy under power save, unicast is not. Flood at a fixed packet rate
-(the host hits `ENOBUFS` unthrottled); 1500 packets per second survived on every board. A forced Wi-Fi
-reconnect on the Pico keeps IGMP membership. Set a long loop interval from `wifi.on_connect`
-(`App.set_loop_interval(20000)`), not `on_boot`, or Wi-Fi connect crawls. The `logger.log` action
-rejects `%.*s`; use a lambda.
-
-## OTA overlap and lock (#20588), OTA timeouts (#19041), deflate (#19037)
-
-All overlap orders (a web upload during a native OTA and the reverse) must be refused; the lock release
-after an interrupted web upload waits about 14 s (ESP8266) or 7 s (ESP-IDF) for disconnect detection. A
-refused web client on `web_server_idf` never gets the busy reply; the connection drops at reboot.
-`pkill -f "a\|b"` does not alternate; use two pkills.
-
-## DHCP lease cache (#17767)
-
-Cycle 20 s awake, `deep_sleep.enter 30s`, wake, 20 s, `App.safe_reboot()`, logging `millis()` at the
-`wifi.connected` condition. An RTS hardware reset must fall back to DHCP; a software reboot and a deep
-sleep wake must apply the cache. `esphome run --no-logs` silently skipped the upload on one board; use
-`upload` then `logs`.
-
-## HDMI-CEC two-board wire (#9189)
-
-Two boards on one wire: promiscuous mode, a 0x8F request answered with 0x90 0x00, a `destination:`
-filter on the reply handler, template buttons for each target plus lambdas calling
-`send(source, dest, span)` as another initiator. Healthy numbers: device-side turnaround 15 to 22 ms,
-round trip 144 to 156 ms. Press buttons over the API; judge timings from device logs (ESP32 light sleep
-lags the press).
-
-## LD2450 polygon zones (#20154)
-
-To make a target "leave" without anyone moving, set the radar's Zone-1 numbers over the target and
-switch the zone type to `Filter` (the count drops to 0 within 0.5 s); set it back to `Disabled` after.
-Writing those numbers blocks the ld2450 loop about 50 ms.
-
-## Scheduler and loop wake A/B (#20356)
-
-An external component whose template button arms an SDK `os_timer` (50 ms, one shot) on the ESP8266;
-the callback runs in SYS context, records `millis()` and calls `set_timeout` or `defer`; the timeout
-logs the elapsed time and loop count delta. Drive with an aioesphomeapi script (`subscribe_logs` plus
-`button_command`). Build the same yaml twice with different names, one per tree.
-
-## Noise handshake and OTA encryption on the ESP8266 (#19062, #19233)
-
-Host side timing is useless on a weak link; use an on-device bench with the minimum of five runs over
-two boots. Provision a key with `noise_encryption_set_key` through aioesphomeapi and upload with
-`espota2.run_ota(host, 8266, None, bin, noise_psk=key)` when the key is not in the yaml.
-
-## ESP-NOW on the ESP8266 (#14407)
-
-The NONOS SDK only delivers broadcast ESP-NOW frames while the station is associated or a soft-AP is
-up; a hidden, open, client-less soft-AP (60 s beacon, DHCP stopped) makes broadcasts arrive. In AP-only
-mode the device transmits from the soft-AP MAC.
-
-## Wi-Fi Easy Connect (DPP) enrollee (#17934)
-
-Only an Android phone configures: Settings, network details, Add device, Share Wi-Fi (the Wi-Fi list's
-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.
-
-## Thread border router (#18104)
-
-See boards.md for the ESP Thread BR board. Check that the H2 answers Spinel before blaming a PR.
-
-## nRF52840 dongle boards (#19009, #20814)
-
-Test config: the two LEDs as inverted GPIO outputs, the button as an inverted pull-up binary sensor, a
-10 s alive interval. To retest the nrfutil download path, move the cached `sdk-nrf/nrfutil` aside first.

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

@@ -0,0 +1,30 @@
+# Proven test flows
+
+Each flow names the pull requests it was used on, so their result tables show what to post.
+
+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
+- [`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
+- [`libretiny.md`](libretiny.md): rtc preference emulation, BK72xx crash report on the next boot
+- [`mqtt.md`](mqtt.md): broker bench, QoS, reconnect, crash log over MQTT
+- [`nrf52.md`](nrf52.md): dongle board support
+- [`online_image.md`](online_image.md): stalled and malformed downloads
+- [`openthread.md`](openthread.md): border router on the S3 host plus H2 RCP
+- [`ota.md`](ota.md): overlap and lock, timeouts, deflate
+- [`rtsp_server.md`](rtsp_server.md): camera streaming on the Waveshare ESP32-S3-ETH
+- [`scheduler.md`](scheduler.md): loop wake A/B
+- [`udp.md`](udp.md): datagrams, multicast, sockets
+- [`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)
+- [`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
+- [`globals.md`](globals.md): restoring globals with storage rtc and flash across every reset kind
+- [`homeassistant.md`](homeassistant.md): light platform mirrored from a local Home Assistant, held reports versus later calls
+- [`usb_audio.md`](usb_audio.md): USB audio speaker and microphone, the usb_host FIFO split, and Music Assistant playback through sendspin
+- [`dfrobot_sen0395.md`](dfrobot_sen0395.md): SEN0395 mmWave command flow, module quirks and overlong lines through its error reply

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

@@ -0,0 +1,30 @@
+# api
+
+## Noise handshake and OTA encryption on the ESP8266 (#19062, #19233)
+
+Host side timing is useless on a weak link; use an on-device bench with the minimum of five runs over
+two boots. Provision a key with `noise_encryption_set_key` through aioesphomeapi and upload with
+`espota2.run_ota(host, 8266, None, bin, noise_psk=key)` when the key is not in the yaml.
+
+## Outgoing connection wake timing on a deep sleep build (#21077)
+
+`templates/deep-sleep-outgoing-dut.yaml`: classic ESP32 ESP-IDF, `wifi: fast_connect`, `api: encryption` with a bare
+`outgoing_connection:`, `deep_sleep` 15 s run and 15 s sleep, a `homeassistant` text sensor, and `millis()` logged
+from `wifi: on_connect`, `api: on_client_connected` and the sensor's first `on_value`. Home Assistant's dial-in
+listener is on 6054; reuse a device name it already has. Flash by USB, `serial_capture.py PORT 360 OUT --reset` for
+12 cycles, then `scripts/api_outgoing/cycles.py OUT LABEL` prints per cycle the wifi, client and state millis with
+the client-wifi and state-client gaps. Wi-Fi takes 4 to 8 s after a wake, so compare the client-wifi gap, and run
+the PR twice around one base run because the spread is a few hundred ms.
+Results: https://github.com/esphome/esphome/pull/21077#issuecomment-6254098014
+
+## Outgoing connection on a mains build after a Wi-Fi drop (#21085)
+
+`templates/outgoing-wifi-drop-dut.yaml`: classic ESP32, `outgoing_connection: delay: 2s`, a "Wifi cycle" button doing
+`wifi.disable`, 4 s, `wifi.enable`, a `debug` loop-time sensor, millis from the wifi and api triggers. Flash by USB,
+`serial_capture.py PORT SECONDS OUT --ms`, press the button N times 40 s apart with `api_button.py DEV_IP KEY press
+"Wifi cycle"`, then `wificycles.py CAPTURE LABEL` prints per drop the Wi-Fi-to-dial gap, dials and dials closed, who
+connected first, and the loop-time maxima. For the loop cost of polling, repeat with an unreachable
+`host: 192.0.2.1`. Home Assistant refuses a dial-in while its own session is READY (`Refusing dial-in adoption`),
+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

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

@@ -0,0 +1,21 @@
+# captive_portal
+
+## Captive portal `/wifisave` hammer (#20802, #20784)
+
+Reproduces a `/wifisave` arriving during the STA cooldown, and proves a fix on every board.
+Device under test: `templates/example-dut.yaml` (bogus network, `ap:` with `ap_timeout: 15s`,
+`captive_portal:`). Client: `templates/example-client.yaml` on an ESP32 or a D1 mini; it joins the
+device's AP, posts 15 bogus saves 3 s apart, then the real credentials. With the portal up the cooldown
+is 30 s, so nearly every save lands inside one. Driver: `scripts/wifisave_hammer.sh`. Settle 40 s on
+ESP boards, 90 s on the BW15 (its first attempt on the real network fails, see boards.md).
+
+Counts that matter: `Requested WiFi Settings Change` (saves received), `Exiting cooldown early`, crash
+markers, boots (`Log initialized`), and the client's `bogus save status 200` and `real save status 200`.
+A healthy run: every save answered 200, one cooldown exit per save (two on the BW15, whose retry enters
+the adapter restart), no panic, and the real credentials connect the device within about 10 s.
+
+Fault injection for AP start failures: wrap `this->ap_setup_ = this->wifi_start_ap_(this->ap_)` in
+`setup_ap_config_()` with an `HWTEST_AP_FAIL_COUNT` build flag
+(`esphome: platformio_options: build_flags: -DHWTEST_AP_FAIL_COUNT=2`), raise the portal's "Captive
+portal started" from LOGV to LOGI, and after provisioning curl the device's STA address: connection
+refused proves the portal's server is gone.

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

@@ -0,0 +1,11 @@
+# cse7766
+
+## cse7766 on a Sonoff S31 (#20948)
+
+`templates/s31-cse7766-dut.yaml`: `logger: baud_rate: 0` because the CSE7766 owns the UART, VERBOSE logger
+with everything but cse7766 quieted, 2 s throttles, and a `globals` frame counter fed by the voltage sensor's
+`on_raw_value` and logged every 10 s (about 96 frames per 10 s). OTA only, every reflash reboots the relay.
+`scripts/cse7766/run_obs.sh IP SECONDS LABEL [OUTDIR] [NAME_FILTER]` subscribes to states and logs over the
+API with a concurrent ping and prints the frame counter, API gaps and warnings. API state gaps of 10 to 20 s
+can appear on a weak Wi-Fi path while the device counter stays flat, so judge a UART parser by the
+device-side counter, not by the API cadence. With nothing plugged in, current and power read 0.

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

@@ -0,0 +1,21 @@
+# dfrobot_sen0395
+
+## DFRobot SEN0395 mmWave on an ESP32 DevKit V1 (#20906, #20979)
+
+Wiring: V to VIN (5 V, the module wants 3.6 to 5 V), G to GND, sensor TX to GPIO16 (RX2), sensor RX to GPIO17
+(TX2), IO2 to GPIO18 (presence output, a gpio binary sensor), I1 unconnected. `templates/dfrobot-sen0395-dut.yaml`
+has the hub, both detection binary sensors, the four switches, settings buttons and junk-line buttons.
+`scripts/dfrobot_sen0395/ctl.py HOST KEY press:NAME sw:NAME=on|off wait:S` drives it and prints binary sensor and
+switch updates; `cases.sh DEV_IP KEY CAPTURE LABEL` runs the whole flow against a running serial capture. Flash by
+USB, `serial_capture.py PORT 540 CAPTURE --reset`, then the cases; compare the `Sending command` and `Message:` lines
+and the counts of `Done`, `Error`, prompts and frames between builds. The module echoes every command, so the echoed
+lines are the bytes the component sent and can be compared between builds as a set.
+
+Module facts: it answers `Done` or `Error` and then the `leapMMW:/>` prompt without a line end; a junk line gets
+`<line> is not recognized as a CLI command` (36 chars longer than the line, so 220 and 240 byte junk gives 256 and
+276 char replies); input lines of 256 bytes or more make the module assert (`..\User_code\main.c line:232`) and
+restart, after which the sensor is stopped; a factory reset restarts the module about 7 s later; `sensorStop` on a
+stopped sensor answers `sensor stopped already` then `Error`; a settings press takes 5 to 6 s (stop, change, save,
+start). Free heap on the ESP32 is Wi-Fi noise (192 to 198 kB) and says nothing about the component.
+Results: https://github.com/esphome/esphome/pull/20979#issuecomment-6279129146 and
+https://github.com/esphome/esphome/pull/20906#issuecomment-6279129604

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

@@ -0,0 +1,7 @@
+# espnow
+
+## ESP-NOW on the ESP8266 (#14407)
+
+The NONOS SDK only delivers broadcast ESP-NOW frames while the station is associated or a soft-AP is
+up; a hidden, open, client-less soft-AP (60 s beacon, DHCP stopped) makes broadcasts arrive. In AP-only
+mode the device transmits from the soft-AP MAC.

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

@@ -0,0 +1,15 @@
+# globals
+
+## Restoring globals with storage: rtc and flash (#13954)
+
+`templates/globals-storage-dut.yaml` is the shared package: five restoring globals (rtc int, flash int, default int,
+rtc `std::string`, rtc `uint8_t[2]`), bumped and logged with the reset reason on every boot, saved and synced after
+2 s, odd boots `App.safe_reboot()`. Platform files add the board (`packages: dut: !include globals-storage-dut.yaml`), the `debug` reset-reason text sensor and, on the
+ESP32, `deep_sleep: run_duration: 12s, sleep_duration: 8s` (even boots sleep). No network needed: flash by USB,
+`serial_capture.py PORT 110 OUT --reset` gives the reset pulse plus a run of soft restarts and sleeps; the ESP32's
+EN pulse is a `POWERON_RESET` that empties RTC memory, the D1 mini's RST pulse (`rst cause:2`) keeps it, so the
+ESP8266 needs a real power cut by hand; arm long `--released` captures on both ports first (the capture
+reopens the port when it comes back, the very first boot lines are still lost, read the next boot's restored
+values). Unchanged-build check: the config with every `storage:` removed, built on the PR and on the dev merge
+commit under the PR's own commits (not the merge base, which is older dev), `cmp -l` plus an `nm -S` symbol diff;
+only the template names differ. Results: https://github.com/esphome/esphome/pull/13954#issuecomment-6254794712

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

@@ -0,0 +1,9 @@
+# hdmi_cec
+
+## HDMI-CEC two-board wire (#9189)
+
+Two boards on one wire: promiscuous mode, a 0x8F request answered with 0x90 0x00, a `destination:`
+filter on the reply handler, template buttons for each target plus lambdas calling
+`send(source, dest, span)` as another initiator. Healthy numbers: device-side turnaround 15 to 22 ms,
+round trip 144 to 156 ms. Press buttons over the API; judge timings from device logs (ESP32 light sleep
+lags the press).

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

@@ -0,0 +1,47 @@
+# homeassistant
+
+## homeassistant light platform against a local Home Assistant (#11354)
+
+A local Home Assistant dev install (`hass -c config`, https://127.0.0.1:8123 with a self-signed cert); its ESPHome
+entries and entity ids are in `config/.storage/`. Two ESPHome RGBCW bulbs with a plaintext API are the lights, so an
+"HA side" change is made directly on a bulb with `scripts/homeassistant_light/bulb.py BULB_IP - on|off|state|restart`.
+Add the test devices to HA by hand with the shared `api_key` and "Allow the device to perform Home Assistant actions".
+
+`templates/homeassistant-light-dut.yaml` is a package: two mirrors, buttons for each change, a "Log state" button, a
+30 s alive line, an `on_boot` `light.turn_on` for the change-before-first-write path, and VERBOSE logging with the
+noisy tags at DEBUG (a tag cannot exceed the global level). A platform file sets the board and includes it:
+
+```yaml
+esphome:
+  name: ha-light-dut
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+packages:
+  dut: !include homeassistant-light-dut.yaml
+```
+
+Flash by USB, start a bounded `esphome logs` capture per device, then press buttons with
+`scripts/api_button.py DEV_IP KEY press "Button"` and read the bulb with `bulb.py`. Cases: each
+button against the bulb and the device log; a direct bulb change that both mirrors follow; restart the bulb, send a
+change, expect the 5 s `did not report the change back` and the fallback (with an off and with an on last report);
+OTA reboot with a serial capture running to see the boot-time change (the API log client reconnects too late).
+
+Lessons: the light core clamps mireds to the range HA reported; a flash sends nothing; a change sent while HA is
+connected but not yet subscribed is dropped by the api server (`client has not subscribed to actions (yet)`); after a
+fallback to an off report the mirror keeps the unsent brightness; a mirror that never saw its light on since boot has
+no levels to restore. Results: https://github.com/esphome/esphome/pull/11354#issuecomment-6253630336 and
+https://github.com/esphome/esphome/pull/11354#issuecomment-6254161409
+
+## Held report versus a later call (#21144)
+
+A report that arrives during a transition is held and applied when the transition ends, unless a call came after
+it. `scripts/homeassistant_light/heldcase.py DEV_IP KEY BULB_IP same|many [BULB_KEY]` (a key of `-` is plaintext) keeps one API connection to the mirror
+device and one to the bulb so the steps land inside a 3 s fade: press "A 50 fade 3s", 0.7 s later set the bulb to
+90% directly (the report is held), 1.4 s in press the same fade again (or "A many calls", 16 calls in one loop
+pass). Pass: the mirror and the bulb end at the second call's target. Only `same` reproduces the bug: a build
+without the fix logs `Applying the report that arrived during the transition` and the bulb stays at 90%. `many`
+ends at 100% on both builds because the last call's target differs from the held report, so it is a regression
+check only, not a reproduction. Separate button presses are too slow (about 1.5 s each) to land inside the fade.
+The mirrors are not API entities, so read their state from the "Log state" button's line. Results: https://github.com/esphome/esphome/pull/21144#issuecomment-6278257695

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

@@ -0,0 +1,15 @@
+# ld2450
+
+## LD2450 polygon zones (#20154)
+
+To make a target "leave" without anyone moving, set the radar's Zone-1 numbers over the target and
+switch the zone type to `Filter` (the count drops to 0 within 0.5 s); set it back to `Disabled` after.
+Writing those numbers blocks the ld2450 loop about 50 ms.
+
+## Zone numbers round trip (#21146)
+
+`scripts/ld2450/zonedrive.py HOST KEY(- for plaintext) set:NAME=VALUE sel:NAME=OPTION wait:S list` sets numbers and
+selects over the API and prints every LD2450 state update. After each set the hub sends the set zone command, queries
+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

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

@@ -0,0 +1,58 @@
+# libretiny
+
+## LibreTiny rtc preference emulation (#21007)
+
+The PR keeps `storage: rtc` preferences in FlashDB and deletes them on the first load or save after a boot
+whose `lt_get_reboot_reason()` is not software, watchdog, crash or sleep. Only the families listed in
+`_libretiny_rtc_supported()` accept the config keys; on others force the backend in with
+`platformio_options: build_flags: ["-DUSE_LIBRETINY_RTC_PREFERENCES"]` after confirming the rejection.
+
+- Harness: `scripts/libretiny_prefs/ltprefs.hpp` plus `templates/bk72xx-rtc-prefs-dut.yaml`. `ltprefs_boot()`
+  loads one rtc and one flash preference, a second pair that shares one key as rtc and as flash, and a third
+  rtc entry (so a hard reset drops three entries in one pass), logs the reason and both results, saves `100 + step`, syncs; after
+  a templated delay `ltprefs_exit()` bumps the flash-backed step and runs the step's action (`lt_reboot()`,
+  `__builtin_trap()`, `lt_reboot_wdt()` or idle). The last 8 boot reports are kept in a flash preference and
+  repeated in the 10 s alive line, so a boot missed by the capture (a power cut, an OTA-only board) is still
+  readable. Bump `run:` for fresh keys.
+- A store to an unmapped address does not fault on the ARM968, the board carries on: use `__builtin_trap()`
+  for the crash row. The SDK crash handler reboots about 10 s later. Works on BK7238 and BK7231N.
+- Hard resets: `serial_capture.py ... --reset` pulses RTS on CEN (reported as Power-On). A real power cut
+  needs a hand or a smart plug; the history in the alive line covers the boot the host cannot see. On the
+  Beken SDK a chip-enable reset and a power cut both report Power-On, there is no separate reset-pin source.
+- Step 0 and step 8 wait 30 s before acting so the host can open the port (and pulse a reset) after a flash
+  without losing the first boot; the flash tool's own reset starts the sequence immediately otherwise.
+- OTA-only board: keep the device's wifi, api and ota blocks verbatim, keep safe_mode, read logs with
+  `esphome logs <yaml> --device <name>.local` (the API attaches late, hence the history), and restore the
+  device's own config afterwards.
+- Plain-build comparison: `raw_firmware.bin` differs by the timestamp and by `__LINE__` in log calls of
+  functions below the added code; map offsets through `objdump -h` load addresses and `addr2line` before
+  calling a byte difference a code change.
+
+## BK72xx crash report on the next boot (#21012)
+
+Harness: `scripts/libretiny_crash/bkprobe.hpp` plus `templates/bk72xx-crash-probe-dut.yaml`. A flash
+preference holds the step; `on_boot` (priority -100) logs the reset reason, the SDK start type, two canaries
+and hex dumps of the low SRAM, a set of marker words and the record area after `.bss`, waits 30 s on step 0
+(so a capture can be opened after the flash) or 5 s, saves `step + 1`, syncs, then acts: 0 `__builtin_trap()`,
+1 call into unmapped memory, 2 unmapped and unaligned reads and a store (no fault on the ARM968), 3
+`lt_reboot()`. A `globals: restore_value` step counter does not work here: it is only saved from the global's
+loop, which a crash 50 ms later never reaches; save an `ESPPreferenceObject` and `global_preferences->sync()`
+first. Bump `run:` for fresh keys. Keep the `wifi:` block: the bug the fix addresses only shows with Wi-Fi up.
+
+Flow: `flash_bk72xx.py` (retry up to three times), one `serial_capture.py ... --reset` capture of 150 to 230 s,
+then `grep -a "libretiny.crash\|probe"`. Decode with
+`arm-none-eabi-addr2line -pfiaC -e .pioenvs/<name>/raw_firmware.elf <addr...>` (the ELF is `raw_firmware.elf`
+on LibreTiny), or run `scripts/libretiny_crash/decode_capture.py <yaml> <capture>` from the config directory
+to feed the capture through the CLI's `LogLineProcessor`.
+
+Expected: `*** CRASH DETECTED ON PREVIOUS BOOT ***`, `Reason: Undefined instruction`, PC on the `udf`,
+LR = PC + 1, BT0..BT7 walking the lambda, `StatelessLambdaAction`, `Action::play_complex`, `DelayAction`,
+`Scheduler::call`, `Application::loop`. The wild call reports where the core ended up (it executes zeros as
+Thumb NOPs until it wraps into real code), not the called address. Without the fix a dev build with Wi-Fi
+connected never comes back from the crash; see the BK72xx section in `boards.md`.
+
+OTA-only board: copy the device's own config, add the probe include and the step machine (step 0 crashes
+45 s after boot, later steps idle), keep its wifi, api, ota and safe_mode blocks and use the secrets file
+next to that config. A LibreTiny OTA is a 1.5 MB UF2 and takes minutes on a slow link, so do not wrap the
+upload in a short timeout. Read the replayed report with `esphome logs ... --device <name>.local` (an API
+client gets it on subscribe) or on the board's serial log port if it has one.

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

@@ -0,0 +1,12 @@
+# mqtt
+
+## MQTT (#20433, #17935, #20762, #20767, #20768)
+
+A local mosquitto with `allow_anonymous true`, `log_type all` and `log_dest file`: the broker log gives
+each subscription's QoS, the device address (`New client connected from <ip> as <name>-<mac>`) and exact
+subscribe counts. Kill and restart mosquitto to exercise `on_disconnect` (reason 0) and resubscription.
+Keep `reboot_timeout: 0s` on `api:` and `mqtt:`. The ESP-IDF outbox swings free heap about 2 kB right
+after bulk subscribe and unsubscribe; read the heap seconds later over several rounds before calling a
+leak. Spawned subscriptions need about 2.5 s to reach the broker before the next publish.
+`esphome logs --device MQTT` only uses the MQTT transport when the config has no `api:`. Driver pattern: a
+paho script publishes and polls the serial capture file.

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

@@ -0,0 +1,6 @@
+# nrf52
+
+## nRF52840 dongle boards (#19009, #20814)
+
+Test config: the two LEDs as inverted GPIO outputs, the button as an inverted pull-up binary sensor, a
+10 s alive interval. To retest the nrfutil download path, move the cached `sdk-nrf/nrfutil` aside first.

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

@@ -0,0 +1,20 @@
+# online_image
+
+## online_image stalled downloads (#20594)
+
+One classic ESP32, both frameworks (the ESP32 Arduino build also uses `http_request_idf.cpp`). The host
+serves the images: `scripts/online_image/make_images.py <www>` writes 16x16 BMP/PNG/JPEG/QOI plus an 8 bit
+palette BMP with a 1078 byte header; `scripts/online_image/oi_server.py <www> 8765 <log>` answers one
+misbehaviour per path name (`ok`, `truncated`, `large_header`, `empty`, `stall` holds the socket 40 s,
+`closed_early`, `slow` pauses 2.5 s, `chunked`, `chunked_cut`, `noclen`, `huge` claims 20 MB) with an ETag
+and a 304 on If-None-Match. `templates/online-image-dut.yaml` has two AUTO-format images (default and
+256 byte buffer), API actions `fetch`/`fetch_small` (set_url with `update: false`, then component.update)
+and `refetch`/`refetch_small` (component.update only, keeps the cache headers), and a restart button.
+`scripts/online_image/drive.py <device ip> <api key> <capture> http://<host ip>:8765 pr|base` runs the
+case list over aioesphomeapi and judges each from the serial capture. ESP-IDF facts: a stalled server
+ends with `Error downloading image: -28679` (EAGAIN) after the transport timeout, an early close with
+`-1`, both before and after the PR; a body without Content-Length and without chunking reads as complete
+(Size: 0) and finishes. A build without the fix hangs on the truncated, oversized header, empty, chunked PNG
+and cut chunked cases and every later update logs `Image already being updated.`, so a baseline run needs
+a reboot per group, the driver's 45 s cap per case, and an outer `timeout` that covers the whole list.
+A case expected as `any` passes on `finished` or `error`, never on no outcome.

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

@@ -0,0 +1,5 @@
+# openthread
+
+## Thread border router (#18104)
+
+See boards.md for the ESP Thread BR board. Check that the H2 answers Spinel before blaming a PR.

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

@@ -0,0 +1,8 @@
+# ota
+
+## OTA overlap and lock (#20588), OTA timeouts (#19041), deflate (#19037)
+
+All overlap orders (a web upload during a native OTA and the reverse) must be refused; the lock release
+after an interrupted web upload waits about 14 s (ESP8266) or 7 s (ESP-IDF) for disconnect detection. A
+refused web client on `web_server_idf` never gets the busy reply; the connection drops at reboot.
+`pkill -f "a\|b"` does not alternate; use two pkills.

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

@@ -0,0 +1,18 @@
+# rtsp_server
+
+## RTSP camera streaming on the Waveshare ESP32-S3-ETH (#17990)
+
+`templates/rtsp-waveshare-s3-eth-dut.yaml` (OV5640 pins, GPIO8 camera power switch with the 1.2 s boot delay,
+`rtsp_server`, logger VERBOSE for `rtsp_server`); swap the `wifi:` block for the W5500 `ethernet:` block when
+the cable is in, and add `network: enable_high_performance: true` for the big TCP buffers. Flash over native
+USB, capture the log with `serial_capture.py`, take the IP from the last `IP Address` line that is not
+0.0.0.0 (or `dns-sd -Q <name>.local`). `scripts/rtsp_server/rtsp_client.py IP [cases]` covers play, udp,
+pipeline, badreq, replay, getparam, teardown, third, stall, timeout; `rawrate2.py IP quiet|chatty|rtcp|bigbuf`
+measures the raw receive rate; `measure.sh IP LABEL LOGFILE [OUTDIR]` runs the fixed set (ping, ffmpeg 12 s
+twice, two ffmpeg clients, raw reader) and appends to `results.txt`; `cam_api.py IP` pulls one image over the
+API; `ffmpeg -rtsp_transport tcp -i rtsp://IP:554/ -frames:v 30 -f image2 f%03d.jpg` plus Pillow checks
+decoding. The 5760 byte default TCP send buffer makes the stream stall over Wi-Fi (about 1 fps, dozens of
+stall drops per run); `enable_high_performance` gives several fps on Wi-Fi and removes the stalls on Ethernet.
+Frame counts vary a lot between runs (auto exposure changes the JPEG size), so always measure twice. Home
+Assistant's stream pipeline does not accept MJPEG over RTSP; its ffmpeg camera opens one RTSP session per
+snapshot, so `max_connections` needs headroom, and go2rtc transcoding to H.264 is the way to a live view.

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

@@ -0,0 +1,8 @@
+# scheduler
+
+## Scheduler and loop wake A/B (#20356)
+
+An external component whose template button arms an SDK `os_timer` (50 ms, one shot) on the ESP8266;
+the callback runs in SYS context, records `millis()` and calls `set_timeout` or `defer`; the timeout
+logs the elapsed time and loop count delta. Drive with an aioesphomeapi script (`subscribe_logs` plus
+`button_command`). Build the same yaml twice with different names, one per tree.

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

@@ -0,0 +1,11 @@
+# udp
+
+## UDP, multicast, sockets (#20556 to #20559, #20585, #20590)
+
+A listener on port 9 needs no privileges on macOS. Test multicast device to device; host to device
+multicast never arrives on some access points, and `239.255.x.x` groups are unreliable even to a stock
+listener. Broadcast to boards is lossy under power save, unicast is not. Flood at a fixed packet rate
+(the host hits `ENOBUFS` unthrottled); 1500 packets per second survived on every board. A forced Wi-Fi
+reconnect on the Pico keeps IGMP membership. Set a long loop interval from `wifi.on_connect`
+(`App.set_loop_interval(20000)`), not `on_boot`, or Wi-Fi connect crawls. The `logger.log` action
+rejects `%.*s`; use a lambda.

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

@@ -0,0 +1,52 @@
+# usb_audio
+
+## USB audio on the Waveshare ESP32-S3-ETH (#21081, #11728)
+
+`templates/usb-audio-waveshare-s3-eth-dut.yaml`: ESP-IDF, PoE, logs over the API on Ethernet (the native USB port is
+the host port, so there is no console), `usb_audio` hub, a 48 kHz 16-bit microphone, a 48 kHz 24-bit speaker (many
+speakerphones offer only 24-bit; a wrong format logs the device's alternates), buttons for capture start and stop,
+a non-blocking beep fed from an 8 ms interval with `play(buf, len, 0)` (a blocking `play()` on the main loop trips
+the task watchdog), and a status interval with mic bytes, speaker state and heap. Drive the buttons with
+`scripts/api_button.py IP KEY press "Beep"`. Expect 192 kB/s microphone bytes and the FIFO split
+RX 80 / NPTX 16 / PTX 104 in the build's `defines.h`; with the balanced split the 294-byte OUT pipe is refused
+(`EP MPS (294) exceeds supported limit (128)`). A device whose OUT endpoint is larger than 600 bytes cannot be
+claimed on an S3 at all.
+
+## Music Assistant through sendspin
+
+`templates/usb-audio-sendspin-s3-eth-dut.yaml` overlays the template above with the Apollo CAST-1 wiring: resampler
+speakers into a mixer whose inputs never time out, `speaker_source` media player with the sendspin source, and
+`sendspin: unpaired_access: true`. A `media_player: platform: speaker` is not a media-source consumer and gives
+"Player over its buffer", no audio. Music Assistant finds the device by mDNS within 15 s of boot.
+
+Read the result from the device, not only by ear: sendspin's sync task logs `Lost sync (N us off)` (DEBUG, tag
+`SsSync`) for every correction over 5 ms, a positive N inserts that much silence, and each one is an audible click.
+For the chunk lead histogram, edit the managed library in the build directory,
+`.esphome/build/<name>/managed_components/sendspin__sendspin-cpp/src/sync_task.cpp` (an `SS_LOGD` before the
+late-chunk skip in `decode_chunk()` printing the chunk's lead against `new_audio_client_playtime`), update only that
+file's `size` and sha256 `hash` in the component's `CHECKSUMS.json`, and compile again; deleting `.component_hash` or
+recomputing it makes the manager refuse or refetch. Check the edit is in the image with `strings firmware.ota.bin`.
+A lead below -5 ms makes the library skip the whole chunk; an I2S speaker keeps it within 0.1 ms of zero, which is
+the figure a USB speaker has to match.
+
+Gotchas: wait two minutes after a reboot before the measured stream (safe mode's boot counter write stalls the cores
+for about 140 ms once, 60 to 75 s after boot); with the serial console on, a DEBUG log line per report saturates
+UART0 and trips the task watchdog, so use `logger: baud_rate: 0` and the API log; two overlapping `esphome logs`
+captures double every count; and every audio test must include a pause and resume cycle, since a stream end that
+leaves less than one transfer parked in the driver was what hung the speaker after #11728 merged.
+
+## Controls
+
+Apollo CAST PRO-1 (`templates/cast-pro-1-sendspin-control.yaml`): `Core.yaml` next to it is
+`Integrations/ESPHome/Core.yaml` from ApolloAutomation/CAST_PRO-1, which also defines the `version` substitution.
+Keep its framework log level at ERROR (DEBUG floods driver output and trips the watchdog); the package reboots itself
+into Ethernet-only once it sees a link and appends the MAC suffix to the name. `wifi: enable_on_boot: false` keeps
+sendspin off Wi-Fi.
+
+Nabu Casa Connect AUX-2 (a pre-production unit): build from `packages/aux-2-pre-prod.yaml` at NabuCasa/aux-2 commit
+283f2e64 (dropped in bde41e01), not the public `aux-2.yaml`, whose W5500, codec and I2S pins differ (the public one
+reads W5500 chip ID 0x00 and fails the codec's I2C writes). Point its local `external_components` source at
+`github://NabuCasa/aux-2@main`. Templates `aux-2-preprod-stock-dut.yaml` (I2S codec) and
+`aux-2-preprod-usb-audio-dut.yaml` (the USB speaker as the mixer output via `!extend mixing_speaker`). The console is
+the CH343 (1a86:55d3); first flash over it, OTA after. Forcing the Wi-Fi flag off with `restore_value: no` boot-loops
+when Ethernet fails, so let the package switch itself.

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

@@ -0,0 +1,20 @@
+# usb_cdc_acm
+
+## usb_cdc_acm on the nRF52840 dongle (#11634)
+
+`templates/usb-cdc-acm-dongle-dut.yaml`: logger on USB_CDC port 0, `usb_cdc_acm` interface 0 disabled,
+interface 1 echoing from a 20 ms lambda, 0x01-prefixed commands for burst, stream, flush, peek, line coding
+and counters. Build and flash with `dfu: true` through the app port; the dongle then shows three CDC ports:
+the board DTS node `cdc_acm_uart` (unused), `cdc_acm_uart0` (log) and `cdc_acm_uart1` (data), in that order.
+Capture the log port with `serial_capture.py`, drive the data port with `scripts/usb_cdc_acm/drive.py
+DATA_PORT` (11 cases, prints PASS/FAIL and a summary) and grep the log for `Opened`, `Closed`, `buffer full`,
+`flush result`, `line coding`. Boot lines are held in the driver's 1 KB ring until the host opens the port, so
+a capture started later still shows the first 1 KB of the boot and then a truncated line.
+
+With three CDC instances the Zephyr legacy stack's `CONFIG_USB_MAX_NUM_TRANSFERS=4` starves the last instance
+(each instance holds an OUT read and an IN ZLP), so interface 1 shows DTR changes but moves no data.
+`scripts/usb_cdc_acm/cdc_probe.hpp` (include it, call `cdc_probe()` from an interval) reads the Zephyr driver
+directly to tell a dead endpoint from a component bug. Raising the transfer pool to 8, or disabling the
+board's `cdc_acm_uart` node, fixes it. Design limit of the driver: `fifo_fill` holds `tx_ready` until the
+write callback and `write_array` drops when the ring is full, so a 64 KiB full-duplex echo loses one 64 byte
+tail on every buffer size.

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

@@ -0,0 +1,25 @@
+# wifi
+
+## `reboot_timeout` with a fallback AP (#9958)
+
+Only one board runs the AP at a time, or stations join the wrong one. AP probe: bogus network,
+`ap: {ssid, password, ap_timeout: 5s}`, `reboot_timeout: 60s`, `logger: level: VERBOSE` (ESP32 and
+ESP8266 log `AP client connected MAC=` at verbose), `on_boot: logger.log: BOOT`. Station probes:
+`reboot_timeout: 0s`, `interval: 150s` running `wifi.disable`, `delay: 20s`, `wifi.enable` (60 s cycles
+are too short to cover the due moment). Pass pattern: "Can't connect; rebooting" exactly 60 s after boot
+with no station joined, no reboot for minutes while one is, then a reboot within a second of the last
+disconnect. The BW15 restarts its AP on every STA retry and cannot be tested this way.
+
+## DHCP lease cache (#17767)
+
+Cycle 20 s awake, `deep_sleep.enter 30s`, wake, 20 s, `App.safe_reboot()`, logging `millis()` at the
+`wifi.connected` condition. An RTS hardware reset must fall back to DHCP; a software reboot and a deep
+sleep wake must apply the cache. `esphome run --no-logs` silently skipped the upload on one board; use
+`upload` then `logs`.
+
+## Wi-Fi Easy Connect (DPP) enrollee (#17934)
+
+Only an Android phone configures: Settings, network details, Add device, Share Wi-Fi (the Wi-Fi list's
+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.

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

@@ -0,0 +1,10 @@
+# zephyr
+
+## Zephyr preferences on the nRF52840 dongle (#20810)
+
+`templates/nrf52-preferences-dut.yaml`: logger on USB_CDC at VERBOSE, `flash_write_interval: 5s`, one
+`globals` with `restore_value` incremented every 15 s. Give each build its own global id so each first boot
+sees a never-saved key (settings survive a reflash). Flow per build: flash through the log port, 40 s capture
+of the first boot, then start a second capture and reboot with a 2001 baud touch on the dongle's other CDC
+port (the dfu rate callback is global, and the capture holds the log port); `serial_capture.py` reopens the
+log port after the USB re-enumeration and gets the buffered boot lines (`load setting`, `Loaded N settings`).

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

@@ -0,0 +1,17 @@
+# zephyr_coredump
+
+## zephyr_coredump crash and decode on nRF52 boards (#13122)
+
+`templates/nrf52-coredump-crash-dut.yaml` (dongle; change `board:` to `adafruit_itsybitsy_nrf52840` for the
+ItsyBitsy): `zephyr_coredump:`, `dfu: true`, a `restore_value` global keyed by the `run` substitution
+(settings survive a reflash, so bump `run` for every new crash), and an `on_boot` sequence that sets the
+flag, yields 3 s so the globals loop saves it (a blocking lambda never gets there and the board crash-loops),
+syncs preferences, then writes to 0xDEADBEEF. Flash, keep every port closed for 80 s, then
+`scripts/zephyr_coredump/flow.sh LABEL PORT ELF [OUTDIR]` does the three opens (3 s cut, 100 s full print,
+20 s reopen) and calls `decode.sh`, which keeps the first complete `#CD:BEGIN#..END#` block, runs Zephyr's
+`coredump_serial_log_parser.py` and `coredump_gdbserver.py` from the sdk-nrf ESPHome installed and prints
+`bt` and `info threads` with its `arm-zephyr-eabi-gdb`. The ELF is `.pioenvs/<name>/zephyr/zephyr/zephyr.elf`.
+Expect about 9 KB dumps, 140 to 150 `#CD:` lines, a 673 ms loop warning for the erase, and `Has stored
+dump: 0` on the reopen. Check `compiled on` in every capture: another session flashing the same board
+mid-test looks exactly like a failed test otherwise. Boards without a network cannot exercise the API and
+MQTT delivery paths of the component; say so in the results.

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

@@ -0,0 +1,23 @@
+# zwave_proxy
+
+## zwave_proxy frame checksums on a live proxy (#20922)
+
+A Z-Wave proxy (ESP32-S3 with the module on `usb_uart`) is a live device: flash it over OTA and read logs
+over the API, there is no serial console because the native USB is the host port for the module, so the
+boot-time `GET_NETWORK_IDS` exchange is never captured. Home Assistant's Z-Wave JS holds the single API
+subscription (it polls `0x3B` every 30 s and resubscribes after every reboot), so do not subscribe from a
+script, and keep the device `name:` so it stays on Z-Wave JS; give each build its own scratch directory
+instead.
+
+1. `logger: level: VERY_VERBOSE` with `logs: zwave_proxy: VERY_VERBOSE` and DEBUG for the rest: the
+   `Sending:`, `Received frame:` and `CHECKSUM Received ... Calculated` lines are `ESP_LOGVV`, which needs
+   the compile-time level.
+2. `md5` the two `firmware.ota.bin` files to be sure the A and B builds differ, then `esphome upload
+   --device <name>.local` and a `timeout 330 esphome logs --device <name>.local` capture started right after
+   the OTA to catch the resubscribe traffic.
+3. `scripts/zwave_proxy/verify_checksums.py <captures>` recomputes the XOR (init 0xFF, LENGTH..payload) over
+   every logged frame and counts bad checksums and ACK/NAK sent and received; `scripts/zwave_proxy/devinfo.py
+   <name>.local` prints the firmware version, compile time and the Home ID from the API (a Home ID proves the
+   device-built `GET_NETWORK_IDS` frame was accepted at boot).
+4. Pre-existing: one `zwave_proxy took a long time for an operation` warning on the first frame after the
+   log client connects, caused by VERY_VERBOSE logging; it appears on dev too.

.agents/skills/hardware-test/scripts/api_button.py

@@ -0,0 +1,33 @@
+"""Press a template button on the test device over the API, or list its buttons.
+
+usage: api_button.py HOST KEY list | press "Button name" [...]
+"""
+
+import asyncio
+import sys
+
+from aioesphomeapi import APIClient, ButtonInfo
+
+HOST, KEY = sys.argv[1], sys.argv[2]
+CMD, ARGS = sys.argv[3], sys.argv[4:]
+
+
+async def main() -> None:
+    c = APIClient(HOST, 6053, None, noise_psk=KEY)
+    await c.connect(login=True)
+    ents, _ = await c.list_entities_services()
+    buttons = {e.name: e for e in ents if isinstance(e, ButtonInfo)}
+    if CMD == "list":
+        print("\n".join(sorted(buttons)))
+    else:
+        for name in ARGS:
+            if name not in buttons:
+                sys.exit(f"no button named {name!r}; have {sorted(buttons)}")
+            c.button_command(buttons[name].key)
+            print("pressed", name)
+            await asyncio.sleep(0.3)
+    await asyncio.sleep(0.5)
+    await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/api_outgoing/cycles.py

@@ -0,0 +1,73 @@
+"""Per wake cycle timings from a serial capture of the deep sleep timing config.
+
+usage: cycles.py CAPTURE [LABEL]
+A cycle starts at the boot banner; the numbers are the device's millis() from the timing lines, and the
+capture clock gap from the first line of the cycle to the "Dialing" line.
+"""
+
+import pathlib
+import re
+import statistics
+import sys
+
+cap = (
+    pathlib.Path(sys.argv[1]).read_text(encoding="utf-8", errors="replace").splitlines()
+)
+label = sys.argv[2] if len(sys.argv) > 2 else ""
+TS = re.compile(r"^\[(\d\d):(\d\d):(\d\d)(?:\.(\d+))?\]")
+
+
+def secs(line):
+    m = TS.match(line)
+    if not m:
+        return None
+    h, mi, s, f = m.groups()
+    return int(h) * 3600 + int(mi) * 60 + int(s) + (int(f) / 10 ** len(f) if f else 0)
+
+
+cycles = []
+cur = None
+for line in cap:
+    if "rst:0x" in line or (cur is None and "Log initialized" in line):
+        cur = {"start": secs(line), "reset": line.split("]", 1)[-1].strip()[:60]}
+        cycles.append(cur)
+        continue
+    if cur is None:
+        continue
+    if "Dialing" in line:
+        cur.setdefault("dial_cap", secs(line))
+    m = re.search(r"wifi connected at (\d+) ms", line)
+    if m:
+        cur.setdefault("wifi", int(m.group(1)))
+    m = re.search(r"client connected at (\d+) ms \((.*?)\)", line)
+    if m and "client" not in cur:
+        cur["client"] = int(m.group(1))
+        cur["who"] = m.group(2)
+    m = re.search(r"first HA state '(.*?)' at (\d+) ms", line)
+    if m and "state" not in cur:
+        cur["state"] = int(m.group(2))
+
+print(f"{label} cycles: {len(cycles)}")
+print(
+    f"{'n':>2} {'wifi ms':>8} {'dial +ms':>9} {'client ms':>10} {'state ms':>9} {'client-wifi':>11} {'state-client':>12}  client  reset"
+)
+for i, c in enumerate(cycles, 1):
+    dial = ""
+    if c.get("dial_cap") is not None and c.get("start") is not None:
+        dial = f"{(c['dial_cap'] - c['start']) * 1000:.0f}"
+    cw = c["client"] - c["wifi"] if "client" in c and "wifi" in c else ""
+    sc = c["state"] - c["client"] if "state" in c and "client" in c else ""
+    print(
+        f"{i:>2} {c.get('wifi', ''):>8} {dial:>9} {c.get('client', ''):>10} {c.get('state', ''):>9} {cw:>11} {sc:>12}  {c.get('who', '')}  {c.get('reset', '')[:28]}"
+    )
+for c in cycles:
+    if "client" in c and "wifi" in c:
+        c["client-wifi"] = c["client"] - c["wifi"]
+    if "state" in c and "client" in c:
+        c["state-client"] = c["state"] - c["client"]
+for key in ("wifi", "client", "state", "client-wifi", "state-client"):
+    vals = [c[key] for c in cycles if key in c]
+    if vals:
+        print(
+            f"{key}: n={len(vals)} min={min(vals)} median={statistics.median(vals):.0f} max={max(vals)}"
+        )

.agents/skills/hardware-test/scripts/api_outgoing/wificycles.py

@@ -0,0 +1,107 @@
+"""Per Wi-Fi drop timings from a serial capture of the outgoing connection timing config.
+
+usage: wificycles.py CAPTURE [LABEL]
+A cycle starts at "wifi cycle disabling"; the numbers are the device's millis() from the timing lines.
+"dial" says whether the client that connected first came from the device's own dial ("Dialing" seen after the
+reconnect and before the hello) or from an incoming connection ("Accept" seen first).
+"""
+
+import pathlib
+import re
+import statistics
+import sys
+
+cap = (
+    pathlib.Path(sys.argv[1]).read_text(encoding="utf-8", errors="replace").splitlines()
+)
+label = sys.argv[2] if len(sys.argv) > 2 else ""
+TS = re.compile(r"^\[(\d\d):(\d\d):(\d\d)(?:\.(\d+))?\]")
+
+
+def secs(line):
+    m = TS.match(line)
+    if not m:
+        return None
+    h, mi, se, f = m.groups()
+    return int(h) * 3600 + int(mi) * 60 + int(se) + (int(f) / 10 ** len(f) if f else 0)
+
+
+cycles = []
+cur = None
+loop_max = []
+for line in cap:
+    m = re.search(r"loop time max (\d+) ms", line)
+    if m:
+        loop_max.append(int(m.group(1)))
+    if "wifi cycle disabling" in line:
+        cur = {"order": []}
+        cycles.append(cur)
+        continue
+    if cur is None:
+        continue
+    m = re.search(r"wifi connected at (\d+) ms", line)
+    if m and "wifi" not in cur:
+        cur["wifi"] = int(m.group(1))
+        cur["wifi_cap"] = secs(line)
+    if "Dialing" in line:
+        cur["order"].append("dial")
+        cur["dials"] = cur.get("dials", 0) + 1
+        if "dial_cap" not in cur and "wifi_cap" in cur:
+            cur["dial_cap"] = secs(line)
+        elif "dial_cap" not in cur and "dial_before_wifi_cap" not in cur:
+            cur["dial_before_wifi_cap"] = secs(line)
+    if (
+        re.search(r"client disconnected at \d+ ms \(\d+\.\d+\.\d+\.\d+\)", line)
+        and "wifi" in cur
+        and "client" not in cur
+    ):
+        cur["dial_closed"] = cur.get("dial_closed", 0) + 1
+    if "Accept " in line and "wifi" in cur:
+        cur["order"].append("accept")
+    m = re.search(r"client connected at (\d+) ms \((.*?)\)", line)
+    if m and "wifi" in cur and "client" not in cur:
+        cur["client"] = int(m.group(1))
+        cur["who"] = m.group(2).split(" ")[0]
+        cur["via"] = cur["order"][0] if cur["order"] else "?"
+    m = re.search(r"Connect (failed|timeout)", line)
+    if m:
+        cur.setdefault("connect_errors", 0)
+        cur["connect_errors"] += 1
+
+print(f"{label} cycles: {len(cycles)}")
+print(
+    f"{'n':>2} {'wifi ms':>8} {'dial-wifi cap ms':>16} {'client ms':>10} {'client-wifi':>11}  via     dials closed  client"
+)
+for i, c in enumerate(cycles, 1):
+    cw = c["client"] - c["wifi"] if "client" in c and "wifi" in c else ""
+    c["client-wifi"] = cw
+    dw = ""
+    if "wifi_cap" in c and c.get("wifi_cap") is not None:
+        # the first dial of the cycle, whether it was logged before or after the Wi-Fi line
+        if c.get("dial_before_wifi_cap") is not None:
+            dw = f"{(c['dial_before_wifi_cap'] - c['wifi_cap']) * 1000:.0f}"
+        elif "dial_cap" in c and c["dial_cap"] is not None:
+            dw = f"{(c['dial_cap'] - c['wifi_cap']) * 1000:.0f}"
+    c["dial-wifi"] = dw
+    print(
+        f"{i:>2} {c.get('wifi', ''):>8} {dw:>16} {c.get('client', ''):>10} {cw:>11}  {c.get('via', ''):7s} {c.get('dials', 0):>5} {c.get('dial_closed', 0):>6}  {c.get('who', '')}"
+    )
+for via in ("dial", "accept"):
+    vals = [
+        c["client-wifi"]
+        for c in cycles
+        if c.get("via") == via and c["client-wifi"] != ""
+    ]
+    if vals:
+        print(
+            f"client-wifi via {via}: n={len(vals)} min={min(vals)} median={statistics.median(vals):.0f} max={max(vals)}"
+        )
+dws = [float(c["dial-wifi"]) for c in cycles if c.get("dial-wifi") not in ("", None)]
+if dws:
+    print(
+        f"dial after wifi connected (capture clock): n={len(dws)} min={min(dws):.0f} median={statistics.median(dws):.0f} max={max(dws):.0f}"
+    )
+if loop_max:
+    print(
+        f"loop time max per 5 s: n={len(loop_max)} min={min(loop_max)} median={statistics.median(loop_max):.0f} max={max(loop_max)}"
+    )

.agents/skills/hardware-test/scripts/cse7766/observe.py

@@ -0,0 +1,71 @@
+"""Subscribe to states and logs of a device over the API for N seconds and summarize its float sensors.
+
+usage: observe.py IP SECONDS OUTFILE [NAME_FILTER]
+
+Every float sensor state whose entity name contains NAME_FILTER (default: all) is appended to OUTFILE
+with a relative timestamp, log lines are appended with a LOG prefix, and a one-line summary per sensor
+(count, min, max, last) plus the warning and error count is printed at the end.
+"""
+
+import asyncio
+import pathlib
+import re
+import sys
+import time
+
+from aioesphomeapi import APIClient, LogLevel
+
+IP, SECS, OUT = sys.argv[1], float(sys.argv[2]), sys.argv[3]
+FILTER = sys.argv[4] if len(sys.argv) > 4 else ""
+# ESPHome LOG_SECRET span; one cut off before its end marker is secret to the end of the line
+SECRET = re.compile(r"\x1b\[8m.*?(?:\x1b\[28m|$)", re.DOTALL)
+ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+async def main() -> None:
+    c = APIClient(IP, 6053, None)
+    await c.connect(login=True)
+    di = await c.device_info()
+    ents, _ = await c.list_entities_services()
+    names = {e.key: e.name for e in ents}
+    readings: dict[str, list[float]] = {}
+    warnings: list[str] = []
+    t0 = time.monotonic()
+    with pathlib.Path(OUT).open("w", encoding="utf-8") as out:
+        out.write(
+            f"device {di.name} version {di.esphome_version} compiled {di.compilation_time}\n"
+        )
+
+        def on_state(st) -> None:
+            n = names.get(st.key, str(st.key))
+            if FILTER in n and hasattr(st, "state") and isinstance(st.state, float):
+                readings.setdefault(n, []).append(st.state)
+                out.write(f"[{time.monotonic() - t0:6.1f}] {n}: {st.state}\n")
+                out.flush()
+
+        def on_log(msg) -> None:
+            line = (
+                msg.message.decode(errors="replace")
+                if isinstance(msg.message, bytes)
+                else msg.message
+            )
+            line = ANSI.sub("", SECRET.sub("<secret>", line))
+            out.write(f"[{time.monotonic() - t0:6.1f}] LOG {line}\n")
+            out.flush()
+            if "[W]" in line or "[E]" in line or "Invalid" in line:
+                warnings.append(line)
+
+        c.subscribe_states(on_state)
+        c.subscribe_logs(on_log, log_level=LogLevel.LOG_LEVEL_VERBOSE)
+        await asyncio.sleep(SECS)
+        await c.disconnect()
+    summary = "; ".join(
+        f"{k.split()[-1]} n={len(v)} min={min(v):.3f} max={max(v):.3f} last={v[-1]:.3f}"
+        for k, v in sorted(readings.items())
+    )
+    print(f"{di.compilation_time}: {summary}; warnings/errors {len(warnings)}")
+    for w in warnings[:5]:
+        print("  ", w)
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/cse7766/run_obs.sh

@@ -0,0 +1,27 @@
+#!/bin/zsh
+# usage: run_obs.sh IP SECONDS LABEL [OUTDIR] [NAME_FILTER]
+# Observes states and logs over the API with a concurrent ping and prints a summary: the device-side
+# "frames parsed" counter per 10 s, gaps over 5 s between voltage updates seen by the API, and warnings.
+# Needs a python with aioesphomeapi (PYTHON, default python3).
+D=${0:A:h}
+IP=$1; SECS=$2; L=$3; S=${4:-.}; F=${5:-}
+PY=${PYTHON:-python3}
+setopt pipefail
+ping -i 1 -c $SECS $IP > $S/ping-$L.txt 2>&1 &
+P=$!
+if ! timeout $((SECS + 40)) $PY $D/observe.py $IP $SECS $S/obs-$L.txt "$F" 2>&1 | sed "s/$IP/<ip>/g"; then
+  echo "observe.py failed or timed out, no summary"; wait $P; exit 1
+fi
+wait $P
+echo "ping: $(tail -2 $S/ping-$L.txt | head -1 | sed "s/$IP/<ip>/g") $(tail -1 $S/ping-$L.txt)"
+python3 - "$S/obs-$L.txt" <<'PY'
+import re, sys
+txt = open(sys.argv[1]).read()
+fr = [int(m.group(1)) for m in re.finditer(r"frames parsed: (\d+) in 10 s", txt)]
+print(f"device frame counter per 10 s: n={len(fr)} min={min(fr) if fr else None} max={max(fr) if fr else None} mean={sum(fr)/len(fr) if fr else 0:.1f}")
+ts = [float(m.group(1)) for m in re.finditer(r"^\[\s*([0-9.]+)\] .*Voltage: ", txt, re.M)]
+gaps = [round(b - a, 1) for a, b in zip(ts, ts[1:]) if b - a > 5]
+print(f"API voltage updates {len(ts)}, gaps over 5 s: {gaps}")
+warn = [l for l in txt.splitlines() if "LOG" in l and ("[W]" in l or "[E]" in l or "Invalid" in l)]
+print(f"warnings/errors in log: {len(warn)}", *warn[:3], sep="\n  ")
+PY

.agents/skills/hardware-test/scripts/dfrobot_sen0395/cases.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# cases.sh DEV_IP KEY CAPTURE LABEL : the SEN0395 flow (settings, switches, junk lines, factory reset, reset) against
+# templates/dfrobot-sen0395-dut.yaml, with a serial capture of the device running into CAPTURE
+D=$1; K=$2; LOG=$3; LABEL=$4; PY=${PYTHON:-python3}; CTL="$(dirname "$0")/ctl.py"
+show() { tail -n +$(($1+1)) "$LOG" | sed 's/\x1b\[[0-9;]*m//g' | grep -a 'dfrobot\|Detected\|\[W\]\|\[E\]\|sen\]' | grep -a -v 'JYBSS\|took a long time' | cut -c1-200; }
+step() { n0=$(wc -l < "$LOG"); echo "=== $LABEL: $1 ($(date +%T))"; shift; $PY "$CTL" "$D" "$K" "$@" || { rc=$?; echo "driver failed ($rc), aborting"; exit $rc; }; echo "--- device log:"; show "$n0"; }
+frames() { echo "frames: $(tail -n +$(($1+1)) "$LOG" | grep -a -c 'JYBSS,1') present, $(tail -n +$(($1+1)) "$LOG" | grep -a -c 'JYBSS,0') absent"; }
+n0=$(wc -l < "$LOG"); echo "=== $LABEL: 20 s of frames ($(date +%T))"; sleep 20; frames "$n0"
+step "range 0 to 3 m" "press:Range 0 to 3m" wait:12
+step "range 0 to 9 m" "press:Range 0 to 9m" wait:12
+step "latency 1 s / 2 s" "press:Latency 1s 2s" wait:12
+step "latency 0 / 0" "press:Latency 0 0" wait:12
+step "sensitivity 7" "press:Sensitivity 7" wait:12
+step "LED off then on" "sw:LED=off" wait:10 "sw:LED=on" wait:10
+step "sensor active off then on" "sw:Sensor active=off" wait:10 "sw:Sensor active=on" wait:10
+step "presence via UART off then on" "sw:Presence via UART=off" wait:10 "sw:Presence via UART=on" wait:10
+step "start after boot off then on" "sw:Start after boot=off" wait:10 "sw:Start after boot=on" wait:10
+for n in 100 160 200 220 240 256; do step "junk line of $n bytes" "press:Junk $n" wait:7; done
+step "junk 220 then a command" "press:Junk 220" wait:6 "press:Range 0 to 9m" wait:12
+step "factory reset" "press:Factory reset" wait:15
+step "reset" "press:Reset" wait:15
+n0=$(wc -l < "$LOG"); echo "=== $LABEL: 20 s of frames after ($(date +%T))"; sleep 20; frames "$n0"

.agents/skills/hardware-test/scripts/dfrobot_sen0395/ctl.py

@@ -0,0 +1,63 @@
+"""Drive the SEN0395 test device over the API and print its binary sensor and switch updates.
+usage: ctl.py HOST KEY(- for plaintext) OP [OP ...]   OP: press:NAME | sw:NAME=on|off | wait:SECONDS
+"""
+
+import asyncio
+import sys
+import time
+
+from aioesphomeapi import (
+    APIClient,
+    BinarySensorState,
+    ButtonInfo,
+    SwitchInfo,
+    SwitchState,
+)
+
+HOST, KEY = sys.argv[1], sys.argv[2]
+OPS = sys.argv[3:]
+T0 = time.time()
+
+
+async def main() -> None:
+    c = APIClient(HOST, 6053, None, noise_psk=None if KEY == "-" else KEY)
+    await c.connect(login=True)
+    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)}
+    switches = {e.name: e for e in ents if isinstance(e, SwitchInfo)}
+
+    def on_state(s) -> None:
+        e = by_key.get(s.key)
+        if isinstance(s, BinarySensorState):
+            print(
+                f"{time.time() - T0:7.3f} BIN {e.name} = {'ON' if s.state else 'off'}"
+            )
+        elif isinstance(s, SwitchState):
+            print(
+                f"{time.time() - T0:7.3f} SW  {e.name} = {'on' if s.state else 'off'}"
+            )
+
+    c.subscribe_states(on_state)
+    await asyncio.sleep(1.0)
+    for op in OPS:
+        kind, _, rest = op.partition(":")
+        if kind == "wait":
+            await asyncio.sleep(float(rest))
+        elif kind == "press":
+            if rest not in buttons:
+                sys.exit(f"no button {rest!r}; have {sorted(buttons)}")
+            print(f"{time.time() - T0:7.3f} >>> press {rest}")
+            c.button_command(buttons[rest].key)
+        elif kind == "sw":
+            name, _, val = rest.partition("=")
+            if name not in switches:
+                sys.exit(f"no switch {name!r}; have {sorted(switches)}")
+            print(f"{time.time() - T0:7.3f} >>> switch {name} {val}")
+            c.switch_command(switches[name].key, val == "on")
+        else:
+            sys.exit(f"unknown op {op!r}")
+    await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/homeassistant_light/bulb.py

@@ -0,0 +1,78 @@
+"""Read or drive a bulb directly over its own ESPHome API (an HA-side change, independent of the mirror).
+
+usage: bulb.py HOST KEY state | on [brightness 0-1] [ct_mireds|rgb r,g,b] | off | restart
+"""
+
+import asyncio
+import sys
+
+from aioesphomeapi import APIClient, ButtonInfo, LightColorCapability, LightInfo
+
+HOST, KEY, CMD = sys.argv[1], sys.argv[2], sys.argv[3]
+ARGS = sys.argv[4:]
+
+
+async def main() -> None:
+    c = APIClient(HOST, 6053, None, noise_psk=None if KEY == "-" else KEY)
+    await c.connect(login=True)
+    ents, _ = await c.list_entities_services()
+    light = next((e for e in ents if isinstance(e, LightInfo)), None)
+    if light is None:
+        sys.exit("no light entity on this device; is HOST a bulb?")
+    if CMD == "state":
+        fut = asyncio.get_running_loop().create_future()
+
+        def on_state(st):
+            if getattr(st, "key", None) == light.key and not fut.done():
+                fut.set_result(st)
+
+        c.subscribe_states(on_state)
+        st = await asyncio.wait_for(fut, 5)
+        print(
+            f"{light.name}: on={st.state} mode={st.color_mode} bri={st.brightness:.2f} "
+            f"ct={st.color_temperature:.1f} rgb={st.red:.2f}/{st.green:.2f}/{st.blue:.2f} "
+            f"white={st.white:.2f} cold={st.cold_white:.2f} warm={st.warm_white:.2f}"
+        )
+    elif CMD == "on":
+        kw = {"state": True}
+        if ARGS:
+            kw["brightness"] = float(ARGS[0])
+        if len(ARGS) > 1:
+            if "," in ARGS[1]:
+                r, g, b = (float(x) for x in ARGS[1].split(","))
+                kw["rgb"] = (r, g, b)
+                kw["color_mode"] = (
+                    LightColorCapability.RGB
+                    | LightColorCapability.ON_OFF
+                    | LightColorCapability.BRIGHTNESS
+                )
+            else:
+                kw["color_temperature"] = float(ARGS[1])
+                kw["color_mode"] = (
+                    LightColorCapability.COLOR_TEMPERATURE
+                    | LightColorCapability.ON_OFF
+                    | LightColorCapability.BRIGHTNESS
+                )
+        c.light_command(light.key, **kw)
+        print("bulb on", kw)
+    elif CMD == "off":
+        c.light_command(light.key, state=False)
+        print("bulb off")
+    elif CMD == "restart":
+        btn = next(
+            (
+                e
+                for e in ents
+                if isinstance(e, ButtonInfo) and "restart" in e.name.lower()
+            ),
+            None,
+        )
+        if btn is None:
+            sys.exit("no restart button on this device")
+        c.button_command(btn.key)
+        print("bulb restart pressed")
+    await asyncio.sleep(0.5)
+    await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/homeassistant_light/heldcase.py

@@ -0,0 +1,71 @@
+"""Held-report cases for esphome#21144 with persistent API connections, so the steps land inside the 3 s fade.
+usage: heldcase.py DEV_IP KEY BULB_IP same|many [BULB_KEY]   (KEY or BULB_KEY of - means plaintext)
+  t0      press "A 50 fade 3s" on the mirror device (3 s fade to 50%)
+  t0+0.7  set the bulb directly to 90% (Home Assistant reports it to the mirror during the fade: held)
+  t0+1.4  same:  press "A 50 fade 3s" again (same target as the running fade)
+          many:  press "A many calls" (16 calls in one loop pass, the last one 100% with a 1 s fade)
+  t0+6.5  read the bulb, press Log state so the mirror prints its state
+"""
+
+import asyncio
+import sys
+import time
+
+from aioesphomeapi import APIClient, ButtonInfo, LightInfo, LightState
+
+DEV, KEY, BULB, CASE = sys.argv[1:5]
+BULB_KEY = sys.argv[5] if len(sys.argv) > 5 else "-"
+if CASE not in ("same", "many"):
+    sys.exit(f"case must be same or many, got {CASE!r}")
+T0 = time.time()
+
+
+def stamp() -> str:
+    return f"{time.time() - T0:6.3f}"
+
+
+async def main() -> None:
+    dev = APIClient(DEV, 6053, None, noise_psk=None if KEY == "-" else KEY)
+    bulb = APIClient(BULB, 6053, None, noise_psk=None if BULB_KEY == "-" else BULB_KEY)
+    await dev.connect(login=True)
+    await bulb.connect(login=True)
+    dents, _ = await dev.list_entities_services()
+    bents, _ = await bulb.list_entities_services()
+    buttons = {e.name: e for e in dents if isinstance(e, ButtonInfo)}
+    blight = next(e for e in bents if isinstance(e, LightInfo))
+    states = {}
+
+    def on_bulb(s) -> None:
+        if isinstance(s, LightState) and s.key == blight.key:
+            states["bulb"] = s
+            print(f"{stamp()} bulb state: on={s.state} bri={s.brightness:.2f}")
+
+    bulb.subscribe_states(on_bulb)
+    await asyncio.sleep(1.0)
+    print(f"{stamp()} >>> bulb to 100% (precondition)")
+    bulb.light_command(blight.key, state=True, brightness=1.0)
+    await asyncio.sleep(4.0)
+    t = time.time()
+    print(f"{stamp()} >>> t0 press A 50 fade 3s")
+    dev.button_command(buttons["A 50 fade 3s"].key)
+    await asyncio.sleep(0.7 - (time.time() - t))
+    print(f"{stamp()} >>> bulb direct to 90%")
+    bulb.light_command(blight.key, state=True, brightness=0.9)
+    await asyncio.sleep(1.4 - (time.time() - t))
+    name = "A 50 fade 3s" if CASE == "same" else "A many calls"
+    print(f"{stamp()} >>> press {name}")
+    dev.button_command(buttons[name].key)
+    await asyncio.sleep(6.5 - (time.time() - t))
+    print(f"{stamp()} >>> press Log state (the mirror's state is in the device log)")
+    dev.button_command(buttons["Log state"].key)
+    await asyncio.sleep(1.0)
+    b = states.get("bulb")
+    print(
+        f"{stamp()} RESULT bulb "
+        + (f"bri={b.brightness:.2f}" if b is not None else "no state")
+    )
+    await dev.disconnect()
+    await bulb.disconnect()
+
+
+asyncio.run(main())

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

@@ -0,0 +1,85 @@
+"""Drive LD2450 numbers and selects over the API while printing every LD2450 state update.
+usage: zonedrive.py HOST KEY(- for plaintext) OP [OP ...]
+  OP: set:NAME=VALUE | sel:NAME=OPTION | wait:SECONDS | list
+Every state update of an entity whose name contains "LD2450" is printed with a timestamp.
+"""
+
+import asyncio
+import sys
+import time
+
+from aioesphomeapi import (
+    APIClient,
+    NumberInfo,
+    NumberState,
+    SelectInfo,
+    SelectState,
+    SensorInfo,
+    SensorState,
+)
+
+HOST, KEY = 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:
+    c = APIClient(HOST, 6053, None, noise_psk=None if KEY == "-" else KEY)
+    await c.connect(login=True)
+    ents, _ = await c.list_entities_services()
+    by_key = {e.key: e for e in ents}
+    numbers = {e.name: e for e in ents if isinstance(e, NumberInfo)}
+    selects = {e.name: e for e in ents if isinstance(e, SelectInfo)}
+    sensors = {e.name: e for e in ents if isinstance(e, SensorInfo)}
+
+    def on_state(s) -> None:
+        e = by_key.get(s.key)
+        if e is None or "LD2450" not in e.name:
+            return
+        if isinstance(s, NumberState):
+            print(
+                f"{stamp()} NUM {e.name} = {s.state:.0f}{' (missing)' if s.missing_state else ''}"
+            )
+        elif isinstance(s, SelectState):
+            print(f"{stamp()} SEL {e.name} = {s.state}")
+        elif isinstance(s, SensorState) and "Count" in e.name:
+            print(f"{stamp()} CNT {e.name} = {s.state:.0f}")
+
+    c.subscribe_states(on_state)
+    await asyncio.sleep(1.5)
+    for op in OPS:
+        if op == "list":
+            for n in sorted(numbers):
+                print("number:", n)
+            for n in sorted(selects):
+                print("select:", n, selects[n].options)
+            for n in sorted(sensors):
+                if "Count" in n:
+                    print("sensor:", n)
+            continue
+        kind, _, rest = op.partition(":")
+        if kind == "wait":
+            await asyncio.sleep(float(rest))
+            continue
+        name, _, value = rest.partition("=")
+        if kind == "set":
+            if name not in numbers:
+                sys.exit(f"no number named {name!r}; have {sorted(numbers)}")
+            print(f"{stamp()} >>> set {name} = {value}")
+            c.number_command(numbers[name].key, float(value))
+        elif kind == "sel":
+            if name not in selects:
+                sys.exit(f"no select named {name!r}; have {sorted(selects)}")
+            print(f"{stamp()} >>> select {name} = {value}")
+            c.select_command(selects[name].key, value)
+        else:
+            sys.exit(f"unknown op {op!r}")
+        await asyncio.sleep(0.3)
+    await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/libretiny_crash/bkprobe.hpp

@@ -0,0 +1,116 @@
+// BK72xx crash probe: forces one crash per step and shows what the SDK and the bootloader leave behind.
+// Steps: 0 undefined instruction, 1 call into unmapped memory, 2 unmapped and unaligned accesses (no fault),
+// 3 lt_reboot(). The step lives in a flash preference saved and synced before the crash.
+#pragma once
+#include <Arduino.h>
+#include <FreeRTOS.h>
+#include <task.h>
+#include <cstdint>
+#include "esphome/core/hal.h"
+#include "esphome/core/log.h"
+#include "esphome/core/preferences.h"
+
+extern "C" unsigned bk_misc_get_start_type(void);
+extern "C" char _bss_end[];
+
+static constexpr uint32_t PROBE_CANARY_LOW = 0x004000F8;   // free word in the SDK-reserved low SRAM
+static constexpr uint32_t PROBE_CANARY_ITCM = 0x003F3FF0;  // top of ITCM
+static char bkprobe_report[112];
+static constexpr uint32_t PROBE_MARKS[] = {0x40A1B0, 0x40B000, 0x40C000, 0x40E000, 0x410000, 0x414000, 0x418000,
+                                           0x41C000, 0x420000, 0x428000, 0x430000, 0x438000, 0x43C000, 0x43E000,
+                                           0x43F000, 0x43F800, 0x43FC00, 0x43FE00, 0x43FFF0};
+static constexpr size_t PROBE_MARK_COUNT = sizeof(PROBE_MARKS) / sizeof(PROBE_MARKS[0]);
+
+static inline uint32_t rd(uint32_t a) { return *(volatile uint32_t *) a; }
+
+inline esphome::ESPPreferenceObject bkprobe_pref(uint32_t run) {
+  return esphome::global_preferences->make_preference<int>(0xBC000000u + run);
+}
+
+inline int bkprobe_boot(uint32_t run) {
+  using namespace esphome;
+  int step = 0;
+  bkprobe_pref(run).load(&step);
+  unsigned st = bk_misc_get_start_type();
+  snprintf(bkprobe_report, sizeof(bkprobe_report), "step=%d reason=%s(%d) start_type=%u low=%08lx itcm=%08lx top=%08lx",
+           step, lt_get_reboot_reason_name(lt_get_reboot_reason()), (int) lt_get_reboot_reason(), st,
+           (unsigned long) rd(PROBE_CANARY_LOW), (unsigned long) rd(PROBE_CANARY_ITCM),
+           (unsigned long) rd(0x0043FFF0u));
+  ESP_LOGI("probe", "%s", bkprobe_report);
+  for (uint32_t a = 0x400000; a < 0x400100; a += 32) {
+    ESP_LOGI("probe", "%06lx: %08lx %08lx %08lx %08lx %08lx %08lx %08lx %08lx", (unsigned long) a,
+             (unsigned long) rd(a), (unsigned long) rd(a + 4), (unsigned long) rd(a + 8), (unsigned long) rd(a + 12),
+             (unsigned long) rd(a + 16), (unsigned long) rd(a + 20), (unsigned long) rd(a + 24),
+             (unsigned long) rd(a + 28));
+  }
+  for (size_t i = 0; i < PROBE_MARK_COUNT; i += 7) {
+    char line[120];
+    int n = 0;
+    for (size_t j = i; j < i + 7 && j < PROBE_MARK_COUNT; j++)
+      n += snprintf(line + n, sizeof(line) - n, " %06lx=%08lx", (unsigned long) PROBE_MARKS[j],
+                    (unsigned long) rd(PROBE_MARKS[j]));
+    ESP_LOGI("probe", "marks%s", line);
+  }
+  uint32_t rec = ((uint32_t) _bss_end + 7) & ~7u;
+  for (uint32_t a = rec; a < rec + 64; a += 32) {
+    ESP_LOGI("probe", "rec %06lx: %08lx %08lx %08lx %08lx %08lx %08lx %08lx %08lx", (unsigned long) a,
+             (unsigned long) rd(a), (unsigned long) rd(a + 4), (unsigned long) rd(a + 8), (unsigned long) rd(a + 12),
+             (unsigned long) rd(a + 16), (unsigned long) rd(a + 20), (unsigned long) rd(a + 24),
+             (unsigned long) rd(a + 28));
+  }
+  *(volatile uint32_t *) PROBE_CANARY_LOW = 0xC0DE0000u | (uint32_t) step;
+  *(volatile uint32_t *) PROBE_CANARY_ITCM = 0x17C40000u | (uint32_t) step;
+  return step;
+}
+
+__attribute__((noinline)) void bkprobe_data_abort() {
+  using namespace esphome;
+  volatile uint32_t v = rd(0xFFFFFFF0);
+  ESP_LOGI("probe", "read 0xFFFFFFF0 -> %08lx (no fault)", (unsigned long) v);
+  uint32_t r;
+  __asm__ volatile("ldr %0, [%1]" : "=r"(r) : "r"(0x00400101) : "memory");
+  ESP_LOGI("probe", "unaligned ldr 0x400101 -> %08lx (no fault)", (unsigned long) r);
+  *(volatile uint32_t *) 0xFFFFFFF0 = 1;
+  ESP_LOGI("probe", "store 0xFFFFFFF0 (no fault)");
+}
+
+// act is the step number before it was bumped
+inline void bkprobe_act(uint32_t run, int act) {
+  using namespace esphome;
+  int next = act + 1;
+  bkprobe_pref(run).save(&next);
+  global_preferences->sync();
+  ESP_LOGI("probe", "acting on step %d (saved %d)", act, next);
+  // mark candidate storage areas so the next boot shows what survives
+  uint32_t rec = ((uint32_t) _bss_end + 7) & ~7u;
+  for (uint32_t i = 0; i < 8; i++)
+    *(volatile uint32_t *) (rec + 32 + i * 4) = 0xA5A50000u | i;  // second half of the record area
+  for (size_t i = 0; i < PROBE_MARK_COUNT; i++)
+    *(volatile uint32_t *) PROBE_MARKS[i] = 0x70700000u | (uint32_t) i;
+  ESP_LOGI("probe", "ramtop before: %08lx", (unsigned long) rd(0x0043FFF0u));
+  vTaskDelay(pdMS_TO_TICKS(50));
+  switch (act) {
+    case 0:
+      __builtin_trap();  // undefined instruction
+      break;
+    case 1: {
+      void (*fn)() = (void (*)()) 0xFFFFFFF1;  // prefetch abort (unmapped, Thumb)
+      fn();
+      ESP_LOGI("probe", "call 0xFFFFFFF1 returned (no fault)");
+      break;
+    }
+    case 2:
+      bkprobe_data_abort();
+      break;
+    case 3:
+      lt_reboot();
+      break;
+    default:
+      break;
+  }
+}
+
+inline void bkprobe_alive(int step) {
+  using namespace esphome;
+  ESP_LOGI("probe", "alive step=%d uptime=%lus boot: %s", step, (unsigned long) (millis() / 1000), bkprobe_report);
+}

.agents/skills/hardware-test/scripts/libretiny_crash/decode_capture.py

@@ -0,0 +1,25 @@
+"""Feed a serial capture through the CLI's stacktrace decoder for a build.
+
+usage: decode_capture.py CONFIG_YAML CAPTURE
+
+Run from the directory that holds the config (its .esphome build is used), with the esphome checkout that
+built it on PYTHONPATH. Lines of the crash report are echoed, decoded frames follow them.
+"""
+
+import logging
+from pathlib import Path
+import sys
+
+from esphome.config import read_config
+from esphome.core import CORE
+from esphome.stacktrace import LogLineProcessor
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
+yaml, capture = Path(sys.argv[1]), Path(sys.argv[2])
+CORE.config_path = yaml
+config = read_config({})
+proc = LogLineProcessor(config, CORE.target_platform)
+for line in capture.read_text(encoding="utf-8", errors="replace").splitlines():
+    if "libretiny.crash" in line:
+        print(line[:120])
+    proc.process_line(line)

.agents/skills/hardware-test/scripts/libretiny_prefs/ltprefs.hpp

@@ -0,0 +1,155 @@
+#pragma once
+// BK7238 bench harness for esphome#21007: one rtc and one flash preference, a step counter in flash,
+// and an exit action per step so the board drives its own soft reboot, crash and watchdog reboot.
+#include <libretiny.h>
+#include <cstring>
+#include <FreeRTOS.h>
+#include <task.h>
+#include "esphome/core/hal.h"
+#include "esphome/core/log.h"
+#include "esphome/core/preferences.h"
+
+using namespace esphome;
+
+// Boot report kept for the alive line, so a boot the host could not capture is still visible
+static char ltprefs_report[128];
+// Last boots' reports, kept in a flash preference so boots the host never saw stay readable
+struct LtprefsHistory {
+  char line[8][128];
+};
+static LtprefsHistory ltprefs_hist;
+
+inline ESPPreferenceObject ltprefs_step_pref(uint32_t run) {
+  return global_preferences->make_preference<int>(0x3B210070u ^ run, true);
+}
+
+// Loads the step and both preferences, logs them, saves this step's value.
+// Returns the exit action: 0 idle, 1 lt_reboot, 2 crash, 3 watchdog.
+inline int ltprefs_boot(int &step, uint32_t run) {
+  auto reason = lt_get_reboot_reason();
+  step = 0;
+  ltprefs_step_pref(run).load(&step);
+  auto rtcp = global_preferences->make_preference<uint32_t>(0x1B210070u ^ run, false);
+  auto flp = global_preferences->make_preference<uint32_t>(0x2B210070u ^ run, true);
+  uint32_t rv = 0, fv = 0;
+  // a second pair sharing one key as rtc and as flash, and a third rtc entry, so a hard reset drops three
+  auto rtcp2 = global_preferences->make_preference<uint32_t>(0x5B210070u ^ run, false);
+  auto flp2 = global_preferences->make_preference<uint32_t>(0x5B210070u ^ run, true);
+  auto rtcp3 = global_preferences->make_preference<uint32_t>(0x6B210070u ^ run, false);
+  uint32_t rv2 = 0, fv2 = 0, rv3 = 0;
+  bool rok = rtcp.load(&rv);
+  bool fok = flp.load(&fv);
+  bool rok2 = rtcp2.load(&rv2);
+  bool fok2 = flp2.load(&fv2);
+  bool rok3 = rtcp3.load(&rv3);
+  snprintf(ltprefs_report, sizeof(ltprefs_report),
+           "step=%d reason=%s(%d) rtc=%s%u flash=%s%u sharedkey rtc=%s%u flash=%s%u rtc3=%s%u", step,
+           lt_get_reboot_reason_name(reason), (int) reason, rok ? "" : "none ", rv, fok ? "" : "none ", fv,
+           rok2 ? "" : "none ", rv2, fok2 ? "" : "none ", fv2, rok3 ? "" : "none ", rv3);
+  ESP_LOGI("lttest", "%s", ltprefs_report);
+  auto histp = global_preferences->make_preference<LtprefsHistory>(0x4B210070u ^ run, true);
+  if (!histp.load(&ltprefs_hist))
+    memset(&ltprefs_hist, 0, sizeof(ltprefs_hist));
+  memmove(&ltprefs_hist.line[1], &ltprefs_hist.line[0], sizeof(ltprefs_hist.line) - sizeof(ltprefs_hist.line[0]));
+  strncpy(ltprefs_hist.line[0], ltprefs_report, sizeof(ltprefs_hist.line[0]) - 1);
+  ltprefs_hist.line[0][sizeof(ltprefs_hist.line[0]) - 1] = 0;
+  if (!histp.save(&ltprefs_hist)) {
+    ESP_LOGW("lttest", "history save failed");
+  }
+  int act = 0;
+  bool save = true;
+  switch (step) {
+    case 0:
+      act = 1;
+      break;  // soft reboot
+    case 1:
+      act = 2;
+      break;  // crash
+    case 2:
+      act = 3;
+      break;  // watchdog
+    case 3:
+      act = 0;
+      break;  // idle: chip-enable reset from the host
+    case 4:
+      act = 1;
+      break;  // soft reboot after the hard reset
+    case 5:
+      act = 0;
+      break;  // idle: chip-enable reset from the host
+    case 6:
+      act = 1;
+      save = false;
+      break;  // no save, soft reboot: deleted, not skipped?
+    case 7:
+      act = 0;
+      break;  // idle
+    case 8:
+      act = 2;
+      break;  // crash
+    case 9:
+      act = 0;
+      break;  // idle
+    case 10:
+      act = 0;
+      break;  // idle: power cut by the user
+    default:
+      act = 0;
+      save = false;
+      break;
+  }
+  if (save) {
+    uint32_t v = 100 + step, v2r = 200 + step, v2f = 300 + step, v3 = 400 + step;
+    bool srtc = rtcp.save(&v);
+    bool sfl = flp.save(&v);
+    bool srtc2 = rtcp2.save(&v2r);
+    bool sfl2 = flp2.save(&v2f);
+    bool srtc3 = rtcp3.save(&v3);
+    bool synced = global_preferences->sync();
+    ESP_LOGI("lttest", "save %u/%u/%u/%u: rtc=%d flash=%d sharedkey rtc=%d flash=%d rtc3=%d sync=%d", v, v2r, v2f, v3,
+             srtc, sfl, srtc2, sfl2, srtc3, synced);
+  }
+  ESP_LOGI("lttest", "exit action=%d", act);
+  return act;
+}
+
+inline void ltprefs_exit(int &step, uint32_t run, int act) {
+  step++;
+  bool saved = ltprefs_step_pref(run).save(&step);
+  bool synced = global_preferences->sync();
+  ESP_LOGI("lttest", "step %d save=%d sync=%d", step, saved, synced);
+  if (!saved || !synced) {
+    ESP_LOGE("lttest", "step not stored, staying idle instead of repeating the step");
+    return;
+  }
+  vTaskDelay(pdMS_TO_TICKS(200));
+  switch (act) {
+    case 1:
+      ESP_LOGW("lttest", "soft reboot now");
+      vTaskDelay(pdMS_TO_TICKS(50));
+      lt_reboot();
+      break;
+    case 2:
+      ESP_LOGW("lttest", "crashing now");
+      vTaskDelay(pdMS_TO_TICKS(50));
+      __builtin_trap();  // undefined instruction: a plain bad store does not fault on the ARM968
+      break;
+    case 3:
+      ESP_LOGW("lttest", "watchdog reboot now");
+      vTaskDelay(pdMS_TO_TICKS(50));
+      lt_reboot_wdt();
+      break;
+    default:
+      ESP_LOGW("lttest", "idle, waiting for an external reset");
+      break;
+  }
+}
+
+inline void ltprefs_alive(int step, int act) {
+  ESP_LOGI("lttest", "alive step=%d act=%d boot: %s", step, act, ltprefs_report);
+  for (int i = 7; i >= 0; i--) {
+    if (ltprefs_hist.line[i][0] != 0) {
+      ESP_LOGI("lttest", "  history[-%d]: %s", i, ltprefs_hist.line[i]);
+    }
+  }
+}

.agents/skills/hardware-test/scripts/online_image/drive.py

@@ -0,0 +1,179 @@
+"""Drive the online_image cases over the native API and judge each from the serial capture."""
+
+import asyncio
+import pathlib
+import re
+import sys
+import time
+
+from aioesphomeapi import (
+    APIClient,
+    APIConnectionError,
+    InvalidEncryptionKeyAPIError,
+    RequiresEncryptionAPIError,
+)
+
+HOST, KEY, CAPTURE, BASE, MODE = sys.argv[1:6]
+CAP_S = 45
+
+CASES = [
+    # (label, action, path, expected outcome)
+    ("ok bmp", "fetch", "ok.bmp", "finished"),
+    ("ok png", "fetch", "ok.png", "finished"),
+    ("ok jpg", "fetch", "ok.jpg", "finished"),
+    ("ok qoi", "fetch", "ok.qoi", "finished"),
+    ("truncated bmp", "fetch", "truncated.bmp", "error"),
+    ("ok bmp after error", "fetch", "ok.bmp", "finished"),
+    ("large header, 256 byte buffer", "fetch_small", "large_header.bmp", "error"),
+    ("ok bmp, 256 byte buffer", "fetch_small", "ok.bmp", "finished"),
+    ("empty body", "fetch", "empty.bmp", "error"),
+    ("stalled connection", "fetch", "stall.bmp", "error"),
+    ("closed early", "fetch", "closed_early.bmp", "error"),
+    ("slow but alive", "fetch", "slow.bmp", "finished"),
+    ("chunked bmp", "fetch", "chunked.bmp", "finished"),
+    ("chunked png", "fetch", "chunked.png", "finished"),
+    ("chunked qoi", "fetch", "chunked.qoi", "finished"),
+    ("chunked bmp cut", "fetch", "chunked_cut.bmp", "error"),
+    ("chunked png cut", "fetch", "chunked_cut.png", "any"),
+    ("no content-length", "fetch", "noclen.bmp", "any"),
+    ("huge jpeg claim", "fetch", "huge.jpg", "error"),
+    ("ok jpg after huge", "fetch", "ok.jpg", "finished"),
+    ("ok bmp again", "fetch", "ok.bmp", "finished"),
+    ("ok bmp refetch: 304", "refetch", "", "finished"),
+    ("ok png", "fetch", "ok.png", "finished"),
+    ("ok png refetch: 304", "refetch", "", "finished"),
+    ("chunked bmp", "fetch", "chunked.bmp", "finished"),
+    ("chunked bmp refetch: 304", "refetch", "", "finished"),
+    ("chunked png", "fetch", "chunked.png", "finished"),
+    ("chunked png refetch: not cached", "refetch", "", "finished"),
+    ("chunked png cut", "fetch", "chunked_cut.png", "any"),
+    ("chunked png cut refetch: not cached", "refetch", "", "any"),
+]
+if MODE == "base":
+    # Each stuck case is followed by a fetch that shows the symptom, then a reboot.
+    CASES = [
+        ("ok bmp", "fetch", "ok.bmp", "finished"),
+        ("truncated bmp", "fetch", "truncated.bmp", "error"),
+        ("ok bmp after truncated", "fetch", "ok.bmp", "finished"),
+        ("REBOOT", "", "", ""),
+        ("large header, 256 byte buffer", "fetch_small", "large_header.bmp", "error"),
+        ("ok bmp, 256 byte buffer", "fetch_small", "ok.bmp", "finished"),
+        ("REBOOT", "", "", ""),
+        ("empty body", "fetch", "empty.bmp", "error"),
+        ("ok bmp after empty", "fetch", "ok.bmp", "finished"),
+        ("REBOOT", "", "", ""),
+        ("stalled connection", "fetch", "stall.bmp", "error"),
+        ("ok bmp after stall", "fetch", "ok.bmp", "finished"),
+        ("REBOOT", "", "", ""),
+        ("closed early", "fetch", "closed_early.bmp", "error"),
+        ("ok bmp after closed early", "fetch", "ok.bmp", "finished"),
+        ("REBOOT", "", "", ""),
+        ("chunked png", "fetch", "chunked.png", "finished"),
+        ("ok bmp after chunked png", "fetch", "ok.bmp", "finished"),
+        ("REBOOT", "", "", ""),
+        ("chunked bmp cut", "fetch", "chunked_cut.bmp", "error"),
+        ("ok bmp after chunked cut", "fetch", "ok.bmp", "finished"),
+        ("REBOOT", "", "", ""),
+        ("huge jpeg claim", "fetch", "huge.jpg", "error"),
+        ("ok jpg after huge", "fetch", "ok.jpg", "finished"),
+    ]
+
+OUTCOME = re.compile(r"download (finished|error): (img_small|img)")
+INTEREST = re.compile(
+    r"\[(E|W)\]\[online_image|Image already being updated|download (finished|error)|Downloading image|Updating image|Image fully downloaded|HTTP 304|allocat|Panic|abort\(\)|Guru|Backtrace|rst:0x",
+    re.IGNORECASE,
+)
+
+
+def tail(path: str, offset: int) -> tuple[list[str], int]:
+    with pathlib.Path(path).open("rb") as f:
+        f.seek(offset)
+        data = f.read()
+    return data.decode("utf-8", "replace").splitlines(), offset + len(data)
+
+
+async def connect() -> tuple[APIClient, dict, int]:
+    for _ in range(60):
+        try:
+            c = APIClient(HOST, 6053, None, noise_psk=KEY)
+            await c.connect(login=True)
+            ents, services = await c.list_entities_services()
+        except (InvalidEncryptionKeyAPIError, RequiresEncryptionAPIError) as exc:
+            raise SystemExit(f"API key problem, not retrying: {exc}") from exc
+        except (APIConnectionError, OSError) as exc:
+            # only connection trouble is retried; a wrong key or a missing button must fail at once
+            print(f"connect: {exc}", flush=True)
+            await asyncio.sleep(3)
+            continue
+        btn = next(
+            (e.key for e in ents if getattr(e, "object_id", "") == "reboot"), None
+        )
+        if btn is None:
+            raise SystemExit("the config has no reboot button")
+        return c, {s.name: s for s in services}, btn
+    raise SystemExit("API never connected")
+
+
+async def main() -> None:
+    client, actions, btn = await connect()
+    with pathlib.Path(CAPTURE).open("rb") as f:
+        f.seek(0, 2)
+        offset = f.tell()
+    rows = []
+    for label, action, path, expect in CASES:
+        if label == "REBOOT":
+            client.button_command(btn)
+            await asyncio.sleep(1)
+            await client.disconnect()
+            await asyncio.sleep(8)
+            client, actions, btn = await connect()
+            _, offset = tail(CAPTURE, offset)
+            print("--- rebooted", flush=True)
+            continue
+        img = "img_small" if action.endswith("_small") else "img"
+        t0 = time.monotonic()
+        args = {} if action.startswith("refetch") else {"url": f"{BASE}/{path}"}
+        await client.execute_service(actions[action], args)
+        outcome, notes = "no outcome", []
+        while time.monotonic() - t0 < CAP_S:
+            await asyncio.sleep(0.5)
+            lines, offset = tail(CAPTURE, offset)
+            done = False
+            for line in lines:
+                if INTEREST.search(line):
+                    notes.append(line.strip())
+                m = OUTCOME.search(line)
+                if m and m.group(2) == img:
+                    outcome = m.group(1)
+                    done = True
+            if done:
+                break
+        took = time.monotonic() - t0
+        if outcome == "no outcome":
+            took = CAP_S
+            # drain a little more so the "already being updated" line lands
+            await asyncio.sleep(1)
+            lines, offset = tail(CAPTURE, offset)
+            notes += [line.strip() for line in lines if INTEREST.search(line)]
+        ok = outcome == expect or (expect == "any" and outcome != "no outcome")
+        rows.append((label, path, expect, outcome, took, ok, notes))
+        print(
+            f"{'PASS' if ok else 'FAIL'} {label:32s} {path:18s} expected {expect:9s} got {outcome:10s} {took:5.1f}s",
+            flush=True,
+        )
+        for n in notes:
+            print(f"      {n}", flush=True)
+        await asyncio.sleep(1.5)
+    await client.disconnect()
+    print(
+        "\nSUMMARY",
+        "all expectations met"
+        if all(r[5] for r in rows)
+        else "MISMATCHES: " + ", ".join(r[0] for r in rows if not r[5]),
+        flush=True,
+    )
+    if not all(r[5] for r in rows):
+        sys.exit(1)
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/online_image/make_images.py

@@ -0,0 +1,38 @@
+"""Build the small test images the HTTP server serves."""
+
+from pathlib import Path
+import struct
+import sys
+
+from PIL import Image
+
+out = Path(sys.argv[1])
+out.mkdir(exist_ok=True)
+w = h = 16
+im = Image.new("RGB", (w, h))
+px = im.load()
+for y in range(h):
+    for x in range(w):
+        px[x, y] = (x * 16, y * 16, (x + y) * 8)
+im.save(out / "ok.bmp", "BMP")
+im.save(out / "ok.png", "PNG")
+im.save(out / "ok.jpg", "JPEG", quality=90)
+
+# QOI with only QOI_OP_RGB codes: valid and trivially encoded.
+qoi = b"qoif" + struct.pack(">IIBB", w, h, 3, 0)
+for y in range(h):
+    for x in range(w):
+        qoi += bytes([0xFE, *px[x, y]])
+qoi += bytes(7) + b"\x01"
+(out / "ok.qoi").write_bytes(qoi)
+
+# 8x8 8-bit palette BMP: 1078 byte header, pixels start beyond a 256 byte buffer.
+pw = ph = 8
+data_offset = 14 + 40 + 256 * 4
+file_size = data_offset + pw * ph
+hdr = b"BM" + struct.pack("<IHHI", file_size, 0, 0, data_offset)
+dib = struct.pack("<IiiHHIIiiII", 40, pw, ph, 1, 8, 0, pw * ph, 0, 0, 256, 0)
+(out / "large_header.bmp").write_bytes(hdr + dib + bytes(256 * 4) + bytes(pw * ph))
+
+for p in sorted(out.iterdir()):
+    print(p.name, p.stat().st_size)

.agents/skills/hardware-test/scripts/online_image/oi_server.py

@@ -0,0 +1,142 @@
+"""HTTP server with one misbehaviour per path, for the online_image stalled-download test."""
+
+import asyncio
+from pathlib import Path
+import sys
+import time
+
+WWW = Path(sys.argv[1])
+PORT = int(sys.argv[2])
+LOG = Path(sys.argv[3]).open("a", encoding="utf-8", buffering=1)  # noqa: SIM115
+
+MIME = {"bmp": "image/bmp", "png": "image/png", "jpg": "image/jpeg", "qoi": "image/qoi"}
+IMG = {n: (WWW / f"ok.{n}").read_bytes() for n in MIME}
+BMP = IMG["bmp"]
+BMP_HDR = 54  # 16x16 24-bit: pixel rows follow directly
+LARGE_HEADER = (WWW / "large_header.bmp").read_bytes()
+
+
+def log(msg: str) -> None:
+    LOG.write(f"{time.strftime('%H:%M:%S')} {msg}\n")
+
+
+def headers(ctype: str, extra: list[bytes]) -> bytes:
+    lines = [
+        b"HTTP/1.1 200 OK",
+        b"Content-Type: " + ctype.encode(),
+        b"Connection: close",
+        *extra,
+        b"",
+        b"",
+    ]
+    return b"\r\n".join(lines)
+
+
+def etag(path: str) -> bytes:
+    return b'"' + path.strip("/").encode() + b'-v1"'
+
+
+def chunked(body: bytes, size: int) -> bytes:
+    out = b""
+    for i in range(0, len(body), size):
+        part = body[i : i + size]
+        out += b"%x\r\n" % len(part) + part + b"\r\n"
+    return out + b"0\r\n\r\n"
+
+
+async def respond(path: str, req: bytes, w: asyncio.StreamWriter) -> str:
+    name, _, ext = path.lstrip("/").rpartition(".")
+    ctype = MIME.get(ext, "application/octet-stream")
+    body = IMG.get(ext, BMP)
+    tag = [b"ETag: " + etag(path)]
+    if b"if-none-match: " + etag(path).lower() in req.lower():
+        w.write(
+            b"HTTP/1.1 304 Not Modified\r\nETag: "
+            + etag(path)
+            + b"\r\nConnection: close\r\n\r\n"
+        )
+        return "304 not modified"
+    if name == "ok":
+        w.write(headers(ctype, [b"Content-Length: %d" % len(body), *tag]) + body)
+        return f"full {len(body)} bytes"
+    if name == "truncated":  # cut one byte into the sixth pixel, Content-Length matches
+        cut = BMP[: BMP_HDR + 5 * 3 + 1]
+        w.write(headers(ctype, [b"Content-Length: %d" % len(cut)]) + cut)
+        return f"truncated {len(cut)} bytes"
+    if name == "large_header":
+        w.write(
+            headers(ctype, [b"Content-Length: %d" % len(LARGE_HEADER)]) + LARGE_HEADER
+        )
+        return f"large header {len(LARGE_HEADER)} bytes"
+    if name == "empty":
+        w.write(headers(ctype, [b"Content-Length: 0"]))
+        return "empty body"
+    if (
+        name == "stall"
+    ):  # claims the full length, sends part, then holds the socket open
+        part = body[: BMP_HDR + 15]
+        w.write(headers(ctype, [b"Content-Length: %d" % len(body)]) + part)
+        await w.drain()
+        await asyncio.sleep(40)
+        return f"stalled after {len(part)} bytes, closed after 40 s"
+    if name == "closed_early":  # claims the full length, sends part, closes at once
+        part = body[: BMP_HDR + 15]
+        w.write(headers(ctype, [b"Content-Length: %d" % len(body)]) + part)
+        return f"closed after {len(part)} of {len(body)} bytes"
+    if name == "slow":  # pauses under the timeout, then completes
+        w.write(headers(ctype, [b"Content-Length: %d" % len(body)]) + body[:BMP_HDR])
+        await w.drain()
+        await asyncio.sleep(2.5)
+        w.write(body[BMP_HDR:])
+        return f"full {len(body)} bytes with a 2.5 s pause"
+    if name == "chunked":
+        w.write(
+            headers(ctype, [b"Transfer-Encoding: chunked", *tag]) + chunked(body, 64)
+        )
+        return f"chunked full {len(body)} bytes"
+    if (
+        name == "chunked_cut"
+    ):  # chunked, ends cleanly at a pixel boundary (or half a png)
+        cut = body[: BMP_HDR + 5 * 3] if ext == "bmp" else body[: len(body) // 2]
+        w.write(
+            headers(ctype, [b"Transfer-Encoding: chunked", *tag]) + chunked(cut, 64)
+        )
+        return f"chunked cut {len(cut)} of {len(body)} bytes"
+    if name == "noclen":  # body delimited by connection close
+        w.write(headers(ctype, []) + body)
+        return f"no content-length, full {len(body)} bytes"
+    if name == "huge":  # claims 20 MB so the JPEG buffer resize fails
+        w.write(headers(ctype, [b"Content-Length: 20000000"]) + body)
+        return f"claims 20000000, sent {len(body)} bytes"
+    w.write(b"HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
+    return "404"
+
+
+async def handle(r: asyncio.StreamReader, w: asyncio.StreamWriter) -> None:
+    peer = w.get_extra_info("peername")
+    try:
+        async with asyncio.timeout(5):
+            line = await r.readuntil(b"\r\n")
+            req = await r.readuntil(b"\r\n\r\n")
+        path = line.split(b" ")[1].decode()
+        log(
+            f"GET {path} from {peer}"
+            + (" (If-None-Match)" if b"if-none-match" in req.lower() else "")
+        )
+        what = await respond(path, req, w)
+        await w.drain()
+        log(f"  -> {path}: {what}")
+    except Exception as exc:  # noqa: BLE001
+        log(f"  !! {peer}: {exc!r}")
+    finally:
+        w.close()
+
+
+async def main() -> None:
+    server = await asyncio.start_server(handle, "0.0.0.0", PORT)
+    log(f"listening on {PORT}")
+    async with server:
+        await server.serve_forever()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/rtsp_server/cam_api.py

@@ -0,0 +1,33 @@
+"""Request one camera image over the native API and report its size (direct esp32_camera check)."""
+
+import asyncio
+import sys
+
+from aioesphomeapi import APIClient
+
+
+async def main():
+    c = APIClient(sys.argv[1], 6053, None)
+    await c.connect(login=True)
+    ents, _ = await c.list_entities_services()
+    cams = [e for e in ents if type(e).__name__ == "CameraInfo"]
+    print("camera entities:", [e.name for e in cams])
+    got = asyncio.get_event_loop().create_future()
+
+    def on_state(state):
+        if type(state).__name__ == "CameraState" and not got.done():
+            got.set_result(len(state.data))
+
+    c.subscribe_states(on_state)
+    c.request_single_image()
+    try:
+        n = await asyncio.wait_for(got, 10)
+        print("single image bytes:", n)
+    except TimeoutError:
+        print("no image within 10 s")
+        await c.disconnect()
+        sys.exit(1)
+    await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/rtsp_server/measure.sh

@@ -0,0 +1,32 @@
+#!/bin/zsh
+# usage: measure.sh IP LABEL LOGFILE [OUTDIR]
+# Runs the fixed RTSP measurement set against one build and appends a result line to OUTDIR/results.txt:
+# ping RTT, two 12 s ffmpeg runs, two concurrent ffmpeg clients, and the raw receive rate with the default
+# and a 1 MiB socket buffer. LOGFILE is the device capture, used to count "stalled" drops during the run.
+# A measurement that produced nothing is written as ERR and the script exits 1, so a broken run never looks
+# like a measured one. Needs ffmpeg and a python with the rtsp scripts' dependencies (PYTHON, default python3).
+D=${0:A:h}
+IP=$1; LABEL=$2; LOG=$3; S=${4:-.}
+PY=${PYTHON:-python3}
+[ -f "$LOG" ] || { echo "device capture not found: $LOG"; exit 1; }
+rtt=$(ping -c 10 -i 0.2 $IP 2>&1 | tail -1 | awk -F/ '{print $5}')
+stall0=$(grep -a -c "stalled" $LOG)
+frames() {  # OUTFILE RC: the frame count of a run that finished on its own, nothing for a failed or killed one
+  [ "$2" = 0 ] && grep -o 'frame= *[0-9]*' $1 | tail -1 | tr -dc 0-9
+}
+timeout 40 ffmpeg -hide_banner -rtsp_transport tcp -i rtsp://$IP:554/ -t 12 -f null - > $S/m-f1.txt 2>&1; f1=$(frames $S/m-f1.txt $?); sleep 2
+timeout 40 ffmpeg -hide_banner -rtsp_transport tcp -i rtsp://$IP:554/ -t 12 -f null - > $S/m-f2.txt 2>&1; f2=$(frames $S/m-f2.txt $?); sleep 2
+timeout 40 ffmpeg -hide_banner -rtsp_transport tcp -i rtsp://$IP:554/ -t 12 -f null - > $S/m-twoA.txt 2>&1 & A=$!; sleep 1
+timeout 40 ffmpeg -hide_banner -rtsp_transport tcp -i rtsp://$IP:554/ -t 12 -f null - > $S/m-twoB.txt 2>&1 & B=$!
+wait $A; ra=$?; wait $B; rb=$?
+fa=$(frames $S/m-twoA.txt $ra); fb=$(frames $S/m-twoB.txt $rb); sleep 2
+timeout 40 $PY $D/rawrate2.py $IP quiet > $S/m-raw.txt 2>&1 && raw=$(grep -o "[0-9.]* KiB/s" $S/m-raw.txt | head -1); sleep 2
+timeout 40 $PY $D/rawrate2.py $IP bigbuf > $S/m-raw2.txt 2>&1 && raw2=$(grep -o "[0-9.]* KiB/s" $S/m-raw2.txt | head -1); sleep 1
+stall1=$(grep -a -c "stalled" $LOG)
+bad=0
+for v in rtt f1 f2 fa fb raw raw2; do
+  if [ -z "${(P)v}" ]; then eval "$v=ERR"; bad=1; fi
+done
+line="$LABEL | rtt avg ${rtt} ms | ffmpeg single 12 s: ${f1}, ${f2} frames | two clients: ${fa} + ${fb} | python raw: ${raw} (1 MiB rcvbuf ${raw2}) | stalls logged: $((stall1 - stall0))"
+echo "$line" | tee -a $S/results.txt
+if [ $bad = 1 ]; then echo "one or more measurements failed (ERR above)"; exit 1; fi

.agents/skills/hardware-test/scripts/rtsp_server/rawrate2.py

@@ -0,0 +1,83 @@
+import contextlib
+import socket
+import sys
+import time
+
+IP = sys.argv[1]
+mode = sys.argv[2]
+secs = 8
+s = socket.create_connection((IP, 554), timeout=5)
+if mode == "bigbuf":
+    s.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, 1 << 20)
+cseq = 0
+
+
+buf = b""
+
+
+def read_response() -> bytes:
+    """One complete RTSP response: headers through the blank line plus a Content-Length body."""
+    global buf  # noqa: PLW0603
+    while (end := buf.find(b"\r\n\r\n")) < 0:
+        chunk = s.recv(4096)
+        if not chunk:
+            raise ConnectionError("closed")
+        buf += chunk
+    head = buf[:end].decode(errors="replace")
+    body_len = 0
+    for line in head.split("\r\n"):
+        if line.lower().startswith("content-length:"):
+            body_len = int(line.split(":", 1)[1])
+    while len(buf) < end + 4 + body_len:
+        chunk = s.recv(4096)
+        if not chunk:
+            raise ConnectionError("closed")
+        buf += chunk
+    resp, buf = buf[: end + 4 + body_len], buf[end + 4 + body_len :]
+    return resp
+
+
+def req(m, extra="", wait=True):
+    global cseq  # noqa: PLW0603
+    cseq += 1
+    url = f"rtsp://{IP}:554/trackID=0" if m == "SETUP" else f"rtsp://{IP}:554/"
+    s.sendall(f"{m} {url} RTSP/1.0\r\nCSeq: {cseq}\r\n{extra}\r\n".encode())
+    return read_response() if wait else b""
+
+
+req("OPTIONS")
+req("DESCRIBE", "Accept: application/sdp\r\n")
+r = req("SETUP", "Transport: RTP/AVP/TCP;unicast;interleaved=0-1\r\n")
+sess = (
+    [x for x in r.decode(errors="replace").split("\r\n") if x.startswith("Session")][0]
+    .split()[1]
+    .split(";")[0]
+)
+req("PLAY", f"Session: {sess}\r\n")
+t0 = time.monotonic()
+total = 0
+chunks = 0
+last_chat = t0
+s.settimeout(2)
+while time.monotonic() - t0 < secs:
+    now = time.monotonic()
+    if mode == "chatty" and now - last_chat > 0.2:
+        req("GET_PARAMETER", f"Session: {sess}\r\n", wait=False)
+        last_chat = now
+    if mode == "rtcp" and now - last_chat > 0.2:
+        s.sendall(b"$\x01\x00\x08" + b"\x80\xc9\x00\x01\x00\x00\x00\x01")
+        last_chat = now
+    try:
+        d = s.recv(65536)
+    except TimeoutError:
+        continue
+    if not d:
+        break
+    total += len(d)
+    chunks += 1
+print(
+    f"{mode:7s}: {total / 1024 / secs:5.1f} KiB/s, {chunks} recvs, avg {total // max(chunks, 1)} B/recv"
+)
+with contextlib.suppress(OSError):
+    req("TEARDOWN", f"Session: {sess}\r\n")
+s.close()

.agents/skills/hardware-test/scripts/rtsp_server/rtsp_client.py

@@ -0,0 +1,345 @@
+"""Raw RTSP/TCP client for the esphome rtsp_server hardware test.
+
+usage: rtsp_client.py HOST [case ...]
+cases: play, udp, pipeline, third, stall, teardown, getparam, badreq, replay, timeout
+"""
+
+import socket
+import struct
+import sys
+import time
+
+HOST = sys.argv[1]
+PORT = 554
+cases = sys.argv[2:] or [
+    "play",
+    "udp",
+    "pipeline",
+    "badreq",
+    "replay",
+    "getparam",
+    "teardown",
+    "third",
+    "stall",
+]
+results = []
+
+
+def say(case, ok, detail):
+    results.append((case, ok, detail))
+    print(f"{'PASS' if ok else 'FAIL'} {case}: {detail}", flush=True)
+
+
+class Client:
+    def __init__(self, timeout=5):
+        self.s = socket.create_connection((HOST, PORT), timeout=timeout)
+        self.cseq = 0
+        self.session = None
+        self.buf = b""
+
+    def send(self, method, extra="", url=None):
+        self.cseq += 1
+        url = (
+            url or f"rtsp://{HOST}:{PORT}/trackID=0"
+            if method == "SETUP"
+            else (url or f"rtsp://{HOST}:{PORT}/")
+        )
+        req = f"{method} {url} RTSP/1.0\r\nCSeq: {self.cseq}\r\n"
+        if self.session:
+            req += f"Session: {self.session}\r\n"
+        req += extra + "\r\n"
+        self.s.sendall(req.encode())
+        return self.cseq
+
+    def _recv(self):
+        chunk = self.s.recv(4096)
+        if not chunk:
+            raise ConnectionError("closed")
+        self.buf += chunk
+
+    def read_response(self):
+        # Read until a full RTSP response (headers + optional body); skip any interleaved data in between
+        while True:
+            if self.buf.startswith(b"$"):
+                if len(self.buf) < 4:
+                    self._recv()
+                    continue
+                ln = struct.unpack(">H", self.buf[2:4])[0]
+                if len(self.buf) < 4 + ln:
+                    self._recv()
+                    continue
+                self.buf = self.buf[4 + ln :]
+                continue
+            end = self.buf.find(b"\r\n\r\n")
+            if end < 0:
+                self._recv()
+                continue
+            head = self.buf[:end].decode(errors="replace")
+            body_len = 0
+            for line in head.split("\r\n"):
+                if line.lower().startswith("content-length:"):
+                    body_len = int(line.split(":", 1)[1])
+            while len(self.buf) < end + 4 + body_len:
+                self._recv()
+            body = self.buf[end + 4 : end + 4 + body_len]
+            self.buf = self.buf[end + 4 + body_len :]
+            status = int(head.split(" ", 2)[1])
+            for line in head.split("\r\n"):
+                if line.lower().startswith("session:"):
+                    self.session = line.split(":", 1)[1].strip().split(";")[0]
+            return status, head, body
+
+    def read_frames(self, seconds):
+        """Collect interleaved RTP packets on channel 0 for `seconds`; return (frames, packets, seq_gaps, sizes)."""
+        deadline = time.monotonic() + seconds
+        frames = 0
+        packets = 0
+        gaps = 0
+        last_seq = None
+        cur = 0
+        sizes = []
+        self.s.settimeout(1.0)
+        while time.monotonic() < deadline:
+            try:
+                chunk = self.s.recv(65536)
+            except TimeoutError:
+                continue
+            if not chunk:
+                break
+            self.buf += chunk
+            while True:
+                if len(self.buf) < 4 or self.buf[0:1] != b"$":
+                    if self.buf and self.buf[0:1] != b"$":
+                        end = self.buf.find(b"\r\n\r\n")
+                        if end < 0:
+                            break
+                        self.buf = self.buf[end + 4 :]
+                        continue
+                    break
+                ch = self.buf[1]
+                ln = struct.unpack(">H", self.buf[2:4])[0]
+                if len(self.buf) < 4 + ln:
+                    break
+                pkt = self.buf[4 : 4 + ln]
+                self.buf = self.buf[4 + ln :]
+                if ch != 0 or len(pkt) < 12:
+                    continue
+                packets += 1
+                seq = struct.unpack(">H", pkt[2:4])[0]
+                marker = pkt[1] & 0x80
+                if last_seq is not None and seq != ((last_seq + 1) & 0xFFFF):
+                    gaps += 1
+                last_seq = seq
+                cur += len(pkt) - 12
+                if marker:
+                    frames += 1
+                    sizes.append(cur)
+                    cur = 0
+        return frames, packets, gaps, sizes
+
+    def close(self):
+        self.s.close()
+
+
+def setup_play(c):
+    c.send("OPTIONS")
+    st, head, _ = c.read_response()
+    assert st == 200, head
+    c.send("DESCRIBE", "Accept: application/sdp\r\n")
+    st, head, body = c.read_response()
+    assert st == 200, head
+    c.send("SETUP", "Transport: RTP/AVP/TCP;unicast;interleaved=0-1\r\n")
+    st, head, _ = c.read_response()
+    assert st == 200, head
+    c.send("PLAY")
+    st, head, _ = c.read_response()
+    assert st == 200, head
+    return body
+
+
+for case in cases:
+    try:
+        if case == "play":
+            c = Client()
+            sdp = setup_play(c)
+            frames, packets, gaps, sizes = c.read_frames(10)
+            c.send("TEARDOWN")
+            c.read_response()
+            c.close()
+            ok = frames >= 50 and gaps == 0
+            say(
+                case,
+                ok,
+                f"{frames} frames in 10 s ({frames / 10:.1f} fps), {packets} RTP packets, {gaps} seq gaps, frame size min {min(sizes) if sizes else 0} max {max(sizes) if sizes else 0}; sdp has m=video {'m=video' in sdp.decode()}",
+            )
+        elif case == "udp":
+            c = Client()
+            c.send("OPTIONS")
+            c.read_response()
+            c.send("SETUP", "Transport: RTP/AVP;unicast;client_port=5000-5001\r\n")
+            st, head, _ = c.read_response()
+            c.close()
+            say(case, st == 461, f"UDP SETUP answered {st}")
+        elif case == "pipeline":
+            c = Client()
+            c.s.sendall(
+                f"OPTIONS rtsp://{HOST}/ RTSP/1.0\r\nCSeq: 1\r\n\r\nDESCRIBE rtsp://{HOST}/ RTSP/1.0\r\nCSeq: 2\r\nAccept: application/sdp\r\n\r\n".encode()
+            )
+            c.cseq = 2
+            st1, h1, _ = c.read_response()
+            st2, h2, b2 = c.read_response()
+            c.close()
+            cs = [x for x in (h1 + h2).split("\r\n") if x.startswith("CSeq")]
+            say(
+                case,
+                st1 == 200 and st2 == 200 and cs == ["CSeq: 1", "CSeq: 2"],
+                f"two pipelined requests answered {st1}, {st2} with {cs}",
+            )
+        elif case == "badreq":
+            c = Client()
+            c.s.sendall(b"BOGUS rtsp://x/ RTSP/1.0\r\nCSeq: 7\r\n\r\n")
+            st, head, _ = c.read_response()
+            c.close()
+            say(
+                case,
+                st in (400, 405, 501) and "CSeq: 7" in head,
+                f"unknown method answered {st}, CSeq echoed {'CSeq: 7' in head}",
+            )
+        elif case == "replay":
+            c = Client()
+            setup_play(c)
+            f1, _, _, _ = c.read_frames(3)
+            c.send("PLAY")
+            st, head, _ = c.read_response()
+            f2, _, gaps, _ = c.read_frames(3)
+            c.send("TEARDOWN")
+            c.read_response()
+            c.close()
+            say(
+                case,
+                st == 200 and f2 >= 10 and gaps == 0,
+                f"second PLAY answered {st}, {f1} then {f2} frames, {gaps} seq gaps after repeat PLAY",
+            )
+        elif case == "getparam":
+            c = Client()
+            setup_play(c)
+            c.read_frames(1)
+            c.send("GET_PARAMETER")
+            st, head, _ = c.read_response()
+            f, _, _, _ = c.read_frames(2)
+            c.send("TEARDOWN")
+            c.read_response()
+            c.close()
+            say(
+                case,
+                st == 200 and f > 5,
+                f"GET_PARAMETER while playing answered {st}, stream continued with {f} frames in 2 s",
+            )
+        elif case == "teardown":
+            c = Client()
+            setup_play(c)
+            c.read_frames(2)
+            c.send("TEARDOWN")
+            st, head, _ = c.read_response()
+            c.s.settimeout(3)
+            time.sleep(1.5)
+            try:
+                rest = c.s.recv(65536)
+                closed = rest == b""
+            except TimeoutError:
+                rest = b"x"
+                closed = False
+            except ConnectionError:
+                closed = True
+            c.close()
+            say(
+                case,
+                st == 200,
+                f"TEARDOWN answered {st}; connection closed by server afterwards: {closed}",
+            )
+        elif case == "third":
+            a = Client()
+            setup_play(a)
+            b = Client()
+            setup_play(b)
+            fa, _, ga, _ = a.read_frames(4)
+            fb, _, gb, _ = b.read_frames(4)
+            try:
+                d = Client(timeout=3)
+                d.send("OPTIONS")
+                st, _, _ = d.read_response()
+                third = f"third got {st}"
+                d.close()
+            except ConnectionError as e:
+                # refused, reset or closed by the server; a timeout or a bug propagates and fails the case
+                third = f"third rejected ({type(e).__name__})"
+            a.send("TEARDOWN")
+            a.read_response()
+            a.close()
+            b.send("TEARDOWN")
+            b.read_response()
+            b.close()
+            say(
+                case,
+                fa > 10 and fb > 10 and ga == 0 and gb == 0 and "rejected" in third,
+                f"two clients: {fa} and {fb} frames in 4 s each, gaps {ga}/{gb}; {third}",
+            )
+        elif case == "stall":
+            a = Client()
+            setup_play(a)
+            b = Client()
+            setup_play(b)
+            # stop reading on a for 4 s while b keeps playing
+            a.s.settimeout(None)
+            fb1, _, gb1, _ = b.read_frames(4)
+            a.s.settimeout(1.0)
+            fa, _, ga, _ = a.read_frames(4)
+            fb2, _, gb2, _ = b.read_frames(3)
+            a.send("TEARDOWN")
+            a.read_response()
+            a.close()
+            b.send("TEARDOWN")
+            b.read_response()
+            b.close()
+            say(
+                case,
+                fb1 > 10 and fb2 > 10 and fa > 5,
+                f"b kept {fb1} then {fb2} frames while a stalled 4 s; a recovered {fa} frames after resuming (gaps {ga}); b gaps {gb1}/{gb2}; device log must show stalled/dropping frame",
+            )
+        elif case == "timeout":
+            c = Client(timeout=70)
+            setup_play(c)
+            c.s.settimeout(
+                2
+            )  # a server that stops sending but never closes must not hang the run
+            t0 = time.monotonic()
+            dead = False
+            try:
+                while time.monotonic() - t0 < 68:
+                    try:
+                        d = c.s.recv(65536)
+                    except TimeoutError:
+                        continue
+                    if not d:
+                        dead = True
+                        break
+            except ConnectionError:
+                dead = True
+            elapsed = time.monotonic() - t0
+            say(
+                case,
+                dead and 50 <= elapsed <= 68,
+                f"connection closed by server after idle: {dead} at {elapsed:.0f} s (expect the 60 s session timeout when the client sends nothing)",
+            )
+    except Exception as e:  # noqa: BLE001
+        say(case, False, f"exception {type(e).__name__}: {e}")
+    time.sleep(1)
+
+print(
+    "SUMMARY",
+    sum(1 for r in results if r[1]),
+    "pass",
+    sum(1 for r in results if not r[1]),
+    "fail",
+)
+sys.exit(1 if any(not r[1] for r in results) else 0)

.agents/skills/hardware-test/scripts/serial_capture.py

@@ -1,6 +1,6 @@
 """Bounded, timestamped serial capture that always exits and closes the port.
 
-  serial_capture.py PORT SECONDS OUTFILE [--baud 115200] [--released] [--reset] [--append]
+  serial_capture.py PORT SECONDS OUTFILE [--baud 115200] [--released] [--reset] [--append] [--ms]
 
   default      open with DTR/RTS as pyserial leaves them (asserted); fine for ESP devkits and the Pico.
   --released   drive DTR and RTS low before opening: the BW15 and BK7238 CH340 kits strap the boot pin
@@ -76,14 +76,21 @@ def open_port(args: argparse.Namespace, path: str) -> serial.Serial:
     return s
 
 
-def write_line(out, tag: bytes, data: bytes) -> None:
-    stamp = time.strftime("[%H:%M:%S]").encode()
+def write_line(out, tag: bytes, data: bytes, ms: bool = False) -> None:
+    if ms:
+        now = time.time()
+        stamp = (
+            time.strftime("[%H:%M:%S", time.localtime(now))
+            + f".{int(now * 1000) % 1000:03d}]"
+        ).encode()
+    else:
+        stamp = time.strftime("[%H:%M:%S]").encode()
     out.write(stamp + tag + ANSI.sub(b"", SECRET.sub(b"<secret>", data)) + b"\n")
     out.flush()
 
 
-def note(out, text: str) -> None:
-    write_line(out, b"[capture] ", text.encode())
+def note(out, text: str, ms: bool = False) -> None:
+    write_line(out, b"[capture] ", text.encode(), ms)
 
 
 def capture(args: argparse.Namespace, out) -> int:
@@ -102,18 +109,18 @@ def capture(args: argparse.Namespace, out) -> int:
                 if serial_number is None:
                     serial_number, index = identify(path)
                 if path != args.port:
-                    note(out, f"reopened as {path}")
+                    note(out, f"reopened as {path}", args.ms)
             except PORT_ERRORS as err:
-                note(out, f"open failed: {err}")
+                note(out, f"open failed: {err}", args.ms)
                 time.sleep(1)
                 continue
         try:
             data = s.read(4096)
         except PORT_ERRORS as err:
             if buf:  # keep the cut-off line apart from the next boot's first line
-                write_line(out, b"[partial]", buf)
+                write_line(out, b"[partial]", buf, args.ms)
                 buf = b""
-            note(out, f"port lost: {err}")
+            note(out, f"port lost: {err}", args.ms)
             with contextlib.suppress(*PORT_ERRORS):
                 s.close()
             s = None
@@ -125,9 +132,9 @@ def capture(args: argparse.Namespace, out) -> int:
         buf += data
         while b"\n" in buf:
             line, buf = buf.split(b"\n", 1)
-            write_line(out, b"", line.rstrip(b"\r"))
+            write_line(out, b"", line.rstrip(b"\r"), args.ms)
     if buf:
-        write_line(out, b"[partial]", buf)
+        write_line(out, b"[partial]", buf, args.ms)
     if s is not None:
         s.close()
     return received
@@ -144,6 +151,7 @@ def main() -> int:
     ap.add_argument("--released", action="store_true")
     ap.add_argument("--reset", action="store_true")
     ap.add_argument("--append", action="store_true")
+    ap.add_argument("--ms", action="store_true", help="millisecond timestamps")
     args = ap.parse_args()
     with pathlib.Path(args.outfile).open("ab" if args.append else "wb") as out:
         received = capture(args, out)

.agents/skills/hardware-test/scripts/usb_audio/playurl.py

@@ -0,0 +1,30 @@
+"""Play a URL on the speaker_source media player over the API (no sync task involved).
+
+usage: playurl.py HOST KEY URL [PLAYER_NAME]
+"""
+
+import asyncio
+import sys
+
+from aioesphomeapi import APIClient, MediaPlayerInfo
+
+HOST, KEY, URL = sys.argv[1], sys.argv[2], sys.argv[3]
+PLAYER = sys.argv[4] if len(sys.argv) > 4 else "Player"
+
+
+async def main() -> None:
+    c = APIClient(HOST, 6053, None, noise_psk=KEY)
+    await c.connect(login=True)
+    ents, _ = await c.list_entities_services()
+    players = {e.name: e for e in ents if isinstance(e, MediaPlayerInfo)}
+    print("media players:", sorted(players))
+    if PLAYER not in players:
+        sys.exit(f"no media player named {PLAYER!r}; have {sorted(players)}")
+    p = players[PLAYER]
+    c.media_player_command(p.key, media_url=URL)
+    print("sent play_media to", PLAYER)
+    await asyncio.sleep(1)
+    await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/usb_cdc_acm/cdc_probe.hpp

@@ -0,0 +1,13 @@
+#pragma once
+#include <zephyr/device.h>
+#include <zephyr/drivers/uart.h>
+#include "esphome/core/log.h"
+
+// Direct look at the Zephyr cdc_acm_uart1 driver state, bypassing the usb_cdc_acm component
+inline void cdc_probe() {
+  const device *d = DEVICE_DT_GET(DT_NODELABEL(cdc_acm_uart1));
+  uint8_t tmp[32];
+  int rr = uart_irq_rx_ready(d);
+  int n = uart_fifo_read(d, tmp, sizeof(tmp));
+  ESP_LOGI("probe", "driver rx_ready=%d fifo_read=%d first=0x%02X", rr, n, n > 0 ? tmp[0] : 0);
+}

.agents/skills/hardware-test/scripts/usb_cdc_acm/drive.py

@@ -0,0 +1,203 @@
+"""Drive the usb_cdc_acm echo firmware on the nRF52840 dongle from the Mac.
+
+usage: drive.py DATA_PORT [case ...]
+Cases: short, bulk1k, bulk16k, bulk64k, burst, flush, peek, linecoding, dtr, stream, counters
+"""
+
+import random
+import sys
+import time
+
+import serial
+
+port = sys.argv[1]
+cases = sys.argv[2:] or [
+    "short",
+    "bulk1k",
+    "bulk16k",
+    "bulk64k",
+    "burst",
+    "flush",
+    "peek",
+    "linecoding",
+    "dtr",
+    "stream",
+    "counters",
+]
+results = []
+
+
+def say(case, ok, detail):
+    results.append((case, ok, detail))
+    print(f"{'PASS' if ok else 'FAIL'} {case}: {detail}", flush=True)
+
+
+def info(case, detail):
+    """A case whose result lives in the device log; printed, not counted."""
+    print(f"INFO {case}: {detail}", flush=True)
+
+
+def open_port(baud=115200):
+    s = serial.Serial(port, baudrate=baud, timeout=1)
+    time.sleep(0.3)  # let the 100 ms line-state poll see DTR and the echo loop settle
+    return s
+
+
+def read_exact(s, n, timeout):
+    buf = bytearray()
+    deadline = time.monotonic() + timeout
+    while len(buf) < n and time.monotonic() < deadline:
+        chunk = s.read(min(4096, n - len(buf)))
+        if chunk:
+            buf += chunk
+    return bytes(buf)
+
+
+def payload(n):
+    # No 0x01 anywhere: the device treats a chunk starting with 0x01 as a command
+    rnd = random.Random(n)
+    return bytes(rnd.choice(range(2, 256)) for _ in range(n))
+
+
+def cmd(s, c, extra=b""):
+    s.write(b"\x01" + c + extra)
+    s.flush()
+
+
+def echo_case(name, n, chunk):
+    s = open_port()
+    s.reset_input_buffer()
+    data = payload(n)
+    t0 = time.monotonic()
+    for i in range(0, n, chunk):
+        s.write(data[i : i + chunk])
+    got = read_exact(s, n, timeout=max(5, n / 2000))
+    dt = time.monotonic() - t0
+    s.close()
+    ok = got == data
+    first_bad = next((i for i in range(min(len(got), n)) if got[i] != data[i]), None)
+    say(
+        name,
+        ok,
+        f"{len(got)}/{n} bytes echoed in {dt:.2f}s ({n / dt / 1024:.1f} KiB/s), first mismatch {first_bad}",
+    )
+
+
+for case in cases:
+    if case == "short":
+        s = open_port()
+        s.reset_input_buffer()
+        ok = True
+        lat = []
+        for i in range(20):
+            msg = f"hello {i}\n".encode()
+            t0 = time.monotonic()
+            s.write(msg)
+            got = read_exact(s, len(msg), 2)
+            lat.append(time.monotonic() - t0)
+            ok = ok and got == msg
+        s.close()
+        say(
+            case,
+            ok,
+            f"20 lines, latency min {min(lat) * 1000:.0f} ms max {max(lat) * 1000:.0f} ms",
+        )
+    elif case == "bulk1k":
+        echo_case(case, 1024, 1024)
+    elif case == "bulk16k":
+        echo_case(case, 16 * 1024, 4096)
+    elif case == "bulk64k":
+        echo_case(case, 64 * 1024, 16384)
+    elif case == "burst":
+        s = open_port()
+        s.reset_input_buffer()
+        cmd(s, b"B")
+        got = read_exact(s, 1000, 3)
+        s.close()
+        expect = bytes((ord("A") + (i % 26)) for i in range(1000))
+        prefix_ok = got == expect[: len(got)]
+        say(
+            case,
+            prefix_ok and 0 < len(got) < 1000,
+            f"{len(got)} of 1000 bytes arrived (256 byte TX ring, rest must be dropped and warned), prefix intact {prefix_ok}",
+        )
+    elif case == "flush":
+        s = open_port()
+        s.reset_input_buffer()
+        cmd(s, b"F")
+        got = read_exact(s, 200, 3)
+        s.close()
+        expect = bytes((ord("a") + (i % 26)) for i in range(200))
+        say(case, got == expect, f"{len(got)}/200 bytes, flush result in device log")
+        time.sleep(0.5)
+    elif case == "peek":
+        s = open_port()
+        s.reset_input_buffer()
+        cmd(s, b"K", b"Z")
+        time.sleep(0.5)
+        s.close()
+        info(
+            case,
+            "peek/read result is in the device log: expect `peek ok=1 0x5A read ok=1 0x5A`",
+        )
+    elif case == "linecoding":
+        for baud in (9600, 115200, 921600):
+            s = open_port(baud)
+            s.reset_input_buffer()
+            cmd(s, b"L")
+            time.sleep(0.4)
+            s.close()
+            time.sleep(0.3)
+        info(case, "opened at 9600, 115200, 921600; the device log must show each baud")
+    elif case == "dtr":
+        for _i in range(5):
+            s = open_port()
+            time.sleep(0.3)
+            s.close()
+            time.sleep(0.3)
+        info(
+            case, "5 open/close cycles; the device log must show 5 Opened and 5 Closed"
+        )
+    elif case == "stream":
+        # device streams 100 x 100 byte lines over 10 s; close the port for 3 s in the middle
+        s = open_port()
+        s.reset_input_buffer()
+        cmd(s, b"S")
+        part1 = bytearray()
+        t0 = time.monotonic()
+        while time.monotonic() - t0 < 2.5:
+            part1 += s.read(4096)
+        s.close()
+        time.sleep(3.0)
+        s = open_port()
+        part2 = bytearray()
+        t0 = time.monotonic()
+        while time.monotonic() - t0 < 6.0:
+            part2 += s.read(4096)
+        s.close()
+        lines1 = [x for x in bytes(part1).split(b"\n") if x.startswith(b"STREAM")]
+        lines2 = [x for x in bytes(part2).split(b"\n") if x.startswith(b"STREAM")]
+        n1 = [int(x[7:10]) for x in lines1]
+        n2 = [int(x[7:10]) for x in lines2]
+        resumed = bool(n2) and max(n2) >= 90
+        say(
+            case,
+            resumed,
+            f"before close: lines {min(n1) if n1 else None}-{max(n1) if n1 else None} ({len(n1)}), after reopen: {min(n2) if n2 else None}-{max(n2) if n2 else None} ({len(n2)}); streaming resumed after reopen {resumed}",
+        )
+    elif case == "counters":
+        s = open_port()
+        cmd(s, b"C")
+        time.sleep(0.3)
+        s.close()
+        info(case, "counters are in the device log")
+    time.sleep(0.5)
+
+print(
+    "SUMMARY",
+    sum(1 for r in results if r[1]),
+    "pass",
+    sum(1 for r in results if not r[1]),
+    "fail",
+)
+sys.exit(1 if any(not r[1] for r in results) else 0)

.agents/skills/hardware-test/scripts/zephyr_coredump/decode.sh

@@ -0,0 +1,39 @@
+#!/bin/zsh
+# usage: decode.sh CAPTURE ELF OUTPREFIX
+# Parses the #CD: lines of a serial capture with Zephyr's coredump tools from the sdk-nrf that ESPHome
+# installed (SDK_NRF, default: the sdk-nrf directory under the ESPHome cache), serves the dump to GDB on a
+# random port and prints the backtrace and the thread list. The ELF is .pioenvs/<name>/zephyr/zephyr/zephyr.elf.
+# Every step is checked: a missing tool, a capture without a complete dump, an empty .bin or a gdbserver
+# that died all stop the script with exit 1, and the exit status is GDB's otherwise.
+CAP=$1; ELF=$2; OUT=$3
+SDK_NRF=${SDK_NRF:-$(ls -d ~/Library/Caches/esphome/sdk-nrf ~/.cache/esphome/sdk-nrf 2>/dev/null | head -1)}
+[ -n "$SDK_NRF" ] || { echo "sdk-nrf not found, set SDK_NRF"; exit 1; }
+F=$(ls -d $SDK_NRF/frameworks/v*/zephyr/scripts/coredump 2>/dev/null | tail -1)
+PY=${PYTHON:-$(ls $SDK_NRF/penvs/*/bin/python 2>/dev/null | head -1)}
+# SDK 0.x keeps the tools under arm-zephyr-eabi/, SDK 1.0+ under gnu/arm-zephyr-eabi/
+GDB=$(ls $SDK_NRF/toolchains/*/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb $SDK_NRF/toolchains/*/gnu/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb 2>/dev/null | tail -1)
+for v in F PY GDB; do
+  [ -n "${(P)v}" ] || { echo "$v not found under $SDK_NRF"; exit 1; }
+done
+[ -f "$ELF" ] || { echo "ELF not found: $ELF"; exit 1; }
+# strip capture timestamps and ANSI so the parser sees the raw log lines
+sed -E 's/^\[[0-9:.]+\]//; s/\x1b\[[0-9;]*m//g' "$CAP" > $OUT-all.log
+# keep only the first complete #CD:BEGIN# .. #CD:END# block
+awk '/#CD:BEGIN#/{if(!done){p=1;buf=""}} p{buf=buf $0 "\n"} /#CD:END#/{if(p){printf "%s", buf; done=1; p=0}}' $OUT-all.log > $OUT-raw.log
+echo "CD lines in capture: $(grep -c '#CD:' $OUT-all.log) (BEGIN $(grep -c '#CD:BEGIN#' $OUT-all.log), END $(grep -c '#CD:END#' $OUT-all.log)); first complete block: $(grep -c '#CD:' $OUT-raw.log) lines"
+[ -s $OUT-raw.log ] || { echo "no complete #CD:BEGIN# .. #CD:END# block in the capture"; exit 1; }
+if ! $PY $F/coredump_serial_log_parser.py $OUT-raw.log $OUT.bin > $OUT-parser.log 2>&1; then
+  echo "parser failed:"; tail -5 $OUT-parser.log; exit 1
+fi
+tail -3 $OUT-parser.log
+[ -s $OUT.bin ] || { echo "parser wrote an empty $OUT.bin"; exit 1; }
+ls -la $OUT.bin | awk '{print "bin bytes", $5}'
+PORT=$((20000 + RANDOM % 10000))
+$PY $F/coredump_gdbserver.py --port $PORT "$ELF" $OUT.bin > $OUT-gdbserver.log 2>&1 &
+G=$!
+sleep 3
+if ! kill -0 $G 2>/dev/null; then echo "gdbserver exited:"; tail -5 $OUT-gdbserver.log; exit 1; fi
+$GDB -q -batch -ex "target remote :$PORT" -ex "bt" -ex "info threads" "$ELF" 2>&1 | grep -v "^warning\|Reading symbols\|^$" | head -40
+rc=$pipestatus[1]
+kill $G 2>/dev/null
+exit $rc

.agents/skills/hardware-test/scripts/zephyr_coredump/flow.sh

@@ -0,0 +1,29 @@
+#!/bin/zsh
+# usage: flow.sh LABEL PORT ELF [OUTDIR]
+# Run at least 60 s after the board rebooted from its crash, with the port closed. Proves the stored
+# coredump waits for a reader and survives a reader that goes away:
+# 1) open the port for 3 s and close it (a reader that leaves mid-print)
+# 2) open it for 100 s: the whole dump must print again, then be erased
+# 3) open it again for 20 s: dump_config must report no stored dump
+# then decode.sh parses the first complete dump and prints the GDB backtrace.
+# Needs a python with pyserial (PYTHON, default python3).
+D=${0:A:h}
+L=$1; P=$2; ELF=$3; S=${4:-.}
+PY=${PYTHON:-python3}
+CAP=$D/../serial_capture.py
+capture() {  # SECONDS OUTFILE: stop the flow when the capture fails (busy or missing port)
+  if ! $PY $CAP $P $1 $2 > $2.err 2>&1; then
+    echo "capture of $2 failed:"; cat $2.err; exit 1
+  fi
+}
+capture 3 $S/$L-brief.txt
+echo "$L brief 3 s open: $(wc -l < $S/$L-brief.txt) lines, CD lines $(grep -a -c '#CD:' $S/$L-brief.txt), END $(grep -a -c '#CD:END#' $S/$L-brief.txt)"
+sleep 5
+capture 100 $S/$L-full.txt
+echo "$L full 100 s open: $(wc -l < $S/$L-full.txt) lines, CD lines $(grep -a -c '#CD:' $S/$L-full.txt), BEGIN $(grep -a -c '#CD:BEGIN#' $S/$L-full.txt), END $(grep -a -c '#CD:END#' $S/$L-full.txt)"
+grep -a "crashtest\|zephyr_coredump\|Reset reason\|Has stored\|  Size:\|  Error:\|took a long\|compiled on" $S/$L-full.txt | grep -a -v "#CD:[0-9A-F]" | head -16
+sleep 3
+capture 20 $S/$L-after.txt
+echo "$L reopen 20 s: CD lines $(grep -a -c '#CD:' $S/$L-after.txt); $(grep -a 'Has stored\|  Size:' $S/$L-after.txt | sed -E 's/^\[[^]]*\]//' | tr '\n' ' ')"
+echo "== decode"
+$D/decode.sh $S/$L-full.txt $ELF $S/$L

.agents/skills/hardware-test/scripts/zwave_proxy/devinfo.py

@@ -0,0 +1,24 @@
+import asyncio
+import sys
+
+from aioesphomeapi import APIClient
+
+
+async def main():
+    c = APIClient(sys.argv[1], 6053, None)
+    await c.connect(login=True)
+    di = await c.device_info()
+    print(
+        "version",
+        di.esphome_version,
+        "compiled",
+        di.compilation_time,
+        "home_id",
+        hex(di.zwave_home_id),
+        "flags",
+        di.zwave_proxy_feature_flags,
+    )
+    await c.disconnect()
+
+
+asyncio.run(main())

.agents/skills/hardware-test/scripts/zwave_proxy/verify_checksums.py

@@ -0,0 +1,45 @@
+"""Recompute the Z-Wave checksum (XOR of LENGTH..payload, initial 0xFF) over every frame the proxy logged."""
+
+from functools import reduce
+import pathlib
+import re
+import sys
+
+
+def zw_checksum(frame: bytes) -> int:
+    return reduce(lambda a, b: a ^ b, frame[1:-1], 0xFF)
+
+
+def complete(frame: bytes) -> bool:
+    """A data frame is SOF, LENGTH, then LENGTH bytes; the proxy logs at most 168 bytes, so longer ones are cut."""
+    return len(frame) >= 3 and frame[0] == 0x01 and len(frame) == frame[1] + 2
+
+
+for path in sys.argv[1:]:
+    text = pathlib.Path(path).read_text(encoding="utf-8", errors="replace")
+    sent = re.findall(r"Sending: ((?:[0-9A-F]{2}:)+[0-9A-F]{2})", text)
+    recv = re.findall(r"Received frame: ((?:[0-9A-F]{2}:)+[0-9A-F]{2})", text)
+    calc = re.findall(
+        r"CHECKSUM Received: 0x([0-9A-F]{2}) - Calculated: 0x([0-9A-F]{2})", text
+    )
+    bad = len(re.findall(r"Bad checksum", text))
+    acks_sent = len(re.findall(r"Sending ACK", text))
+    naks_sent = len(re.findall(r"Sending NAK/CAN", text))
+    acks_recv = len(re.findall(r"Received ACK", text))
+    naks_recv = len(re.findall(r"Received NAK", text))
+    reboots = len(re.findall(r"Boot count|Reset reason|rst:0x", text))
+    long_ops = len(re.findall(r"zwave_proxy took a long time", text))
+    rx_frames = [bytes.fromhex(f.replace(":", "")) for f in recv]
+    tx_frames = [bytes.fromhex(f.replace(":", "")) for f in sent]
+    rx_cut = sum(1 for b in rx_frames if not complete(b))
+    tx_cut = sum(1 for b in tx_frames if len(b) > 1 and not complete(b))
+    rx_ok = sum(1 for b in rx_frames if complete(b) and zw_checksum(b) == b[-1])
+    tx_ok = sum(1 for b in tx_frames if complete(b) and zw_checksum(b) == b[-1])
+    calc_ok = sum(1 for r, c in calc if r == c)
+    cmds = sorted({f.split(":")[3] for f in recv})
+    print(
+        f"{path.rsplit('/', 1)[-1]}: tx frames {len(sent)} (checksum ok {tx_ok}, truncated in log {tx_cut}), "
+        f"rx frames {len(recv)} (recomputed ok {rx_ok}, truncated in log {rx_cut}), "
+        f"device calc==received {calc_ok}/{len(calc)}, bad checksum warnings {bad}, ACK sent {acks_sent}, NAK sent {naks_sent}, "
+        f"ACK received {acks_recv}, NAK received {naks_recv}, long ops {long_ops}, rx cmd ids {cmds}"
+    )

.agents/skills/hardware-test/templates/aux-2-preprod-stock-dut.yaml

@@ -0,0 +1,23 @@
+# Needs packages/aux-2-pre-prod.yaml from NabuCasa/aux-2 at commit 283f2e64 next to this file, with its local
+# external_components source pointed at github://NabuCasa/aux-2@main (see reference/recipes/usb_audio.md).
+# Nabu Casa Connect AUX-2 on the usb_audio PR tree: stock package (I2S PCM5122 output) as a control.
+packages:
+  core: !include aux-2-pre-prod.yaml
+
+esphome:
+  name: aux-2-dut
+  name_add_mac_suffix: false
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+api:
+  encryption:
+    key: !secret api_key
+
+logger:
+  level: DEBUG
+
+sendspin:
+  unpaired_access: true

.agents/skills/hardware-test/templates/aux-2-preprod-usb-audio-dut.yaml

@@ -0,0 +1,39 @@
+# Needs packages/aux-2-pre-prod.yaml from NabuCasa/aux-2 at commit 283f2e64 next to this file, with its local
+# external_components source pointed at github://NabuCasa/aux-2@main (see reference/recipes/usb_audio.md).
+# Nabu Casa Connect AUX-2 on the usb_audio PR tree: the Anker S330 on the USB host port as the mixer output.
+packages:
+  core: !include aux-2-pre-prod.yaml
+
+esphome:
+  name: aux-2-usb-dut
+  name_add_mac_suffix: false
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+api:
+  encryption:
+    key: !secret api_key
+
+logger:
+  level: DEBUG
+  baud_rate: 0
+
+sendspin:
+  unpaired_access: true
+
+usb_audio:
+  id: usb_audio_id
+
+speaker:
+  - platform: usb_audio
+    id: usb_speaker
+    usb_audio_id: usb_audio_id
+    sample_rate: 48000
+    bits_per_sample: 24bit
+    num_channels: 2
+    buffer_size: 28800
+    write_timeout: 50ms
+  - id: !extend mixing_speaker
+    output_speaker: usb_speaker

.agents/skills/hardware-test/templates/bk72xx-crash-probe-dut.yaml

@@ -0,0 +1,44 @@
+substitutions:
+  run: "1"
+
+esphome:
+  name: bk72xx-crash-probe
+  includes: [../scripts/libretiny_crash/bkprobe.hpp]
+  # step 0 waits 30 s so a capture can be opened (and a reset pulsed) after the flash; later steps 5 s
+  on_boot:
+    priority: -100
+    then:
+      - lambda: id(step) = bkprobe_boot(${run});
+      - delay: !lambda 'return id(step) == 0 ? 30000 : 5000;'
+      - lambda: bkprobe_act(${run}, id(step));
+
+bk72xx:
+  board: generic-bk7238-tuya
+
+logger:
+  hardware_uart: UART1
+  level: DEBUG
+
+preferences:
+  flash_write_interval: 1s
+
+globals:
+  - id: step
+    type: int
+    initial_value: "0"
+
+interval:
+  - interval: 10s
+    then:
+      - lambda: bkprobe_alive(id(step));
+
+# Wi-Fi matters: a crashed BK72xx with Wi-Fi up never reboots on its own without the crash handler fix
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+api:
+  reboot_timeout: 0s
+
+ota:
+  - platform: esphome

.agents/skills/hardware-test/templates/bk72xx-rtc-prefs-dut.yaml

@@ -0,0 +1,38 @@
+substitutions:
+  run: "1"
+
+esphome:
+  name: lt21007e
+  includes: [../scripts/libretiny_prefs/ltprefs.hpp]
+  platformio_options:
+    build_flags: ["-DUSE_LIBRETINY_RTC_PREFERENCES"]
+  on_boot:
+    priority: -100
+    then:
+      - lambda: id(act) = ltprefs_boot(id(step), ${run});
+      # the first boot waits so the host can open the port and pulse a reset before the sequence starts
+      - delay: !lambda 'return (id(step) == 0 || id(step) == 8) ? 30000 : 3000;'
+      - lambda: ltprefs_exit(id(step), ${run}, id(act));
+
+bk72xx:
+  board: generic-bk7238-tuya
+
+logger:
+  hardware_uart: UART1
+  level: DEBUG
+
+preferences:
+  flash_write_interval: 1s
+
+globals:
+  - id: step
+    type: int
+    initial_value: "0"
+  - id: act
+    type: int
+    initial_value: "0"
+
+interval:
+  - interval: 10s
+    then:
+      - lambda: ltprefs_alive(id(step), id(act));

.agents/skills/hardware-test/templates/cast-pro-1-sendspin-control.yaml

@@ -0,0 +1,27 @@
+# CAST PRO-1 control for the sendspin sync comparison: Apollo's current package, DEBUG logging as on the S3.
+esphome:
+  name: "cast-pro-1-dut"
+  friendly_name: CAST PRO-1 test
+  project:
+    name: "ApolloAutomation.CAST_PRO-1"
+    version: ${version}
+
+packages:
+  core: !include Core.yaml
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  enable_on_boot: false
+
+logger:
+  level: DEBUG
+
+api:
+  encryption:
+    key: !secret api_key
+
+sendspin:
+  manufacturer: Apollo
+  model: CAST PRO-1 control
+  unpaired_access: true

.agents/skills/hardware-test/templates/deep-sleep-outgoing-dut.yaml

@@ -0,0 +1,46 @@
+# Deep sleep wake timing for the outgoing API connection: boot -> dial -> client hello -> first HA state.
+esphome:
+  name: deep-sleep-dut
+  on_boot:
+    priority: -100
+    then:
+      - lambda: ESP_LOGI("timing", "setup done at %u ms", (unsigned) millis());
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+logger:
+  level: DEBUG
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  fast_connect: true
+  on_connect:
+    - lambda: ESP_LOGI("timing", "wifi connected at %u ms", (unsigned) millis());
+
+api:
+  encryption:
+    key: !secret api_key
+  outgoing_connection:
+  on_client_connected:
+    - lambda: ESP_LOGI("timing", "client connected at %u ms (%s %s)", (unsigned) millis(), client_info.c_str(), client_address.c_str());
+  on_client_disconnected:
+    - lambda: ESP_LOGI("timing", "client disconnected at %u ms", (unsigned) millis());
+
+ota:
+  - platform: esphome
+
+text_sensor:
+  - platform: homeassistant
+    id: ha_state
+    entity_id: light.ENTITY
+    on_value:
+      - lambda: ESP_LOGI("timing", "first HA state '%s' at %u ms", x.c_str(), (unsigned) millis());
+
+deep_sleep:
+  id: ds
+  run_duration: 15s
+  sleep_duration: 15s

.agents/skills/hardware-test/templates/dfrobot-sen0395-dut.yaml

@@ -0,0 +1,186 @@
+# DFRobot SEN0395 on an ESP32 DevKit V1: V to VIN (5 V), G to GND, sensor TX to GPIO16 (RX2), sensor RX to GPIO17 (TX2),
+# IO2 to GPIO18, I1 unconnected. Settings buttons, the four switches and junk-line buttons whose echo and
+# "is not recognized" reply come back as lines of known length (220 and 240 bytes give replies over 252 chars).
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+logger:
+  level: VERBOSE
+  logs:
+    api: DEBUG
+    api.connection: DEBUG
+    api.service: DEBUG
+    wifi: DEBUG
+    mdns: DEBUG
+    scheduler: DEBUG
+    component: DEBUG
+    esp32: DEBUG
+    uart: DEBUG
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+api:
+  encryption:
+    key: !secret api_key
+  reboot_timeout: 0s
+
+ota:
+  - platform: esphome
+
+uart:
+  id: mmwave_uart
+  tx_pin: GPIO17
+  rx_pin: GPIO16
+  baud_rate: 115200
+
+dfrobot_sen0395:
+  id: mmwave
+  uart_id: mmwave_uart
+
+binary_sensor:
+  - platform: dfrobot_sen0395
+    dfrobot_sen0395_id: mmwave
+    name: Detected via UART
+    id: uart_detected
+  - platform: gpio
+    name: Detected via GPIO
+    device_class: motion
+    pin:
+      number: GPIO18
+      mode: INPUT_PULLDOWN
+
+switch:
+  - platform: dfrobot_sen0395
+    dfrobot_sen0395_id: mmwave
+    type: sensor_active
+    name: Sensor active
+  - platform: dfrobot_sen0395
+    dfrobot_sen0395_id: mmwave
+    type: presence_via_uart
+    name: Presence via UART
+  - platform: dfrobot_sen0395
+    dfrobot_sen0395_id: mmwave
+    type: turn_on_led
+    name: LED
+  - platform: dfrobot_sen0395
+    dfrobot_sen0395_id: mmwave
+    type: start_after_boot
+    name: Start after boot
+
+button:
+  - platform: template
+    name: Range 0 to 3m
+    on_press:
+      - dfrobot_sen0395.settings:
+          id: mmwave
+          detection_segments:
+            - [0cm, 3m]
+  - platform: template
+    name: Range 0 to 9m
+    on_press:
+      - dfrobot_sen0395.settings:
+          id: mmwave
+          detection_segments:
+            - [0cm, 9m]
+  - platform: template
+    name: Latency 1s 2s
+    on_press:
+      - dfrobot_sen0395.settings:
+          id: mmwave
+          output_latency:
+            delay_after_detect: 1s
+            delay_after_disappear: 2s
+  - platform: template
+    name: Latency 0 0
+    on_press:
+      - dfrobot_sen0395.settings:
+          id: mmwave
+          output_latency:
+            delay_after_detect: 0s
+            delay_after_disappear: 0s
+  - platform: template
+    name: Sensitivity 7
+    on_press:
+      - dfrobot_sen0395.settings:
+          id: mmwave
+          sensitivity: 7
+  - platform: template
+    name: Factory reset
+    on_press:
+      - dfrobot_sen0395.settings:
+          id: mmwave
+          factory_reset: true
+  - platform: template
+    name: Reset
+    on_press:
+      - dfrobot_sen0395.reset:
+          id: mmwave
+  - platform: template
+    name: Junk 100
+    on_press:
+      - uart.write:
+          id: mmwave_uart
+          data: !lambda |-
+            std::vector<uint8_t> v(100, 'x');
+            v.push_back('\r');
+            v.push_back('\n');
+            return v;
+  - platform: template
+    name: Junk 160
+    on_press:
+      - uart.write:
+          id: mmwave_uart
+          data: !lambda |-
+            std::vector<uint8_t> v(160, 'x');
+            v.push_back('\r');
+            v.push_back('\n');
+            return v;
+  - platform: template
+    name: Junk 200
+    on_press:
+      - uart.write:
+          id: mmwave_uart
+          data: !lambda |-
+            std::vector<uint8_t> v(200, 'x');
+            v.push_back('\r');
+            v.push_back('\n');
+            return v;
+  - platform: template
+    name: Junk 220
+    on_press:
+      - uart.write:
+          id: mmwave_uart
+          data: !lambda |-
+            std::vector<uint8_t> v(220, 'x');
+            v.push_back('\r');
+            v.push_back('\n');
+            return v;
+  - platform: template
+    name: Junk 240
+    on_press:
+      - uart.write:
+          id: mmwave_uart
+          data: !lambda |-
+            std::vector<uint8_t> v(240, 'x');
+            v.push_back('\r');
+            v.push_back('\n');
+            return v;
+  - platform: template
+    name: Junk 256
+    on_press:
+      - uart.write:
+          id: mmwave_uart
+          data: !lambda |-
+            std::vector<uint8_t> v(256, 'x');
+            v.push_back('\r');
+            v.push_back('\n');
+            return v;
+
+interval:
+  - interval: 30s
+    then:
+      - lambda: 'ESP_LOGI("sen", "alive uart_detected=%d heap=%u", id(uart_detected).state, (unsigned) esp_get_free_heap_size());'

.agents/skills/hardware-test/templates/dut-ap-only-wipe-once-bk72xx.yaml

@@ -0,0 +1,34 @@
+esphome:
+  name: i19430-dut3
+  on_boot:
+    priority: 800
+    then:
+      - lambda: |-
+          auto marker = global_preferences->make_preference<uint32_t>(0x19430001, true);
+          uint32_t v = 0;
+          if (!marker.load(&v)) {
+            ESP_LOGW("test", "first boot: wiping preferences");
+            global_preferences->reset();
+            static_cast<esphome::libretiny::LibreTinyPreferences *>(global_preferences)->open();
+            v = 1;
+            marker.save(&v);
+            global_preferences->sync();
+          }
+
+bk72xx:
+  board: generic-bk7238
+
+logger:
+  hardware_uart: UART1
+  level: VERBOSE
+
+wifi:
+  ap:
+    ssid: i19430-ap
+
+captive_portal:
+
+interval:
+  - interval: 5s
+    then:
+      - lambda: ESP_LOGI("test", "alive %u s", (unsigned) (millis() / 1000));

.agents/skills/hardware-test/templates/globals-storage-dut.yaml

@@ -0,0 +1,66 @@
+# Restoring globals with every storage choice; each boot bumps the counters, logs them with the reset reason, saves
+# and syncs; odd boots soft restart, even boots deep sleep (ESP32) or idle (D1 mini). The host's reset pulse and a
+# power cut give the other reset kinds.
+logger:
+  level: DEBUG
+
+preferences:
+  flash_write_interval: 1s
+
+globals:
+  - id: cnt_rtc
+    type: int
+    restore_value: true
+    storage: rtc
+    initial_value: "0"
+  - id: cnt_flash
+    type: int
+    restore_value: true
+    storage: flash
+    initial_value: "0"
+  - id: cnt_default
+    type: int
+    restore_value: true
+    initial_value: "0"
+  - id: str_rtc
+    type: std::string
+    restore_value: true
+    storage: rtc
+    max_restore_data_length: 24
+    initial_value: '"fresh"'
+  - id: arr_rtc
+    type: uint8_t[2]
+    restore_value: true
+    storage: rtc
+    initial_value: "{0, 0}"
+
+esphome:
+  on_boot:
+    priority: -100
+    then:
+      - lambda: |-
+          id(cnt_rtc) += 1;
+          id(cnt_flash) += 1;
+          id(cnt_default) += 1;
+          id(arr_rtc)[0] += 1;
+          id(arr_rtc)[1] += 2;
+          char buf[24];
+          snprintf(buf, sizeof(buf), "boot%d", id(cnt_rtc));
+          ESP_LOGI("gl", "restored rtc=%d flash=%d default=%d str='%s' arr=%u/%u (values before this boot's bump: one less)",
+                   id(cnt_rtc) - 1, id(cnt_flash) - 1, id(cnt_default) - 1, id(str_rtc).c_str(), id(arr_rtc)[0] - 1, id(arr_rtc)[1] - 2);
+          id(str_rtc) = buf;
+      - delay: 2s
+      - lambda: |-
+          global_preferences->sync();
+          ESP_LOGI("gl", "saved rtc=%d flash=%d default=%d str='%s' arr=%u/%u", id(cnt_rtc), id(cnt_flash), id(cnt_default),
+                   id(str_rtc).c_str(), id(arr_rtc)[0], id(arr_rtc)[1]);
+      - if:
+          condition:
+            lambda: 'return id(cnt_rtc) % 2 == 1;'
+          then:
+            - delay: 3s
+            - lambda: 'ESP_LOGI("gl", "odd boot, soft restart now"); App.safe_reboot();'
+
+button:
+  - platform: restart
+    name: Restart

.agents/skills/hardware-test/templates/homeassistant-light-dut.yaml

@@ -0,0 +1,159 @@
+# shared part: two Home Assistant lights mirrored on the device plus buttons that drive them
+esphome:
+  # A local change made before the light core's first write (b19a776 sends it instead of merging it).
+  on_boot:
+    priority: -100
+    then:
+      - lambda: 'ESP_LOGI("halight", "on_boot turning B on at 35 percent before the first write");'
+      - light.turn_on:
+          id: bulb_b
+          brightness: 35%
+logger:
+  level: VERBOSE
+  logs:
+    api: DEBUG
+    api.connection: DEBUG
+    api.service: DEBUG
+    wifi: DEBUG
+    scheduler: DEBUG
+    component: DEBUG
+    sensor: DEBUG
+    mdns: DEBUG
+    ota: DEBUG
+    socket: DEBUG
+    esp-idf: DEBUG
+    preferences: DEBUG
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+api:
+  encryption:
+    key: !secret api_key
+  reboot_timeout: 0s
+
+ota:
+  - platform: esphome
+
+light:
+  - platform: homeassistant
+    id: bulb_a
+    name: Mirror A
+    entity_id: light.ENTITY_A
+    report_timeout: 5s
+    on_turn_on:
+      - logger.log: "bulb_a on_turn_on"
+    on_turn_off:
+      - logger.log: "bulb_a on_turn_off"
+  - platform: homeassistant
+    id: bulb_b
+    name: Mirror B
+    entity_id: light.ENTITY_B
+    report_timeout: 5s
+
+button:
+  - platform: template
+    name: A warm 40
+    id: a_warm_40
+    on_press:
+      - light.turn_on:
+          id: bulb_a
+          brightness: 40%
+          color_temperature: 370 mireds
+  - platform: template
+    name: A cool 100
+    on_press:
+      - light.turn_on:
+          id: bulb_a
+          brightness: 100%
+          color_temperature: 153 mireds
+  - platform: template
+    name: A red
+    on_press:
+      - light.turn_on:
+          id: bulb_a
+          brightness: 80%
+          red: 100%
+          green: 0%
+          blue: 0%
+  - platform: template
+    name: A green dim
+    on_press:
+      - light.turn_on:
+          id: bulb_a
+          brightness: 20%
+          red: 0%
+          green: 100%
+          blue: 0%
+  - platform: template
+    name: A brightness only 60
+    on_press:
+      - light.turn_on:
+          id: bulb_a
+          brightness: 60%
+  - platform: template
+    name: A transition 100
+    on_press:
+      - light.turn_on:
+          id: bulb_a
+          brightness: 100%
+          transition_length: 3s
+  - platform: template
+    name: A flash
+    on_press:
+      - light.turn_on:
+          id: bulb_a
+          flash_length: 1s
+  - platform: template
+    name: A off
+    on_press:
+      - light.turn_off: bulb_a
+  - platform: template
+    name: A toggle
+    on_press:
+      - light.toggle: bulb_a
+  - platform: template
+    name: B warm 50
+    on_press:
+      - light.turn_on:
+          id: bulb_b
+          brightness: 50%
+          color_temperature: 300 mireds
+  - platform: template
+    name: B off
+    on_press:
+      - light.turn_off: bulb_b
+  - platform: template
+    name: A 50 fade 3s
+    on_press:
+      - light.turn_on:
+          id: bulb_a
+          brightness: 50%
+          transition_length: 3s
+  - platform: template
+    name: A many calls
+    on_press:
+      - lambda: |-
+          for (int i = 0; i < 16; i++) {
+            id(bulb_a).make_call().set_brightness(i == 15 ? 1.0f : 0.6f).set_transition_length(1000).perform();
+          }
+  - platform: template
+    name: Log state
+    on_press:
+      - lambda: |-
+          auto v = id(bulb_a).current_values;
+          ESP_LOGI("halight", "A: on=%d mode=%d bri=%.2f ct=%.1f rgb=%.2f/%.2f/%.2f  B: on=%d bri=%.2f",
+                   v.is_on(), (int) v.get_color_mode(), v.get_brightness(), v.get_color_temperature(),
+                   v.get_red(), v.get_green(), v.get_blue(), id(bulb_b).current_values.is_on(),
+                   id(bulb_b).current_values.get_brightness());
+
+interval:
+  - interval: 30s
+    then:
+      - lambda: |-
+          auto v = id(bulb_a).current_values;
+          ESP_LOGI("halight", "alive A: on=%d mode=%d bri=%.2f ct=%.1f rgb=%.2f/%.2f/%.2f  B: on=%d bri=%.2f",
+                   v.is_on(), (int) v.get_color_mode(), v.get_brightness(), v.get_color_temperature(),
+                   v.get_red(), v.get_green(), v.get_blue(), id(bulb_b).current_values.is_on(),
+                   id(bulb_b).current_values.get_brightness());

.agents/skills/hardware-test/templates/nrf52-coredump-crash-dut.yaml

@@ -0,0 +1,50 @@
+substitutions:
+  run: "3"
+
+esphome:
+  name: cd13122d
+  on_boot:
+    priority: -100
+    then:
+      - lambda: |-
+          ESP_LOGI("crashtest", "boot, crashed_before=%d run=%s", id(crashed_${run}), "${run}");
+      - delay: 20s
+      - if:
+          condition:
+            lambda: 'return id(crashed_${run}) == 0;'
+          then:
+            - lambda: |-
+                id(crashed_${run}) = 1;
+                ESP_LOGW("crashtest", "flag set, letting the loop save it");
+            - delay: 3s
+            - lambda: |-
+                global_preferences->sync();
+                delay(500);
+                ESP_LOGW("crashtest", "writing to 0xDEADBEEF now");
+                delay(100);
+                *reinterpret_cast<volatile uint32_t *>(0xDEADBEEF) = 1;
+          else:
+            - lambda: |-
+                ESP_LOGI("crashtest", "already crashed once, running normally");
+
+nrf52:
+  board: nrf52840dongle
+  dfu: true
+
+logger:
+  hardware_uart: USB_CDC
+  level: DEBUG
+
+zephyr_coredump:
+
+globals:
+  - id: crashed_${run}
+    type: int
+    restore_value: true
+    initial_value: "0"
+
+interval:
+  - interval: 10s
+    then:
+      - lambda: |-
+          ESP_LOGI("crashtest", "alive");

.agents/skills/hardware-test/templates/nrf52-preferences-dut.yaml

@@ -0,0 +1,31 @@
+esphome:
+  name: pref20810
+  on_boot:
+    priority: -100
+    then:
+      - lambda: |-
+          ESP_LOGI("test", "boot: restored counter_pr=%d", id(counter_pr));
+
+nrf52:
+  board: nrf52840dongle
+  dfu: true
+
+logger:
+  hardware_uart: USB_CDC
+  level: VERBOSE
+
+preferences:
+  flash_write_interval: 5s
+
+globals:
+  - id: counter_pr
+    type: int
+    restore_value: true
+    initial_value: "0"
+
+interval:
+  - interval: 15s
+    then:
+      - lambda: |-
+          id(counter_pr) += 1;
+          ESP_LOGI("test", "counter_pr now %d", id(counter_pr));

.agents/skills/hardware-test/templates/online-image-dut.yaml

@@ -0,0 +1,84 @@
+esphome:
+  name: online-image-dut
+  friendly_name: online-image-dut
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+logger:
+  level: DEBUG
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+api:
+  encryption:
+    key: !secret api_key
+  reboot_timeout: 0s
+  actions:
+    - action: fetch
+      variables:
+        url: string
+      then:
+        - online_image.set_url:
+            id: img
+            url: !lambda 'return url;'
+            update: false
+        - component.update: img
+    - action: refetch
+      then:
+        - component.update: img
+    - action: fetch_small
+      variables:
+        url: string
+      then:
+        - online_image.set_url:
+            id: img_small
+            url: !lambda 'return url;'
+            update: false
+        - component.update: img_small
+    - action: refetch_small
+      then:
+        - component.update: img_small
+
+http_request:
+  timeout: 4.5s
+  verify_ssl: false
+
+display:
+
+image:
+  - platform: online_image
+    id: img
+    url: http://127.0.0.1/none.bmp
+    format: AUTO
+    type: RGB565
+    update_interval: never
+    on_download_finished:
+      logger.log:
+        format: "download finished: img cached=%d"
+        args: [cached]
+    on_error:
+      logger.log: "download error: img"
+  - platform: online_image
+    id: img_small
+    url: http://127.0.0.1/none.bmp
+    format: AUTO
+    type: RGB565
+    buffer_size: 256
+    update_interval: never
+    on_download_finished:
+      logger.log:
+        format: "download finished: img_small cached=%d"
+        args: [cached]
+    on_error:
+      logger.log: "download error: img_small"
+
+button:
+  - platform: restart
+    id: reboot_btn
+    name: Reboot

.agents/skills/hardware-test/templates/outgoing-wifi-drop-dut.yaml

@@ -0,0 +1,55 @@
+# Mains build (no deep sleep): outgoing API connection timing after a Wi-Fi drop, and the loop cost while a
+# connect is pending or the network is down.
+esphome:
+  name: wifi-drop-dut
+
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+
+logger:
+  level: DEBUG
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  fast_connect: true
+  on_connect:
+    - lambda: ESP_LOGI("timing", "wifi connected at %u ms", (unsigned) millis());
+  on_disconnect:
+    - lambda: ESP_LOGI("timing", "wifi disconnected at %u ms", (unsigned) millis());
+
+api:
+  encryption:
+    key: !secret api_key
+  reboot_timeout: 0s
+  outgoing_connection:
+    delay: 2s
+  on_client_connected:
+    - lambda: ESP_LOGI("timing", "client connected at %u ms (%s %s)", (unsigned) millis(), client_info.c_str(), client_address.c_str());
+  on_client_disconnected:
+    - lambda: ESP_LOGI("timing", "client disconnected at %u ms (%s)", (unsigned) millis(), client_info.c_str());
+
+ota:
+  - platform: esphome
+
+debug:
+  update_interval: 5s
+
+sensor:
+  - platform: debug
+    loop_time:
+      name: Loop Time
+      on_value:
+        - lambda: ESP_LOGI("timing", "loop time max %.0f ms over the last 5 s at %u ms", x, (unsigned) millis());
+
+button:
+  - platform: template
+    name: Wifi cycle
+    on_press:
+      - lambda: ESP_LOGI("timing", "wifi cycle disabling at %u ms", (unsigned) millis());
+      - wifi.disable:
+      - delay: 4s
+      - lambda: ESP_LOGI("timing", "wifi cycle enabling at %u ms", (unsigned) millis());
+      - wifi.enable:

.agents/skills/hardware-test/templates/rtsp-waveshare-s3-eth-dut.yaml

@@ -0,0 +1,105 @@
+esphome:
+  name: rtsp17990
+  on_boot:
+    # GPIO8 low enables the camera's power supply on the Waveshare ESP32-S3-ETH; give the sensor
+    # time to come up before esp32_camera (setup_priority 200) probes it
+    priority: 700
+    then:
+      - switch.turn_off: cam_power
+      - lambda: |-
+          delay(1200);
+
+esp32:
+  board: esp32-s3-devkitc-1
+  variant: esp32s3
+  flash_size: 16MB
+  framework:
+    type: esp-idf
+
+psram:
+  mode: octal
+  speed: 80MHz
+
+logger:
+  level: VERBOSE
+  hardware_uart: USB_SERIAL_JTAG
+  logs:
+    rtsp_server: VERBOSE
+    esp32_camera: DEBUG
+    camera: DEBUG
+    wifi: DEBUG
+    api: DEBUG
+    api.connection: DEBUG
+    api.socket: DEBUG
+    socket: DEBUG
+    scheduler: DEBUG
+    component: DEBUG
+    app: DEBUG
+    mdns: DEBUG
+    ota: DEBUG
+    logger: DEBUG
+    psram: DEBUG
+    esp32: DEBUG
+    network: DEBUG
+    i2c: DEBUG
+    i2c.idf: DEBUG
+    preferences: DEBUG
+    debug: DEBUG
+    sensor: DEBUG
+    wifi_esp32: DEBUG
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  power_save_mode: none
+
+api:
+  reboot_timeout: 0s
+
+ota:
+  - platform: esphome
+
+debug:
+  update_interval: 10s
+
+sensor:
+  - platform: debug
+    free:
+      name: "Heap Free"
+    block:
+      name: "Heap Largest Block"
+    psram:
+      name: "PSRAM Free"
+
+# Waveshare ESP32-S3-ETH camera header (Waveshare wiki, WIFI_Web_CAM table)
+i2c:
+  - id: cam_i2c
+    sda: GPIO48
+    scl: GPIO47
+    frequency: 400kHz
+
+switch:
+  - platform: gpio
+    id: cam_power
+    name: Camera Power
+    pin: GPIO8
+    restore_mode: ALWAYS_OFF
+    setup_priority: 800
+
+esp32_camera:
+  name: cam
+  setup_priority: 200
+  data_pins: [GPIO41, GPIO45, GPIO46, GPIO42, GPIO40, GPIO38, GPIO15, GPIO18]
+  vsync_pin: GPIO1
+  href_pin: GPIO2
+  pixel_clock_pin: GPIO39
+  external_clock:
+    pin: GPIO3
+    frequency: 20MHz
+  i2c_id: cam_i2c
+  resolution: 640X480
+  max_framerate: 10fps
+
+rtsp_server:
+  port: 554
+  max_connections: 2

.agents/skills/hardware-test/templates/s31-cse7766-dut.yaml

@@ -0,0 +1,107 @@
+# Basic Config
+
+esphome:
+  name: s31-cse7766
+
+esp8266:
+  board: esp01_1m
+  toolchain: arduino
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+logger:
+  baud_rate: 0  # (UART logging interferes with cse7766)
+  level: VERBOSE
+  logs:
+    cse7766: VERBOSE
+    api: DEBUG
+    api.connection: DEBUG
+    api.socket: DEBUG
+    socket: DEBUG
+    scheduler: DEBUG
+    component: DEBUG
+    app: DEBUG
+    wifi: DEBUG
+    mdns: DEBUG
+    ota: DEBUG
+    logger: DEBUG
+    sensor: DEBUG
+    switch: DEBUG
+    binary_sensor: DEBUG
+    status_led: DEBUG
+    uart: DEBUG
+    gpio: DEBUG
+    preferences: DEBUG
+    esp8266: DEBUG
+    wifi_esp8266: DEBUG
+api:
+ota:
+  platform: esphome
+
+# Device Specific Config
+
+uart:
+  rx_pin: RX
+  baud_rate: 4800
+  parity: EVEN
+
+binary_sensor:
+  - platform: gpio
+    pin:
+      number: GPIO0
+      mode: INPUT_PULLUP
+      inverted: True
+    name: "S31 Button"
+    on_press:
+      - switch.toggle: relay
+  - platform: status
+    name: "S31 Status"
+
+sensor:
+  - platform: wifi_signal
+    name: "S31 WiFi Signal"
+    update_interval: 60s
+  - platform: cse7766
+    current:
+      accuracy_decimals: 3
+      name: "S31 Current"
+      filters:
+        - throttle: 2s
+    voltage:
+      accuracy_decimals: 1
+      name: "S31 Voltage"
+      filters:
+        - throttle: 2s
+      on_raw_value:
+        then:
+          - lambda: |-
+              id(frames) += 1;
+    power:
+      accuracy_decimals: 1
+      name: "S31 Power"
+      filters:
+        - throttle: 2s
+switch:
+  - platform: gpio
+    name: "S31 Relay"
+    pin: GPIO12
+    id: relay
+    restore_mode: RESTORE_DEFAULT_ON
+
+status_led:
+  pin: GPIO13
+
+globals:
+  - id: frames
+    type: uint32_t
+    initial_value: "0"
+
+interval:
+  - interval: 10s
+    then:
+      - lambda: |-
+          static uint32_t last = 0;
+          ESP_LOGI("frames", "cse7766 frames parsed: %u in 10 s (total %u)", (unsigned) (id(frames) - last), (unsigned) id(frames));
+          last = id(frames);

.agents/skills/hardware-test/templates/usb-audio-sendspin-s3-eth-dut.yaml

@@ -0,0 +1,76 @@
+# Music Assistant target: the plain USB audio template plus the CAST-1 style sendspin wiring (resampler speakers
+# into a mixer whose inputs never time out, speaker_source media player, sendspin hub and sources).
+packages:
+  base: !include usb-audio-waveshare-s3-eth-dut.yaml
+
+# Logs over the API only: a DEBUG line per report would saturate UART0 and trip the task watchdog.
+logger:
+  baud_rate: 0
+
+speaker:
+  - id: !extend usb_speaker
+    buffer_size: 28800
+    write_timeout: 50ms
+  - platform: mixer
+    id: mixer_speaker_id
+    output_speaker: usb_speaker
+    num_channels: 2
+    task_stack_in_psram: true
+    source_speakers:
+      - id: announcement_mixer_input
+        timeout: never
+      - id: media_mixer_input
+        timeout: never
+  - platform: resampler
+    id: announcement_resampling_speaker
+    output_speaker: announcement_mixer_input
+    sample_rate: 48000
+    bits_per_sample: 16
+  - platform: resampler
+    id: media_resampling_speaker
+    output_speaker: media_mixer_input
+    sample_rate: 48000
+    bits_per_sample: 16
+
+sendspin:
+  id: sendspin_hub
+  # PSRAM stack skews time sync; keep internal
+  task_stack_in_psram: false
+  manufacturer: Waveshare
+  model: ESP32-S3-ETH USB audio
+  firmware_version: "0.1"
+  unpaired_access: true
+
+media_source:
+  - platform: sendspin
+    id: sendspin_source
+  - platform: audio_http
+    id: http_media_source
+    buffer_size: 500000
+  - platform: audio_http
+    id: http_announcement_source
+    buffer_size: 250000
+
+media_player:
+  - platform: sendspin
+    id: sendspin_group_media_player
+    name: Sendspin Player
+  - platform: speaker_source
+    id: external_media_player
+    name: Player
+    volume_increment: 0.05
+    announcement_pipeline:
+      format: FLAC
+      num_channels: 1
+      sample_rate: 48000
+      speaker: announcement_resampling_speaker
+      sources:
+        - http_announcement_source
+    media_pipeline:
+      speaker: media_resampling_speaker
+      format: FLAC
+      num_channels: 2
+      sample_rate: 48000
+      sources:
+        - sendspin_source
+        - http_media_source

.agents/skills/hardware-test/templates/usb-audio-waveshare-s3-eth-dut.yaml

@@ -0,0 +1,142 @@
+# Waveshare ESP32-S3-ETH: USB host for a speakerphone (usb_audio), logs over Ethernet, the USB port is the host port
+esphome:
+  name: usb-audio-dut
+
+esp32:
+  board: esp32-s3-devkitc-1
+  variant: esp32s3
+  flash_size: 16MB
+  framework:
+    type: esp-idf
+
+psram:
+  mode: octal
+  speed: 80MHz
+
+logger:
+  level: DEBUG
+  hardware_uart: UART0
+  logs:
+    usb_host: DEBUG
+
+ethernet:
+  type: W5500
+  clk_pin: GPIO13
+  mosi_pin: GPIO11
+  miso_pin: GPIO12
+  cs_pin: GPIO14
+  interrupt_pin: GPIO10
+  reset_pin: GPIO9
+
+api:
+  encryption:
+    key: !secret api_key
+  reboot_timeout: 0s
+
+ota:
+  - platform: esphome
+
+usb_audio:
+  id: usb_audio_id
+
+microphone:
+  - platform: usb_audio
+    id: usb_mic
+    usb_audio_id: usb_audio_id
+    sample_rate: 48000
+    bits_per_sample: 16bit
+    num_channels: 2
+    buffer_size: 9600
+    on_data:
+      - lambda: |-
+          id(mic_bytes) += x.size();
+          id(mic_chunks) += 1;
+
+speaker:
+  - platform: usb_audio
+    id: usb_speaker
+    usb_audio_id: usb_audio_id
+    sample_rate: 48000
+    bits_per_sample: 24bit
+    num_channels: 2
+    buffer_size: 9600
+    write_timeout: 20ms
+
+globals:
+  - id: beep_left
+    type: int
+    initial_value: "0"
+  - id: beep_written
+    type: uint32_t
+    initial_value: "0"
+  - id: beep_short
+    type: uint32_t
+    initial_value: "0"
+  - id: beep_phase
+    type: float
+    initial_value: "0"
+  - id: mic_bytes
+    type: uint32_t
+    initial_value: "0"
+  - id: mic_chunks
+    type: uint32_t
+    initial_value: "0"
+
+button:
+  - platform: template
+    name: Mic start
+    on_press:
+      - microphone.capture: usb_mic
+  - platform: template
+    name: Mic stop
+    on_press:
+      - microphone.stop_capture: usb_mic
+  - platform: template
+    name: Beep
+    on_press:
+      - lambda: |-
+          // 2 s of a 1 kHz tone at 48 kHz 24-bit stereo, fed 10 ms at a time from the interval below
+          id(beep_left) = 200;
+          id(beep_written) = 0;
+          id(beep_short) = 0;
+          id(beep_phase) = 0.0f;
+          id(usb_speaker).start();
+          ESP_LOGI("uatest", "beep started");
+  - platform: template
+    name: Speaker stop
+    on_press:
+      - speaker.stop: usb_speaker
+  - platform: template
+    name: Restart
+    on_press:
+      - lambda: App.safe_reboot();
+
+interval:
+  - interval: 8ms
+    then:
+      - lambda: |-
+          if (id(beep_left) <= 0) return;
+          // 10 ms of 48 kHz stereo 24-bit samples, 3 bytes little-endian per sample
+          static uint8_t buf[480 * 2 * 3];
+          float phase = id(beep_phase);
+          for (int i = 0; i < 480; i++) {
+            int32_t s = (int32_t) (1500000.0f * sinf(phase));
+            phase += 2.0f * 3.14159265f * 1000.0f / 48000.0f;
+            if (phase > 6.2831853f) phase -= 6.2831853f;
+            for (int c = 0; c < 2; c++) {
+              uint8_t *o = buf + (i * 2 + c) * 3;
+              o[0] = s & 0xFF; o[1] = (s >> 8) & 0xFF; o[2] = (s >> 16) & 0xFF;
+            }
+          }
+          size_t n = id(usb_speaker).play(buf, sizeof(buf), 0);
+          if (n == 0) { id(beep_short) += 1; return; }  // not accepted yet, try the same chunk next time
+          id(beep_phase) = phase;
+          id(beep_written) += n;
+          id(beep_left) -= 1;
+          if (id(beep_left) == 0) ESP_LOGI("uatest", "beep done: %u bytes queued, %u retries", (unsigned) id(beep_written), (unsigned) id(beep_short));
+  - interval: 5s
+    then:
+      - lambda: |-
+          ESP_LOGI("uatest", "mic capturing=%d bytes=%u chunks=%u | speaker running=%d | heap free %u",
+                   id(usb_mic).is_running(), (unsigned) id(mic_bytes), (unsigned) id(mic_chunks),
+                   id(usb_speaker).is_running(), (unsigned) heap_caps_get_free_size(MALLOC_CAP_INTERNAL));

.agents/skills/hardware-test/templates/usb-cdc-acm-dongle-dut.yaml

@@ -0,0 +1,112 @@
+esphome:
+  name: cdc11634
+
+nrf52:
+  board: nrf52840dongle
+  dfu: true
+
+logger:
+  hardware_uart: USB_CDC
+  level: VERBOSE
+  logs:
+    usb_cdc_acm: VERBOSE
+    scheduler: DEBUG
+    component: DEBUG
+    app: DEBUG
+    preferences: DEBUG
+    logger: DEBUG
+    nrf52: DEBUG
+    dfu: DEBUG
+
+usb_cdc_acm:
+  interfaces:
+    - disabled: true
+    - id: cdc1
+
+globals:
+  - id: rx_total
+    type: uint32_t
+    initial_value: "0"
+  - id: tx_attempted
+    type: uint32_t
+    initial_value: "0"
+  - id: stream_left
+    type: int32_t
+    initial_value: "0"
+
+interval:
+  - interval: 20ms
+    then:
+      - lambda: |-
+          uint8_t buf[64];
+          while (id(cdc1).available() > 0) {
+            // a command is exactly two bytes, so what the host sends after it stays in the driver for peek/read
+            uint8_t first = 0;
+            id(cdc1).peek_byte(&first);
+            size_t n = std::min<size_t>(id(cdc1).available(), sizeof(buf));
+            if (first == 0x01 && n >= 2)
+              n = 2;
+            if (!id(cdc1).read_array(buf, n)) {
+              ESP_LOGE("test", "read_array(%u) failed", (unsigned) n);
+              break;
+            }
+            id(rx_total) += n;
+            if (buf[0] == 0x01 && n >= 2) {
+              const char cmd = buf[1];
+              if (cmd == 'B') {
+                // one oversized write: the 256 byte TX ring must drop the rest and warn once
+                static uint8_t big[1000];
+                for (size_t i = 0; i < sizeof(big); i++) big[i] = 'A' + (i % 26);
+                id(cdc1).write_array(big, sizeof(big));
+                id(tx_attempted) += sizeof(big);
+                ESP_LOGI("test", "burst 1000 written");
+              } else if (cmd == 'S') {
+                id(stream_left) = 100;
+                ESP_LOGI("test", "stream started");
+              } else if (cmd == 'L') {
+                ESP_LOGI("test", "line coding baud=%u data=%u stop=%u parity=%u", (unsigned) id(cdc1).get_baud_rate(),
+                         id(cdc1).get_data_bits(), id(cdc1).get_stop_bits(), (unsigned) id(cdc1).get_parity());
+              } else if (cmd == 'K') {
+                // the host sends "\x01KZ" in one write; the Z must still be in the driver here
+                uint8_t pb = 0, rb = 0;
+                bool okp = id(cdc1).peek_byte(&pb);
+                bool okr = id(cdc1).read_byte(&rb);
+                ESP_LOGI("test", "peek ok=%d 0x%02X read ok=%d 0x%02X (expect ok=1 0x5A for both)", okp, pb, okr, rb);
+                if (okr) id(rx_total) += 1;
+              } else if (cmd == 'F') {
+                static uint8_t pat[200];
+                for (size_t i = 0; i < sizeof(pat); i++) pat[i] = 'a' + (i % 26);
+                id(cdc1).write_array(pat, sizeof(pat));
+                id(tx_attempted) += sizeof(pat);
+                const uint32_t t0 = millis();
+                auto res = id(cdc1).flush();
+                ESP_LOGI("test", "flush result=%d took %u ms", (int) res, (unsigned) (millis() - t0));
+              } else if (cmd == 'C') {
+                ESP_LOGI("test", "counters rx=%u tx_attempted=%u (write_array drops silently when the ring is full)", (unsigned) id(rx_total), (unsigned) id(tx_attempted));
+              } else {
+                ESP_LOGW("test", "unknown cmd 0x%02X", cmd);
+              }
+              continue;
+            }
+            id(cdc1).write_array(buf, n);
+            id(tx_attempted) += n;
+          }
+  - interval: 100ms
+    then:
+      - lambda: |-
+          if (id(stream_left) > 0) {
+            char line[101];
+            int len = snprintf(line, sizeof(line), "STREAM %03d ", 100 - id(stream_left));
+            for (int i = len; i < 99; i++) line[i] = 'x';
+            line[99] = '\n';
+            id(cdc1).write_array(reinterpret_cast<const uint8_t *>(line), 100);
+            id(tx_attempted) += 100;
+            id(stream_left) -= 1;
+            if (id(stream_left) == 0) {
+              ESP_LOGI("test", "stream done");
+            }
+          }
+  - interval: 10s
+    then:
+      - lambda: |-
+          ESP_LOGI("test", "alive rx=%u tx_attempted=%u", (unsigned) id(rx_total), (unsigned) id(tx_attempted));

.agents/skills/hardware-test/templates/waveshare-s3-eth-camdiag.yaml

@@ -0,0 +1,83 @@
+esphome:
+  name: camdiag
+  on_boot:
+    priority: -100
+    then:
+      - output.set_level:
+          id: xclk
+          level: 50%
+      - delay: 200ms
+      - lambda: |-
+          auto *bus = id(cam_i2c);
+          auto scan = [&](const char *what) {
+            int found = 0;
+            for (uint8_t a = 0x08; a < 0x78; a++) {
+              if (bus->write(a, nullptr, 0) == i2c::ERROR_OK) {
+                ESP_LOGI("camdiag", "  ACK at 0x%02X", a);
+                found++;
+              }
+            }
+            ESP_LOGI("camdiag", "scan %s: %d devices", what, found);
+          };
+          auto rd16 = [&](uint16_t reg) {
+            uint8_t r[2] = {(uint8_t) (reg >> 8), (uint8_t) reg};
+            uint8_t v = 0xEE;
+            auto err = bus->write_readv(0x3C, r, 2, &v, 1);
+            ESP_LOGI("camdiag", "  0x3C [0x%04X] err=%d -> 0x%02X", reg, (int) err, v);
+            return v;
+          };
+          auto rd8 = [&](uint8_t addr, uint8_t reg) {
+            uint8_t v = 0xEE;
+            auto err = bus->write_readv(addr, &reg, 1, &v, 1);
+            ESP_LOGI("camdiag", "  0x%02X [0x%02X] (8 bit) err=%d -> 0x%02X", addr, reg, (int) err, v);
+          };
+          id(g8).turn_off(); delay(1500);
+          id(xclk).set_level(0.0f); delay(300);
+          scan("GPIO8 LOW, XCLK OFF");
+          id(xclk).set_level(0.5f); delay(300);
+          scan("GPIO8 LOW, XCLK ON");
+          ESP_LOGI("camdiag", "OV5640 style 16 bit reads (expect 300A=0x56 300B=0x40, 302A=0xB0..B2):");
+          rd16(0x300A); rd16(0x300B); rd16(0x302A); rd16(0x3008); rd16(0x3100); rd16(0x3103); rd16(0x4300);
+          ESP_LOGI("camdiag", "8 bit reads at 0x3C (GC2145 expects F0=0x21 F1=0x45):");
+          rd8(0x3C, 0xF0); rd8(0x3C, 0xF1); rd8(0x3C, 0x0A); rd8(0x3C, 0x0B);
+          ESP_LOGI("camdiag", "write 0x3103=0x11 then read back, then soft reset 0x3008=0x82 and re-read IDs:");
+          uint8_t w[3] = {0x31, 0x03, 0x11};
+          auto werr = bus->write(0x3C, w, 3);
+          ESP_LOGI("camdiag", "  write err=%d", (int) werr);
+          rd16(0x3103);
+          uint8_t rst[3] = {0x30, 0x08, 0x82};
+          bus->write(0x3C, rst, 3); delay(100);
+          rd16(0x300A); rd16(0x300B);
+          id(g8).turn_on(); delay(500); scan("GPIO8 HIGH (camera off)");
+          id(g8).turn_off(); delay(1500); scan("GPIO8 LOW again");
+
+esp32:
+  board: esp32-s3-devkitc-1
+  variant: esp32s3
+  flash_size: 16MB
+  framework:
+    type: esp-idf
+
+psram:
+  mode: octal
+  speed: 80MHz
+
+logger:
+  level: DEBUG
+  hardware_uart: USB_SERIAL_JTAG
+
+i2c:
+  - id: cam_i2c
+    sda: GPIO48
+    scl: GPIO47
+    frequency: 100kHz
+    scan: true
+
+output:
+  - platform: gpio
+    id: g8
+    pin: GPIO8
+  - platform: ledc
+    pin: GPIO3
+    id: xclk
+    frequency: 20000000Hz

.github/workflows/ci.yml

@@ -313,6 +313,7 @@ jobs:
           - "3.12"
           - "3.13"
           - "3.14"
+          - "3.15"
         os:
           - ubuntu-latest
           - macOS-latest
@@ -629,7 +630,7 @@ jobs:
             apt-get install -y libc6-dbg
 
       - name: Run CodSpeed benchmarks
-        uses: CodSpeedHQ/action@f842b9a3ffe213dbb81768fd7f7eeb4dfcf1c369 # v5.4.2
+        uses: CodSpeedHQ/action@821a40cd6c80e3cfe387caf55668287addd808da # v5.5.0
         with:
           run: |
             . venv/bin/activate

.github/workflows/codeql.yml

@@ -56,7 +56,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+        uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
@@ -84,6 +84,6 @@ jobs:
           exit 1
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+        uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           category: "/language:${{matrix.language}}"

.github/workflows/lock.yml

@@ -14,4 +14,4 @@ jobs:
     permissions:
       issues: write         # issues.lock on closed issues
       pull-requests: write  # issues.lock on closed pull requests
-    uses: esphome/workflows/.github/workflows/lock.yml@cc3e76de337dc59bc1cba8da58d963cd23b873f1  # 2026.9.0
+    uses: esphome/workflows/.github/workflows/lock.yml@31d160e5f0ffa0ee65d5b27cb55c153d415f2abe  # 2026.10.2

.github/workflows/stale.yml

@@ -16,7 +16,7 @@ jobs:
     # No GITHUB_TOKEN permissions: the reusable workflow mints an ESPHome
     # GitHub App token so the labels, comments and closures come from
     # esphome[bot] instead of github-actions[bot].
-    uses: esphome/workflows/.github/workflows/stale.yml@4fbce13026c393d6eb6b247e394dcd9ef1af76c2  # main
+    uses: esphome/workflows/.github/workflows/stale.yml@31d160e5f0ffa0ee65d5b27cb55c153d415f2abe  # main
     secrets:
       ESPHOME_GITHUB_APP_PRIVATE_KEY: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
     with:

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ ci:
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.17.0
+    rev: v0.17.1
     hooks:
       # Run the linter.
       - id: ruff

AGENTS.md

@@ -80,13 +80,15 @@ file does, and it is the authority when they disagree. The most useful starting
         ```python
         # Bad - looks up CONF_BLAH twice
         if CONF_BLAH in config:
-            cg.add(var.set_blah(config[CONF_BLAH]))
+            cg.add(var.set_blah_ms(config[CONF_BLAH].total_milliseconds))
 
         # Good - single lookup, value bound inline
         if (blah := config.get(CONF_BLAH)) is not None:
-            cg.add(var.set_blah(blah))
+            cg.add(var.set_blah_ms(blah.total_milliseconds))
         ```
         The same applies to `while` loops and comprehensions where it avoids recomputing a value. Don't contort code to use it — reach for `:=` only when it genuinely cuts repetition or an extra assignment line.
+        When the setter takes the value unchanged, use `cg.add_optional(var.set_blah, config.get(CONF_BLAH))`
+        instead; it is not awaited, and it skips only `None`, so `0` and `False` are still set.
 
 *   **C++ Field Visibility:**
     *   **Prefer `protected`:** Use `protected` for most class fields to enable extensibility and testing. Fields should be `lower_snake_case_with_trailing_underscore_`.
@@ -208,8 +210,14 @@ file does, and it is the authority when they disagree. The most useful starting
     *   **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`.
         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`, `reverse_bits`, `encode_uint16`);
-        pick the helper's polynomial and bit-order arguments instead of writing a CRC loop.
+    *   **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`); pick the helper's
+        arguments instead of writing a loop. Epson style 7-byte RTC calendars (one-hot weekday) use
+        `time::decode_bcd_calendar`.
+    *   **Bus helpers:** UART drains with `read_available(on_byte)` and `discard_available()`, text lines with
+        `LineReader<N>`; I2C has `update_register`, `write_registers` (PROGMEM `I2CRegValue` table), `check_chip_id`
+        and `read_bytes_16_le`. `if (!this->status_comm_result(ok)) return;` sets or clears the warning.
+        A child sensor that skips repeated values is `SUB_SENSOR_WITH_DEDUP(name, type)`.
     *   **An unset float is `NAN`**, not `optional<float>`; the optional costs 4 to 8 bytes of padding per member.
     *   **`PollingComponent` first runs `update()`** after a random share of the interval; call `this->update()` at the
         end of `setup()` when the entities need a state at boot.
@@ -287,7 +295,8 @@ file does, and it is the authority when they disagree. The most useful starting
           `from esphome.components.my_component import DOMAIN`. Keep it in alphabetical order with the other
           metadata constants. CI (`lint_component_domain`) fails without it.
         - `DEPENDENCIES`: List of required components
-        - `AUTO_LOAD`: Components to automatically load
+        - `AUTO_LOAD`: Components to automatically load. Not a way to put entities under the component's
+          own key; see "Entities of a hub" below.
         - `CONFLICTS_WITH`: Incompatible components
         - `CODEOWNERS`: GitHub usernames responsible for maintenance
         - `MULTI_CONF`: Whether multiple instances are allowed
@@ -379,6 +388,26 @@ file does, and it is the authority when they disagree. The most useful starting
               var = await switch.new_switch(config)
           ```
 
+        - **Entities of a hub:** a new component's entities go in platform files (`sensor.py`,
+          `binary_sensor.py`, ...) that take the hub's id, never under the hub's own key with their platforms
+          added to `AUTO_LOAD` to make that work. Auto loading a platform because the C++ uses its type is
+          fine. See https://developers.esphome.io/architecture/components/#exposing-multiple-entities.
+          ```yaml
+          # Bad - entities under the hub's key
+          my_hub:
+            connected:
+              name: Connected
+
+          # Good - the hub, then one platform entry that holds its entities
+          my_hub:
+            id: hub1
+          binary_sensor:
+            - platform: my_hub
+              my_hub_id: hub1  # optional with a single hub
+              connected:
+                name: Connected
+          ```
+
         - **Optional child entities of a hub:** bind the config once with `sensor.sub_sensors(config)` (or
           `sub_binary_sensors`, `sub_text_sensors`, `sub_buttons`, `sub_switches`, `sub_numbers`,
           `sub_selects` in their domains), adding `parent=hub` for entities that derive from `Parented<T>`,
@@ -389,15 +418,41 @@ file does, and it is the authority when they disagree. The most useful starting
           itself, `hub` for one fetched with `cg.get_variable`) so the calls fit on one line. Loops whose
           setter also takes an index, such as `set_gate_threshold(x, n)`, stay as they are.
           ```python
+          # my_hub/sensor.py
           async def to_code(config):
-              var = cg.new_Pvariable(config[CONF_ID])
+              hub = await cg.get_variable(config[CONF_MY_HUB_ID])
               sensors = sensor.sub_sensors(config)
-              await sensors(CONF_TEMPERATURE, var.set_temperature_sensor)
-              await sensors(CONF_HUMIDITY, var.set_humidity_sensor)
-              buttons = button.sub_buttons(config, parent=var)
-              await buttons(CONF_RESTART, var.set_restart_button)
+              await sensors(CONF_TEMPERATURE, hub.set_temperature_sensor)
+              await sensors(CONF_HUMIDITY, hub.set_humidity_sensor)
+
+
+          # my_hub/button.py
+          async def to_code(config):
+              hub = await cg.get_variable(config[CONF_MY_HUB_ID])
+              buttons = button.sub_buttons(config, parent=hub)
+              await buttons(CONF_RESTART, hub.set_restart_button)
           ```
 
+        - **Pins and referenced components:** set them with `await cg.add_pin(var.set_cs_pin, config[CONF_CS_PIN])`
+          and `await cg.add_variable(var.set_bus, config[CONF_BUS_ID])`; both skip a `None` value, so pass
+          `config.get(KEY)` for an optional key, and return what they created. Use `cg.register_parented` for `set_parent`.
+
+        - **Hub forwarding entities need no C++ class:** a button, switch, number or select that only calls its hub
+          uses `button.ApplyButton` (`switch.ApplySwitch`, `number.ApplyNumber`, `select.ApplySelect`) in its schema
+          and `apply=` on the `sub_*` call. The body is a call on the hub with `entity` and `state`, `value` or
+          `index`/`option` in scope; on a switch, number or select `publish="before"` or `"after"` publishes the state.
+          ```python
+          switches = switch.sub_switches(config, parent=hub)
+          await switches(CONF_BLUETOOTH, None, apply="set_bluetooth(state)", publish="after")
+          ```
+
+        - **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`)
+          constructs, registers and attaches in one call; `display.add_writer(var, config)` sets the lambda;
+          `MyEnum.options("on", prefix="MY_ENUM_")` builds an enum dict; `button.restart_button_schema(cls)` (and
+          `factory_reset_`, `query_`) are button presets; `fv.get_declaring_config(id)` finds a hub's config in
+          final validation.
+
 *   **Automations (Triggers, Actions, Conditions):**
 
     Automations have three building blocks: **Triggers** (fire when something happens), **Actions** (do something), and **Conditions** (check if something is true).

CODEOWNERS

@@ -30,6 +30,9 @@ esphome/components/airthings_ble/* @jeromelaban
 esphome/components/airthings_wave_base/* @jeromelaban @ncareau
 esphome/components/airthings_wave_mini/* @ncareau
 esphome/components/airthings_wave_plus/* @jeromelaban @precurse
+esphome/components/airton/* @Procsiab
+esphome/components/airton/select/* @Procsiab
+esphome/components/airton/switch/* @Procsiab
 esphome/components/alarm_control_panel/* @grahambrown11 @hwstar
 esphome/components/alpha3/* @jan-hofmeier
 esphome/components/am2315c/* @swoboda1337
@@ -130,7 +133,7 @@ esphome/components/climate/* @esphome/core
 esphome/components/climate_ir/* @glmnet
 esphome/components/cm1106/* @andrewjswan
 esphome/components/color_temperature/* @jesserockz
-esphome/components/combination/* @Cat-Ion @kahrendt
+esphome/components/combination/* @kahrendt
 esphome/components/const/* @esphome/core
 esphome/components/coolix/* @glmnet
 esphome/components/copy/* @OttoWinter
@@ -276,6 +279,7 @@ esphome/components/hmac_sha256/* @dwmw2
 esphome/components/hoermann_hcp/* @zweckj
 esphome/components/homeassistant/* @esphome/core @OttoWinter
 esphome/components/homeassistant/button/* @jesserockz
+esphome/components/homeassistant/light/* @egormanga
 esphome/components/homeassistant/number/* @landonr
 esphome/components/homeassistant/select/* @jesserockz
 esphome/components/homeassistant/switch/* @Links2004
@@ -597,7 +601,10 @@ esphome/components/ssd1331_base/* @kbx81
 esphome/components/ssd1331_spi/* @kbx81
 esphome/components/ssd1351_base/* @kbx81
 esphome/components/ssd1351_spi/* @kbx81
+esphome/components/st25r/* @JohnMcLear
+esphome/components/st25r_spi/* @JohnMcLear
 esphome/components/st7123/* @miniskipper
+esphome/components/st7305/* @clydebarrow
 esphome/components/st7567_base/* @latonita
 esphome/components/st7567_i2c/* @latonita
 esphome/components/st7567_spi/* @latonita
@@ -680,6 +687,7 @@ esphome/components/ultrasonic/* @ssieb @swoboda1337
 esphome/components/unicode/* @esphome/core
 esphome/components/update/* @jesserockz
 esphome/components/uponor_smatrix/* @kroimon
+esphome/components/usb_audio/* @ab-tools
 esphome/components/usb_cdc_acm/* @kbx81
 esphome/components/usb_host/* @clydebarrow
 esphome/components/usb_uart/* @clydebarrow
@@ -688,6 +696,7 @@ esphome/components/vbus/* @ssieb
 esphome/components/veml3235/* @kbx81
 esphome/components/veml7700/* @latonita
 esphome/components/version/* @esphome/core
+esphome/components/vevor_dtx/* @Bofr5555
 esphome/components/voice_assistant/* @jesserockz @kahrendt
 esphome/components/wake_on_lan/* @clydebarrow @willwill2will54
 esphome/components/watchdog/* @oarcher

docker/Dockerfile

@@ -22,7 +22,7 @@ RUN \
     -r /requirements.txt
 
 # Install the ESPHome Device Builder dashboard.
-RUN uv pip install --no-cache-dir esphome-device-builder==1.24.0
+RUN uv pip install --no-cache-dir esphome-device-builder==1.25.0
 
 RUN \
     platformio settings set enable_telemetry No \

esphome/__main__.py

@@ -791,6 +791,7 @@ def write_cpp(config: ConfigType) -> int:
 
     if not get_bool_env(ENV_NOGITIGNORE):
         writer.write_gitignore()
+    writer.check_build_tree_not_tracked()
 
     generate_cpp_contents(config)
     return write_cpp_file()

esphome/automation.py

@@ -430,12 +430,20 @@ def _apply_function(
 ) -> MockObj:
     """Emit the generated function and declare ``id_`` as the ``ApplyAction`` or
     ``ApplyCondition`` templated on it, so ``play()`` calls it directly."""
-    fn = cg.static_function(
-        f"esphome__{id_.id}__fn", return_type, lambda_args, statements
-    )
+    fn = apply_static_function(id_, return_type, lambda_args, statements)
     return cg.new_Pvariable(id_, cg.TemplateArguments(fn, *template_arg))
 
 
+def apply_static_function(
+    id_: ID,
+    return_type: SafeExpType,
+    params: TemplateArgsType,
+    statements: list[str],
+) -> MockObj:
+    """Emit the static function generated for ``id_`` and return an expression naming it."""
+    return cg.static_function(f"esphome__{id_.id}__fn", return_type, params, statements)
+
+
 async def _render_values(
     name: str,
     target: str,

esphome/codegen.py

@@ -53,6 +53,9 @@ from esphome.cpp_generator import (  # noqa: F401
     with_local_variable,
 )
 from esphome.cpp_helpers import (  # noqa: F401
+    add_optional,
+    add_pin,
+    add_variable,
     build_registry_entry,
     build_registry_list,
     extract_registry_entry_config,

esphome/components/a01nyub/a01nyub.cpp

@@ -9,15 +9,13 @@ namespace esphome::a01nyub {
 ESPHOME_LOG_TAG(TAG, "a01nyub.sensor");
 
 void A01nyubComponent::loop() {
-  uint8_t data;
-  while (this->available() > 0) {
-    this->read_byte(&data);
+  this->read_available([this](uint8_t data) {
     if (this->buffer_.empty() && (data != 0xff))
-      continue;
+      return;
     buffer_.push_back(data);
     if (this->buffer_.size() == 4)
       this->check_buffer_();
-  }
+  });
 }
 
 void A01nyubComponent::check_buffer_() {

esphome/components/a02yyuw/a02yyuw.cpp

@@ -9,15 +9,13 @@ namespace esphome::a02yyuw {
 ESPHOME_LOG_TAG(TAG, "a02yyuw.sensor");
 
 void A02yyuwComponent::loop() {
-  uint8_t data;
-  while (this->available() > 0) {
-    this->read_byte(&data);
+  this->read_available([this](uint8_t data) {
     if (this->buffer_.empty() && (data != 0xff))
-      continue;
+      return;
     buffer_.push_back(data);
     if (this->buffer_.size() == 4)
       this->check_buffer_();
-  }
+  });
 }
 
 void A02yyuwComponent::check_buffer_() {

esphome/components/a4988/stepper.py

@@ -23,11 +23,6 @@ async def to_code(config: ConfigType) -> None:
     await cg.register_component(var, config)
     await stepper.register_stepper(var, config)
 
-    step_pin = await cg.gpio_pin_expression(config[CONF_STEP_PIN])
-    cg.add(var.set_step_pin(step_pin))
-    dir_pin = await cg.gpio_pin_expression(config[CONF_DIR_PIN])
-    cg.add(var.set_dir_pin(dir_pin))
-
-    if sleep_pin_config := config.get(CONF_SLEEP_PIN):
-        sleep_pin = await cg.gpio_pin_expression(sleep_pin_config)
-        cg.add(var.set_sleep_pin(sleep_pin))
+    await cg.add_pin(var.set_step_pin, config[CONF_STEP_PIN])
+    await cg.add_pin(var.set_dir_pin, config[CONF_DIR_PIN])
+    await cg.add_pin(var.set_sleep_pin, config.get(CONF_SLEEP_PIN))

esphome/components/absolute_humidity/sensor.py

@@ -44,10 +44,7 @@ async def to_code(config: ConfigType) -> None:
     var = await sensor.new_sensor(config)
     await cg.register_component(var, config)
 
-    temperature_sensor = await cg.get_variable(config[CONF_TEMPERATURE])
-    cg.add(var.set_temperature_sensor(temperature_sensor))
-
-    humidity_sensor = await cg.get_variable(config[CONF_HUMIDITY])
-    cg.add(var.set_humidity_sensor(humidity_sensor))
+    await cg.add_variable(var.set_temperature_sensor, config[CONF_TEMPERATURE])
+    await cg.add_variable(var.set_humidity_sensor, config[CONF_HUMIDITY])
 
     cg.add(var.set_equation(config[CONF_EQUATION]))

esphome/components/ac_dimmer/output.py

@@ -68,10 +68,8 @@ async def to_code(config: ConfigType) -> None:
         config[CONF_MIN_POWER] = 0.1
     await output.register_output(var, config)
 
-    pin = await cg.gpio_pin_expression(config[CONF_GATE_PIN])
-    cg.add(var.set_gate_pin(pin))
-    pin = await cg.gpio_pin_expression(config[CONF_ZERO_CROSS_PIN])
-    cg.add(var.set_zero_cross_pin(pin))
+    await cg.add_pin(var.set_gate_pin, config[CONF_GATE_PIN])
+    await cg.add_pin(var.set_zero_cross_pin, config[CONF_ZERO_CROSS_PIN])
     cg.add(var.set_zero_cross_interrupt_type(config[CONF_ZERO_CROSS_INTERRUPT_TYPE]))
     cg.add(var.set_init_with_half_cycle(config[CONF_INIT_WITH_HALF_CYCLE]))
     cg.add(var.set_method(config[CONF_METHOD]))

esphome/components/adalight/adalight_light_effect.cpp

@@ -68,32 +68,32 @@ void AdalightLightEffect::apply(light::AddressableLight &it, const Color &curren
     blank_all_leds_(it);
   }
 
-  if (this->available() > 0) {
-    ESP_LOGV(TAG, "Frame: Available (size=%d).", this->available());
+  const size_t avail = this->available();
+  if (avail > 0) {
+    ESP_LOGV(TAG, "Frame: Available (size=%zu).", avail);
   }
 
-  while (this->available() != 0) {
-    uint8_t data;
-    if (!this->read_byte(&data))
-      break;
-    this->frame_.push_back(data);
-    this->last_byte_ = now;
+  this->read_available(
+      [this, &it, now](uint8_t data) {
+        this->frame_.push_back(data);
+        this->last_byte_ = now;
 
-    switch (this->parse_frame_(it)) {
-      case INVALID:
-        ESP_LOGD(TAG, "Frame: Invalid (size=%zu, first=%d).", this->frame_.size(), this->frame_[0]);
-        reset_frame_(it);
-        break;
+        switch (this->parse_frame_(it)) {
+          case INVALID:
+            ESP_LOGD(TAG, "Frame: Invalid (size=%zu, first=%d).", this->frame_.size(), this->frame_[0]);
+            reset_frame_(it);
+            break;
 
-      case PARTIAL:
-        break;
+          case PARTIAL:
+            break;
 
-      case CONSUMED:
-        ESP_LOGV(TAG, "Frame: Consumed (size=%zu).", this->frame_.size());
-        reset_frame_(it);
-        break;
-    }
-  }
+          case CONSUMED:
+            ESP_LOGV(TAG, "Frame: Consumed (size=%zu).", this->frame_.size());
+            reset_frame_(it);
+            break;
+        }
+      },
+      avail);
 }
 
 AdalightLightEffect::Frame AdalightLightEffect::parse_frame_(light::AddressableLight &it) {

esphome/components/adc/sensor.py

@@ -164,8 +164,7 @@ async def to_code(config: ConfigType) -> None:
         # Remove before 2027.2.0
         cg.add(var.set_is_temperature())
     elif not CORE.is_nrf52 or config[CONF_PIN][CONF_NUMBER] not in EXTRA_ADC:
-        pin = await cg.gpio_pin_expression(config[CONF_PIN])
-        cg.add(var.set_pin(pin))
+        await cg.add_pin(var.set_pin, config[CONF_PIN])
 
     # Skip the setters when the config matches the C++ initializers.
     if config[CONF_RAW]:

esphome/components/addressable_light/display.py

@@ -56,8 +56,4 @@ async def to_code(config: ConfigType) -> None:
         )
         cg.add(var.set_pixel_mapper(pixel_mapper_template_))
 
-    if lambda_config := config.get(CONF_LAMBDA):
-        lambda_ = await cg.process_lambda(
-            lambda_config, [(display.DisplayRef, "it")], return_type=cg.void
-        )
-        cg.add(var.set_writer(lambda_))
+    await display.add_writer(var, config)

esphome/components/ade7880/sensor.py

@@ -284,16 +284,9 @@ async def power_channel(config: ConfigType) -> MockObj:
 async def to_code(config: ConfigType) -> None:
     var = await i2c.new_i2c_component(config)
 
-    if irq0_pin := config.get(CONF_IRQ0_PIN):
-        pin = await cg.gpio_pin_expression(irq0_pin)
-        cg.add(var.set_irq0_pin(pin))
-
-    pin = await cg.gpio_pin_expression(config[CONF_IRQ1_PIN])
-    cg.add(var.set_irq1_pin(pin))
-
-    if reset_pin := config.get(CONF_RESET_PIN):
-        pin = await cg.gpio_pin_expression(reset_pin)
-        cg.add(var.set_reset_pin(pin))
+    await cg.add_pin(var.set_irq0_pin, config.get(CONF_IRQ0_PIN))
+    await cg.add_pin(var.set_irq1_pin, config[CONF_IRQ1_PIN])
+    await cg.add_pin(var.set_reset_pin, config.get(CONF_RESET_PIN))
 
     if frequency := config.get(CONF_FREQUENCY):
         cg.add(var.set_frequency(frequency))

esphome/components/ade7953_base/__init__.py

@@ -169,9 +169,7 @@ ADE7953_CONFIG_SCHEMA = cv.Schema(
 async def register_ade7953(var: MockObj, config: ConfigType) -> None:
     await cg.register_component(var, config)
 
-    if irq_pin_config := config.get(CONF_IRQ_PIN):
-        irq_pin = await cg.gpio_pin_expression(irq_pin_config)
-        cg.add(var.set_irq_pin(irq_pin))
+    await cg.add_pin(var.set_irq_pin, config.get(CONF_IRQ_PIN))
 
     cg.add(var.set_pga_v(PGA_GAINS[config.get(CONF_VOLTAGE_PGA_GAIN)]))
     cg.add(var.set_pga_ia(PGA_GAINS[config.get(CONF_CURRENT_PGA_GAIN_A)]))

esphome/components/airthings_ble/airthings_listener.cpp

@@ -1,4 +1,5 @@
 #include "airthings_listener.h"
+#include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 #include <cinttypes>
 
@@ -12,10 +13,7 @@ bool AirthingsListener::parse_device(const ble_device_base::ESPBTDevice &device)
       if (it.data.size() < 4)
         continue;
 
-      uint32_t sn = it.data[0];
-      sn |= ((uint32_t) it.data[1] << 8);
-      sn |= ((uint32_t) it.data[2] << 16);
-      sn |= ((uint32_t) it.data[3] << 24);
+      uint32_t sn = encode_value_le<uint32_t>(it.data.data());
 
       char addr_buf[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
       ESP_LOGD(TAG, "Found AirThings device Serial:%" PRIu32 " (MAC: %s)", sn, device.address_str_to(addr_buf));

esphome/components/airton/__init__.py

@@ -0,0 +1,2 @@
+CODEOWNERS = ["@Procsiab"]
+DOMAIN = "airton"

esphome/components/airton/airton.cpp

@@ -0,0 +1,307 @@
+#include "airton.h"
+#include "esphome/core/helpers.h"
+#include "esphome/core/log.h"
+
+namespace esphome::airton {
+
+ESPHOME_LOG_TAG(TAG, "airton.climate");
+
+// Distinct from the climate's own RESTORE_STATE_VERSION, which shares the entity's preference key
+static constexpr uint32_t RESTORE_SETTINGS_VERSION = 0x2E86A1F3UL;
+
+// From IRutils.h of IRremoteESP8266 library
+static uint8_t checksum(const uint8_t *frame) {
+  return static_cast<uint8_t>(0x7F - sum_bytes(frame, AIRTON_STATE_FRAME_SIZE - 1)) ^ 0x2C;
+}
+
+void AirtonClimate::setup() {
+  climate_ir::ClimateIR::setup();
+  // The flap position is the one source of truth for the swing mode the climate state restored
+  this->settings_pref_ = this->make_entity_preference<AirtonSettings>(RESTORE_SETTINGS_VERSION);
+  this->settings_pref_.load(&this->settings_);
+  this->sync_swing_mode_();
+  this->publish_settings_();
+  this->publish_state();
+}
+
+void AirtonClimate::publish_settings_() {
+#ifdef USE_SWITCH
+  if (this->sleep_mode_switch_ != nullptr)
+    this->sleep_mode_switch_->publish_state(this->settings_.sleep_state);
+  if (this->display_switch_ != nullptr)
+    this->display_switch_->publish_state(this->settings_.display_state);
+#endif
+#ifdef USE_SELECT
+  if (this->vertical_direction_select_ != nullptr)
+    this->vertical_direction_select_->publish_state(static_cast<size_t>(this->settings_.vertical_direction));
+#endif
+}
+
+void AirtonClimate::save_settings_() { this->settings_pref_.save(&this->settings_); }
+
+void AirtonClimate::sync_swing_mode_() {
+  this->swing_mode = this->settings_.vertical_direction == VerticalDirection::VERTICAL_DIRECTION_SWING
+                         ? climate::CLIMATE_SWING_VERTICAL
+                         : climate::CLIMATE_SWING_OFF;
+}
+
+// The unit has no sleep mode while it only fans or picks the mode itself
+bool AirtonClimate::sleep_mode_allowed_() const {
+  return this->mode != climate::CLIMATE_MODE_FAN_ONLY && this->mode != climate::CLIMATE_MODE_HEAT_COOL;
+}
+
+// Each setter stores and saves before it publishes: an automation on the entity runs inside
+// publish_state() and may set the value again, which must not be undone afterwards
+bool AirtonClimate::set_sleep_mode_state(bool state) {
+  state = state && this->sleep_mode_allowed_();
+  const bool changed = state != this->settings_.sleep_state;
+  if (changed) {
+    this->settings_.sleep_state = state;
+    this->save_settings_();
+  }
+#ifdef USE_SWITCH
+  if (this->sleep_mode_switch_ != nullptr)
+    this->sleep_mode_switch_->publish_state(state);
+#endif
+  return changed;
+}
+
+bool AirtonClimate::set_display_state(bool state) {
+  const bool changed = state != this->settings_.display_state;
+  if (changed) {
+    this->settings_.display_state = state;
+    this->save_settings_();
+  }
+#ifdef USE_SWITCH
+  if (this->display_switch_ != nullptr)
+    this->display_switch_->publish_state(state);
+#endif
+  return changed;
+}
+
+bool AirtonClimate::set_vertical_direction_state(VerticalDirection direction) {
+  const bool changed = direction != this->settings_.vertical_direction;
+  if (changed) {
+    this->settings_.vertical_direction = direction;
+    this->sync_swing_mode_();
+    this->save_settings_();
+  }
+#ifdef USE_SELECT
+  if (this->vertical_direction_select_ != nullptr)
+    this->vertical_direction_select_->publish_state(static_cast<size_t>(direction));
+#endif
+  return changed;
+}
+
+void AirtonClimate::send_settings() {
+  this->transmit_state();
+  this->publish_state();
+}
+
+void AirtonClimate::control(const climate::ClimateCall &call) {
+  // ClimateIR::control() sends and publishes the whole state afterwards
+  // Only a change of swing mode moves the flap, so a repeated swing-off keeps a fixed position
+  if (auto swing_mode = call.get_swing_mode(); swing_mode.has_value() && *swing_mode != this->swing_mode) {
+    this->set_vertical_direction_state(*swing_mode == climate::CLIMATE_SWING_VERTICAL
+                                           ? VerticalDirection::VERTICAL_DIRECTION_SWING
+                                           : VerticalDirection::VERTICAL_DIRECTION_OFF);
+  }
+  ClimateIR::control(call);
+}
+
+void AirtonClimate::transmit_state() {
+  // Entering fan-only or automatic mode drops sleep mode, as the remote does
+  if (!this->sleep_mode_allowed_())
+    this->set_sleep_mode_state(false);
+  // Sampled valid state
+  // Power: On, Mode: 2 (Dry), Fan: 1 (Quiet), Temp: 20C, Swing(V): On, Econo: Off, Turbo: Off, Light: On, Health: On,
+  // Sleep: Off. 0x74C461041A11D3
+  // The turbo bit above the fan speed stays clear, as the remote sends it
+  uint8_t remote_state[AIRTON_STATE_FRAME_SIZE] = {
+      AIRTON_HEADER_BYTE0,
+      AIRTON_HEADER_BYTE1,
+      static_cast<uint8_t>(this->operation_mode_() | (this->fan_speed_() << 4)),
+      this->temperature_(),
+      static_cast<uint8_t>(this->settings_.vertical_direction),
+      this->operation_settings_(),
+      0,
+  };
+  remote_state[6] = checksum(remote_state);
+
+  ESP_LOGV(TAG, "Sending: %02X %02X %02X %02X %02X %02X %02X", remote_state[6], remote_state[5], remote_state[4],
+           remote_state[3], remote_state[2], remote_state[1], remote_state[0]);
+
+  auto transmit = this->transmitter_->transmit();
+  auto *data = transmit.get_data();
+  data->set_carrier_frequency(AIRTON_IR_FREQUENCY);
+  data->mark(AIRTON_HEADER_MARK);
+  data->space(AIRTON_HEADER_SPACE);
+  data->item_bytes<AIRTON_BIT_TIMINGS>(remote_state, AIRTON_STATE_FRAME_SIZE);
+
+  data->mark(AIRTON_BIT_MARK);
+  data->space(AIRTON_MESSAGE_SPACE);
+
+  transmit.perform();
+}
+
+uint8_t AirtonClimate::operation_mode_() {
+  uint8_t operating_mode = 0b1000;  // First bit is for power state
+  switch (this->mode) {
+    case climate::CLIMATE_MODE_COOL:
+      operating_mode |= AIRTON_MODE_COOL;
+      break;
+    case climate::CLIMATE_MODE_DRY:
+      operating_mode |= AIRTON_MODE_DRY;
+      break;
+    case climate::CLIMATE_MODE_HEAT:
+      operating_mode |= AIRTON_MODE_HEAT;
+      break;
+    case climate::CLIMATE_MODE_HEAT_COOL:
+      operating_mode |= AIRTON_MODE_AUTO;
+      break;
+    case climate::CLIMATE_MODE_FAN_ONLY:
+      operating_mode |= AIRTON_MODE_FAN;
+      break;
+    case climate::CLIMATE_MODE_OFF:
+    default:
+      operating_mode = 0b0111 & this->previous_mode_;  // Set previous mode with power state bit off
+  }
+  this->previous_mode_ = operating_mode;
+  return operating_mode;
+}
+
+uint8_t AirtonClimate::fan_speed_() {
+  uint8_t fan_speed;
+  switch (this->fan_mode.value_or(climate::CLIMATE_FAN_AUTO)) {
+    case climate::CLIMATE_FAN_LOW:
+      fan_speed = AIRTON_FAN_1;
+      break;
+    case climate::CLIMATE_FAN_MEDIUM:
+      fan_speed = AIRTON_FAN_3;
+      break;
+    case climate::CLIMATE_FAN_HIGH:
+      fan_speed = AIRTON_FAN_5;
+      break;
+    case climate::CLIMATE_FAN_AUTO:
+    default:
+      fan_speed = AIRTON_FAN_AUTO;
+  }
+  return fan_speed;
+}
+
+uint8_t AirtonClimate::temperature_() {
+  switch (this->mode) {
+    case climate::CLIMATE_MODE_HEAT_COOL:
+      return AIRTON_AUTO_MODE_TEMP - AIRTON_TEMP_MIN;
+    default:
+      return static_cast<uint8_t>(roundf(clamp<float>(this->target_temperature, AIRTON_TEMP_MIN, AIRTON_TEMP_MAX))) -
+             AIRTON_TEMP_MIN;
+  }
+}
+
+// The bits of this packet's byte have the following meanings (from MSB to LSB)
+// Light, Health, Unknown, HeatOn, Unknown, NotAutoOn, Sleep, Econo
+uint8_t AirtonClimate::operation_settings_() {
+  uint8_t settings = 0;
+  if (this->mode == climate::CLIMATE_MODE_HEAT) {  // Set heating bit if on the corresponding mode
+    settings |= (1 << 4);
+  }
+  if (this->settings_.display_state) {
+    settings |= (1 << 7);
+  }
+  if (this->settings_.sleep_state) {
+    settings |= (1 << 1);
+  }
+  settings |= 0b01000000;  // Health, as the remote always sends it
+  if (this->mode != climate::CLIMATE_MODE_HEAT_COOL) {
+    settings |= 0b00000100;  // NotAutoOn: clear only while the unit picks the mode itself
+  }
+  return settings;
+}
+
+void AirtonClimate::parse_state_frame_(const uint8_t *frame) {
+  uint8_t mode = frame[2];
+  // A later "off" repeats the mode the remote last sent, as the remote itself does
+  this->previous_mode_ = mode & 0b00001111;
+  if (mode & 0b00001000) {  // The power bit
+    switch (mode & 0b00000111) {
+      case AIRTON_MODE_COOL:
+        this->mode = climate::CLIMATE_MODE_COOL;
+        break;
+      case AIRTON_MODE_DRY:
+        this->mode = climate::CLIMATE_MODE_DRY;
+        break;
+      case AIRTON_MODE_HEAT:
+        this->mode = climate::CLIMATE_MODE_HEAT;
+        break;
+      case AIRTON_MODE_AUTO:
+        this->mode = climate::CLIMATE_MODE_HEAT_COOL;
+        break;
+      case AIRTON_MODE_FAN:
+        this->mode = climate::CLIMATE_MODE_FAN_ONLY;
+        break;
+    }
+  } else {
+    this->mode = climate::CLIMATE_MODE_OFF;
+  }
+  uint8_t fan_mode = (frame[2] & 0b01110000) >> 4;
+
+  switch (fan_mode) {
+    case AIRTON_FAN_1:
+    case AIRTON_FAN_2:
+      this->fan_mode = climate::CLIMATE_FAN_LOW;
+      break;
+    case AIRTON_FAN_3:
+      this->fan_mode = climate::CLIMATE_FAN_MEDIUM;
+      break;
+    case AIRTON_FAN_4:
+    case AIRTON_FAN_5:
+      this->fan_mode = climate::CLIMATE_FAN_HIGH;
+      break;
+    case AIRTON_FAN_AUTO:
+      this->fan_mode = climate::CLIMATE_FAN_AUTO;
+      break;
+  }
+
+  this->target_temperature = (frame[3] & 0b00001111) + AIRTON_TEMP_MIN;
+
+  const uint8_t direction = frame[4] & 0b00001111;
+  if (direction <= static_cast<uint8_t>(VerticalDirection::VERTICAL_DIRECTION_DOWN)) {
+    this->set_vertical_direction_state(static_cast<VerticalDirection>(direction));
+  } else {
+    ESP_LOGV(TAG, "Unknown vertical direction %u", direction);
+  }
+  this->set_display_state((frame[5] & 0b10000000) != 0);
+  this->set_sleep_mode_state((frame[5] & 0b00000010) != 0);
+
+  this->publish_state();
+}
+
+bool AirtonClimate::on_receive(remote_base::RemoteReceiveData data) {
+  uint8_t remote_state[AIRTON_STATE_FRAME_SIZE];
+  if (!data.expect_item(AIRTON_HEADER_MARK, AIRTON_HEADER_SPACE)) {
+    ESP_LOGV(TAG, "Wrong header encoding detected!");
+    return false;
+  }
+  if (!data.expect_bytes<AIRTON_BIT_TIMINGS>(remote_state, AIRTON_STATE_FRAME_SIZE)) {
+    ESP_LOGV(TAG, "Wrong modulation encoding");
+    return false;
+  }
+
+  if (remote_state[0] != AIRTON_HEADER_BYTE0 || remote_state[1] != AIRTON_HEADER_BYTE1) {
+    ESP_LOGV(TAG, "Wrong header contents: %02X %02X", remote_state[1], remote_state[0]);
+    return false;
+  }
+  const uint8_t expected = checksum(remote_state);
+  if (remote_state[AIRTON_STATE_FRAME_SIZE - 1] != expected) {
+    ESP_LOGV(TAG, "Checksum error: calculated %02X, received %02X", expected,
+             remote_state[AIRTON_STATE_FRAME_SIZE - 1]);
+    return false;
+  }
+  ESP_LOGV(TAG, "Received: %02X %02X %02X %02X %02X %02X %02X", remote_state[6], remote_state[5], remote_state[4],
+           remote_state[3], remote_state[2], remote_state[1], remote_state[0]);
+  this->parse_state_frame_(remote_state);
+  return true;
+}
+
+}  // namespace esphome::airton