Skip to content

Tell the user why a device is unreachable instead of just 'TimeOut' - #501

Open
alecplumb wants to merge 1 commit into
RobHofmann:masterfrom
alecplumb:diagnose-unreachable-devices
Open

Tell the user why a device is unreachable instead of just 'TimeOut'#501
alecplumb wants to merge 1 commit into
RobHofmann:masterfrom
alecplumb:diagnose-unreachable-devices

Conversation

@alecplumb

@alecplumb alecplumb commented Sep 8, 2026

Copy link
Copy Markdown

You wrote in #405:

Posting this error says nothing. The only valuable thing here would be someone that has this
error actually debugging the issue locally on his side […] someone actually modifies the current
code until it works on his/her device and then creates a Pull Request to this repository with
that working version (while maintaining backwards compatibility with the current situation).

This doesn't make an unsupported device work — nothing can, for the case I hit — but it makes the
error say something, which should take a bite out of the issue volume.

The problem

FetchResult uses an unconnected UDP socket. The kernel discards ICMP errors on those, so
"nothing is listening on port 7000" and "my packets went nowhere" both arrive as TimeoutError.
That one message currently covers most of the causes you listed in #405 — cloud-only modules,
wrong encryption key, wrong IP, firewall — which is exactly why the issues are untriageable from
the outside.

The information is available. A connected UDP socket makes the kernel report ICMP errors
instead of dropping them, so ECONNREFUSED becomes visible and means something precise: the host
is up and actively saying nothing is bound to that port.

The change

After the retries are spent, probe once through a connected socket and report which of three
situations it is:

Result Meaning
refused Reachable, but nothing listening on UDP 7000 — not running the local protocol at all. Cloud-only firmware. Retrying or changing encryption_version cannot help.
responded Port open and answering discovery, so the network is fine — the encrypted exchange is what fails. Points at the device key / encryption_version.
silent Nothing came back: wrong IP, firewall/VLAN, or device offline.

That second case is the one I'd expect to save you the most time — it separates "your network is
broken" from "your key is wrong", which currently look identical.

Backwards compatibility

The request path is untouched. Same socket, same sendto, same recvfrom, same retry count,
same exception raised to the caller. The probe runs only after the final attempt has already
failed, so a working device never reaches it and behaves exactly as before.

I deliberately did not convert the main socket to a connected one. It would be cleaner, and
would let it fail fast instead of burning eight retries on a device that will never answer — but a
connected socket only accepts datagrams from the connected peer, and I can't test that against the
variety of devices in the wild. Happy to do it if you'd prefer.

Verified

Three real cases on my network:

cloud-only unit  (hid U-WB05WR11V2.10, ver V3.2.M)  -> refused
working unit     (hid U-WB05RT11V1.44, ver V3.4.M)  -> responded
unused address                                       -> silent

Incidental data point for #405

You noted "newer Firmware versions have disabled the direct communication". Across the units I can
see, it tracks the WiFi module family rather than the AC:

  • U-WB05**RT**11 / ver V3.4.M — local protocol works
  • U-WB05**WR**11 / ver V3.2.M — port refused, cloud only

That matches #444,
where the failing unit was V3.2.M and the working ones V3.4.M with WB05RT hids. My two units
are the same AC brand and model line, differing only in the module — the older unit works locally,
its warranty replacement does not. Small sample, but hid and ver may be a useful thing to ask
for in issue reports.

README updated so users can self-diagnose before opening an issue.

An unconnected UDP socket cannot distinguish 'nothing is listening' from
'packets went nowhere' -- the kernel discards the ICMP port-unreachable and
FetchResult reports a bare TimeoutError either way. That single message
currently covers causes as different as a cloud-only WiFi module, a wrong
encryption key, and a typo'd IP address, which is a large part of why these
issues are impossible to triage from the outside.

Once the retries are spent, probe the device once through a *connected*
socket, which does surface ICMP errors, and report which of three situations
it is:

  refused   - reachable, but nothing listening on UDP 7000: the unit is not
              running the local protocol at all (cloud-only firmware).
              Retrying or changing encryption_version cannot help.
  responded - port open and answering discovery, so the network is fine and
              the encrypted exchange is what fails: key/encryption_version.
  silent    - nothing came back: wrong IP, firewall/VLAN, or device offline.

The request path itself is untouched -- same socket, same sends, same
retries, same exception raised. The probe only runs on the already-failed
path, so a working device behaves exactly as before.

Verified against three real cases:
  cloud-only unit  (hid U-WB05WR11V2.10, ver V3.2.M)  -> refused
  working unit     (hid U-WB05RT11V1.44, ver V3.4.M)  -> responded
  unused address                                       -> silent

README updated so users can self-diagnose before opening an issue.
@alecplumb
alecplumb force-pushed the diagnose-unreachable-devices branch from 1bd1ccb to acc0c57 Compare September 8, 2026 16:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant