Python 3.14 compatibility + EZSP-over-TCP stability fixes

[silenthooligan]

Five focused changes that together unbreak EZSP/EmberZNet on Python 3.14 and fix several long-standing rough edges with TCP-bridged serial radios (ser2net, ESPHome stream_server / serial_proxy).

Supersedes #711, which was closed unmerged by its author with no review. This PR rebases that work onto current dev, drops the diagnostic-only LOGGER.warning calls #711 carried alongside the fixes, restores the post-#714 NETWORK_COORDINATOR_STARTUP_RESET_WAIT = 2, adds the bellows/cli/util.py get_event_loop fix, and is validated end-to-end against real hardware (see below).

Python 3.14 compatibility

• bellows/thread.py: asyncio.iscoroutinefunction → inspect.iscoroutinefunction. Same semantics, drops the deprecation warning.
• bellows/thread.py, bellows/uart.py: replace four asyncio.get_event_loop() calls (deprecated outside a running loop on 3.14) with asyncio.get_running_loop(). All four sites are reached from async def paths.
• bellows/cli/util.py: background() decorator wrapped CLI commands with asyncio.get_event_loop().run_until_complete(...), which raises RuntimeError: no current event loop on 3.14 from a fresh sync entry point. Replaced with asyncio.run(...).

ThreadsafeProxy: closed-loop as ConnectionError

When the secondary event-loop thread is gone, ThreadsafeProxy used to log a warning and return None, which propagated as TypeError: 'NoneType' object can't be awaited and (on 3.14) left ZHA in an indefinite retry loop. Raise ConnectionError so callers can handle the failure cleanly. Also guards the loop being closed between the is_closed() check and run_coroutine_threadsafe() dispatch.

EZSP startup race over TCP

Reset frames from the NCP can arrive faster than wait_for_startup_reset() is reached when the transport is TCP. The first reset gets dropped, enter_failed_state() fires, and the integration never recovers without a manual restart.

• bellows/uart.py::_connect: pre-create gateway._startup_reset_future before opening the connection so any reset frame received during setup is caught by reset_received().
• bellows/uart.py::wait_for_startup_reset: replace assert is None with if is None so the pre-created future isn't rejected.

TCP serial-bridge connection lifecycle

• bellows/ash.py::eof_received: return True to suppress the transport's auto-close. Serial-over-TCP bridges (ser2net, ESPHome stream_server / serial_proxy) sometimes signal EOF during initialization without intending to close the socket; the default auto-close orphans the connection.
• bellows/ezsp/__init__.py::_startup_reset: raise a clear EzspError when self._gw is None.
• bellows/ezsp/__init__.py::disconnect: tolerate _gw is None, and on ConnectionError from the gateway force-close the underlying TCP socket so ser2net/stream_server releases the port for subsequent attempts.

Test plan

• All 112 existing tests pass on Python 3.14.2.
• tests/test_thread.py::test_proxy_loop_closed now asserts ConnectionError (was: silently returns).
• tests/test_ezsp.py::test_startup_reset_gw_none covers the new null-gateway guard.
• tests/test_ezsp.py::test_disconnect_gw_none covers tolerance of null gateway in disconnect().

End-to-end validation against real hardware

Patched bellows was vendored into a Home Assistant 2026.5.0b2 image and exercised against a live Nabu Casa Connect ZBT-2 (EFR32MG24 Zigbee NCP) behind an ESPHome stream_server raw-TCP bridge on Python 3.14.2:

1. bellows.ezsp.EZSP.connect() + startup_reset() complete cleanly. EZSP_VERSION = 13 negotiated. get_board_info() returns NCP identity (Nabu Casa, Connect ZBT).
2. ZHA boots fresh, forms a network on channel 25, pairs five IAS-Zone water-leak sensors (Samjin model water).
3. After OTA-ing the dongle to ESPHome serial_proxy (encrypted native API on :6053 only) and reconfiguring ZHA to esphome-hass://esphome/<entry_id>?port_name=..., the existing zigbee.db is reused via setup_strategy_advanced -> reuse_settings. All five sensors auto-rejoin without re-pair, attribute reports flow (battery, temperature, water-leak state).

Without this patch, step 1 fails immediately on Python 3.14 with 'NoneType' object can't be awaited (closed event loop) or AttributeError (get_event_loop no current loop), depending on which call path fires first. Step 3 also exercises the EOF-during-init suppression — the encrypted native-API tunnel issued an EOF during the noise-protocol handshake that the eof_received -> return True change keeps open.

Provenance

The bulk of the runtime fixes (and their tests) were originally drafted by @aautem in #711. Credited via Co-Authored-By trailer in the commit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.54%. Comparing base (4b97a6d) to head (384975d).

Additional details and impacted files

@@           Coverage Diff           @@
##              dev     #720   +/-   ##
=======================================
  Coverage   99.54%   99.54%           
=======================================
  Files          61       61           
  Lines        4147     4155    +8     
=======================================
+ Hits         4128     4136    +8     
  Misses         19       19           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[puddly]

Can you attach some debug logs of the issue you're having and how this PR solves it? ZHA is used with a ton of TCP coordinators and we haven't really had reports of issues like this.

[silenthooligan]

Live logs against a Nabu Casa Connect ZBT-2 (EFR32MG24, ESPHome stream_server raw-TCP bridge on 192.168.40.16:6638) from inside a fresh python:3.14-slim container, comparing stock 0.49.1 vs this PR.

Full bellows DEBUG output for all three runs + the test scripts are in this gist:
https://gist.github.com/silenthooligan/6d1399b94ebad2716a2e0b39a1809c7f

Summary:

01: stock 0.49.1, first connect (no teardown)
EZSP startup completes cleanly, board info reads. The recent #714 startup-wait extension dodges the original startup race on first connect, so the bug doesn't reproduce here on a clean boot. It surfaces on reconnect cycles instead, see runs 02/03.

02: stock 0.49.1, secondary loop teardown then dispatch

>>> Phase 1: connect + startup
>>> connected, EZSP version 13
>>> Phase 2: closing the secondary loop
>>> secondary loop running=False closed=True
>>> Phase 3: dispatch a command via the proxy
WARNING [bellows.thread] Attempted to use a closed event loop
>>> dispatch FAILED: TypeError: 'NoneType' object can't be awaited
>>> Phase 4: clean disconnect
WARNING [bellows.thread] Attempted to use a closed event loop
>>> disconnect FAILED: TypeError: 'NoneType' object can't be awaited

Caller has no signal that the connection died (just a TypeError on None), so the integration's retry path can't tell the difference between a transient command failure and a dead transport. ZHA loops without ever rebuilding the gateway.

03: patched bellows (this PR), same teardown

>>> Phase 1: connect + startup
>>> connected, EZSP version 13
>>> Phase 2: closing the secondary loop
>>> secondary loop running=False closed=True
>>> Phase 3: dispatch a command via the proxy
>>> dispatch FAILED: ConnectionError: Attempted to use a closed event loop, the connection may have been lost
>>> Phase 4: clean disconnect
>>> disconnect OK

ConnectionError is raised on dispatch (catchable, signals "rebuild the connection"), and disconnect() succeeds because the PR's fallback force-closes the underlying TCP socket when the gateway can't be reached.

Three conditions for the bug to fire in production: closed secondary loop, caller mid-dispatch, Python 3.14's stricter await None. Stable single-boot ConBee/SkyConnect setups don't see it. Setups that cycle (HA restarts, host reboots, WiFi-bridged dongles flapping) do.

Other bits in this PR (uart.py::wait_for_startup_reset race pre-create, ash.py::eof_received -> True for serial-over-TCP bridges that signal EOF mid-handshake) are TCP-only and don't surface on the first-connect run because #714 already extended the startup wait. They show up on reconnect attempts against ESPHome serial_proxy (encrypted native API) where the noise handshake itself produces an EOF that auto-closes the socket on stock.

[puddly]

Can you attach a log from the live device that you're communicating with?

[silenthooligan]

Live logs are in this gist (full bellows DEBUG for all three runs plus the test scripts):
https://gist.github.com/silenthooligan/6d1399b94ebad2716a2e0b39a1809c7f

Hardware: Nabu Casa Connect ZBT-2 (EFR32MG24) on an ESPHome stream_server raw-TCP bridge at 192.168.40.16:6638. Driver-side tests run from python:3.14-slim.

The race only fires when the secondary loop closes mid-dispatch (HA restart, reconnect cycle). Clean first-connect runs dodge it because #714's startup-wait extension already covers that window.

Stock 0.49.1, secondary loop closed then dispatch:

WARNING [bellows.thread] Attempted to use a closed event loop
>>> dispatch FAILED: TypeError: 'NoneType' object can't be awaited
>>> disconnect FAILED: TypeError: 'NoneType' object can't be awaited

This PR, same scenario:

>>> dispatch FAILED: ConnectionError: Attempted to use a closed event loop, the connection may have been lost
>>> disconnect OK

Caller now gets a catchable ConnectionError instead of a bare TypeError on None, and disconnect() succeeds because the PR's fallback force-closes the underlying TCP socket when the gateway can't be reached. ZHA's reconnect path can act on the former; with the latter it hangs.

[puddly]

transport.get_extra_info("socket") is not part of the latest version of zigpy or bellows, please make sure you're using the latest version of the packages. I don't think this is a good pattern.

[puddly]

I think it would be simpler to have _startup_reset_future default to loop.create_future() within Gateway.

[silenthooligan]

Apologies @puddly. Didn't review the diff carefully before opening. The day job has been demanding lately and I was swivel-chairing with this as a distraction trying to get the ZBT-2 WiFi transport (ESPHome stream_server / serial_proxy bridge) running on my own setup. Used Claude to iterate fixes against live hardware, which is how both rough edges you flagged ended up in the patch. My fault for not catching them on second pass.

Both addressed:

1. bellows/ezsp/__init__.py force-close fallback. Dropped. You're right the walk into asyncio internals via private attrs isn't the way, and zigpy 1.4's serialx migration already made it a no-op for current HA. Simplified handler now just clears _gw on ConnectionError. Live cycle re-run shows Phase 4 still hits >>> disconnect OK, confirming the force-close was inert. New log added to the gist as 04-patched-cycle-simplified.log.
2. bellows/uart.py _startup_reset_future pre-create. Moved into Gateway.__init__ per your suggestion. Optional loop=None keyword so existing tests that construct Gateway in non-async context keep the original None default; _connect() passes the loop in to trigger pre-create on the real path.

Tests: 428 pass on Python 3.14.2 across the two new commits, no regressions.

bellows itself was already current (PR base is dev HEAD 4b97a6df, no missed commits). zigpy 1.4 serialx is the moving piece I should have caught myself before submitting.

[puddly]

How does the remote signal EOF without closing? The asyncio docs state machine shows:

start -> connection_made
    [-> data_received]*
    [-> eof_received]?
-> connection_lost -> end

And the docs state:

This method may return a false value (including None), in which case the transport will close itself. Conversely, if this method returns a true value, the protocol used determines whether to close the transport. Since the default implementation returns None, it implicitly closes the connection.

I don't think this change is right?

[silenthooligan]

Fair point. I borrowed that hunk from #711's commit body (the closed-unmerged PR by @aautem this one rebased from) without validating its premise myself, it claimed an init-time spurious EOF on serial-over-TCP. You're right that the asyncio docs are clear, and honestly I don't have a reproduction of that scenario on my own setup either: stock 0.49.1 on Python 3.14.2 against the ZBT-2 over stream_server completes EZSP startup cleanly on first connect (log in the gist as 01-stock-probe.log).

Dropping it and deferring to you on this one. You know this code far better than I do, and I'd rather get it right than push something speculative. Door's open if a concrete EOF-during-init case surfaces later for some bridge config.

Reverted in f43c38f.