[FEAT] Use serial proxy for ZBT-2 Zigbee

[balloob]

Project

• fliphtml5-liberator
• cyberdrop-dl-gui
• ha-connect-portable
• Other / repo-level

Description

ZHA in HA supports serial proxies. So you can replace stream server with serial proxies in ha-connect-portable/zbt-2-zigbee/zbt-2-zigbee.yaml.

Screenshot from serial port selector in HA 2026.5:

Steps to Reproduce

Expected Behavior

Actual Behavior

Environment

• OS:
• Python version:
• Docker version (if applicable):
• Relevant dependency versions:

Additional Context

[silenthooligan]

Thanks @balloob for filing this. Closing the loop. Validated end-to-end against the actual hardware. Posting the dependency map and what still needs upstream fixes so anyone landing here can decide whether to wait or compile.

What works

ZBT-2 in Zigbee role over ESPHome serial_proxy, paired into ZHA, no raw TCP listener on the dongle, encryption end-to-end on the wire. Single :6053 listener replaces the prior :6053 (ESPHome API) + :6638 (stream_server raw TCP) pair. Same model as the ZWA-2's zwave_proxy, no external_components: oxan/esphome-stream-server dependency.

ZHA URL form: esphome-hass://esphome/<esphome_config_entry_id>?port_name=<serial_proxy.name>. Picker auto-discovers it on HA 2026.5.

Dependencies that had to line up

1. ESPHome >= 2026.3.0 for the first-party serial_proxy component. Already in main, not gated on anything.
2. Home Assistant >= 2026.5 for homeassistant/components/esphome/serial_proxy.py (the esphome-hass:// URL handler that registers with serialx) and the ZHA serial-port picker that enumerates discovered proxies. Currently in beta (2026.5.0b2). zigpy 1.4.0 itself does not parse esphome-hass:// directly. HA's esphome integration is what wraps aioesphomeapi and exposes the stream to zigpy.
3. bellows runtime fixes for Python 3.14 + TCP serial transport. Stock bellows==0.49.1 (what HA 2026.5.0b2 ships) breaks on the Python 3.14 + EZSP-over-TCP combo before you ever get to test serial_proxy. Symptoms include: 'NoneType' object can't be awaited, Attempted to use a closed event loop, indefinite ZHA retry loops with no recovery, and dropped reset frames during NCP startup over TCP. Filed as zigpy/bellows#720 (rebases the abandoned #711 onto current dev, drops diagnostic-only logging, restores the post-#714 NETWORK_COORDINATOR_STARTUP_RESET_WAIT = 2, adds a bellows/cli/util.py get_event_loop fix, end-to-end validated).
4. ZBT-2 firmware swap to serial_proxy. Nabu Casa hasn't shipped portable WiFi firmware for the ZBT-2; the YAML in zbt-2-zigbee/ is the community implementation. Live config in this repo will get bumped to serial_proxy shortly with the prior stream_server config retained under legacy-stream-server/.

What still blocks "anyone clones this and it just works"

Two upstream gates:

• zigpy/bellows#720 needs to merge and land in a release that HA picks up. Until then, anyone running ZHA over a TCP-bridged radio on HA 2026.4+ (Python 3.14) is broken with stock bellows, regardless of whether they use socket:// or esphome-hass://.
• HA 2026.5 needs to cut to :stable. Until then, the esphome-hass:// handler and the ZHA picker are only present in beta builds.

For users who don't want to wait

Either path works today on HA 2026.5.0b2:

Option A: vendor the bellows patch into a custom HA image. Thin layer:

ARG HA_TAG=2026.5.0b2
FROM ghcr.io/home-assistant/home-assistant:${HA_TAG}
RUN pip install --no-deps --force-reinstall \
    https://github.com/silenthooligan/bellows/archive/refs/heads/fix/python-3.14-ezsp-tcp.tar.gz

Pin to a specific SHA for reproducibility. Replace with upstream bellows==<next-release> once #720 merges.

Option B: apply the diff manually. The patch surface is small (bellows/{ash,uart,thread,cli/util}.py and bellows/ezsp/__init__.py, total <100 lines). Diff is on the PR. Easiest if you build HA from source already.

ZHA migration note (for anyone with an existing socket:// ZHA setup)

ZHA's config entry doesn't support reconfigure (supports_reconfigure: false). To swap radio path you have to delete and recreate the integration. Use setup_strategy_advanced -> reuse_settings on the recreate, NOT setup_strategy_recommended (which forms a fresh network and forces re-pair of every device). With reuse_settings, the existing zigbee.db is honored and devices auto-rejoin within ~30s as long as the same physical NCP is on the new URL.

Items resolved during validation that aren't in the PR

Two things outside bellows that bit during the rollout, listed for anyone debugging similar:

• esphome upload <yaml> does NOT recompile; it flashes whatever's in .esphome/build/<name>/.pioenvs/<name>/firmware.bin. Two YAMLs sharing the same esphome.name: will fight over the build dir. Use esphome run (always recompiles) when switching between sibling YAMLs, or give each candidate YAML a distinct name:.
• When swapping the ZBT-2's ESP32-S3 firmware between the unencrypted-API stream_server build and the encrypted-API serial_proxy build, HA's existing ESPHome config entry doesn't auto-prompt for the new noise key. Trigger the entry's reconfigure flow manually (encryption_key step) before ZHA tries to use it via esphome-hass://. Otherwise ZHA gets cannot_connect against an integration entry that reports state: loaded but has unavailable entities.

Will update this repo's zbt-2-zigbee/ YAML + README to make serial_proxy the default, with stream_server parked as a legacy fallback for anyone on older HA / pre-bellows-fix.

[silenthooligan]

Repo update is in: e5467fb. zbt-2-zigbee defaults to serial_proxy now, legacy stream_server parked at zbt-2-zigbee/legacy-stream-server/ for the pre-2026.5 / pre-bellows-fix path. README and zbt-2-zigbee/README.md spell out the dependency chain (HA >= 2026.5 + zigpy/bellows#720) and the in-place migration gotcha (setup_strategy_advanced -> reuse_settings on ZHA recreate so the zigbee.db survives the radio-path swap).