Tell the user why a device is unreachable instead of just 'TimeOut' - #501
Open
alecplumb wants to merge 1 commit into
Open
Tell the user why a device is unreachable instead of just 'TimeOut'#501alecplumb wants to merge 1 commit into
alecplumb wants to merge 1 commit into
Conversation
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
force-pushed
the
diagnose-unreachable-devices
branch
from
September 8, 2026 16:02
1bd1ccb to
acc0c57
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You wrote in #405:
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
FetchResultuses 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
ECONNREFUSEDbecomes visible and means something precise: the hostis 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:
refusedencryption_versioncannot help.respondedencryption_version.silentThat 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, samerecvfrom, 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:
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 worksU-WB05**WR**11/ver V3.2.M— port refused, cloud onlyThat matches #444,
where the failing unit was
V3.2.Mand the working onesV3.4.MwithWB05RThids. My two unitsare 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
hidandvermay be a useful thing to askfor in issue reports.
README updated so users can self-diagnose before opening an issue.