From b7a2a7bdb10506b0efb8b043f2eb39c1255d2ca1 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sun, 9 Aug 2026 20:34:22 +0200 Subject: [PATCH] docs(telnet): document per-port reboot readiness for enable-ssh retries Confirmed on hardware (#471 comments 5231997551, 5232046477): after a reboot, HTTP :8090 and the diagnostic telnet :17000 shell become ready at very different times, up to ~92s. Our own enable-ssh retry guidance tells users to power-cycle and re-run immediately, which can hit the device mid-boot and surface as a raw connection-refused error. Adds a troubleshooting entry plus the underlying measurement in TELNET-COMMAND-REFERENCE.md; no code change. Co-Authored-By: Claude Sonnet 5 --- .../docs/analysis/TELNET-COMMAND-REFERENCE.md | 2 ++ docs/content/docs/guides/TROUBLESHOOTING.md | 14 ++++++++++++++ 2 files changed, 16 insertions(+) diff --git a/docs/content/docs/analysis/TELNET-COMMAND-REFERENCE.md b/docs/content/docs/analysis/TELNET-COMMAND-REFERENCE.md index 08bf5e1..0f596a5 100644 --- a/docs/content/docs/analysis/TELNET-COMMAND-REFERENCE.md +++ b/docs/content/docs/analysis/TELNET-COMMAND-REFERENCE.md @@ -307,6 +307,8 @@ sys reboot **Factory reset does not remove root access, if it was ever persisted.** Confirmed on a genuinely factory-reset `spotty` ([#471 comment 5232232575](https://github.com/gesellix/Bose-SoundTouch/issues/471#issuecomment-5232232575)): after the reset, `margeAccountUUID` was empty, all four service URLs were back to `streaming.bose.com`, and presets were gone — but `/etc/remote_services` and `/mnt/nv/remote_services` **survived**, and SSH (:22) and telnet (:17000) stayed open. So once a device has been through `setup enable-ssh` with persistence (`EnsureRemoteServices`, the default), a later factory reset only wipes configuration, not root access — recovery is re-migrate + re-pair + rename + restore presets, with **no USB stick and no re-running the injection**. +**Readiness after a reboot is per-port, not a single moment.** `JRpersonal` first measured that the firmware needs roughly 60s after a cold boot before `:8090`'s `/info` answers and marge state is ready — a booting device answers a bare `HTTP 400` with an empty body before its services are up, which is easy to misread as a rejection rather than "too early" ([#471 comment 5231997551](https://github.com/gesellix/Bose-SoundTouch/issues/471#issuecomment-5231997551)). `bitranox` refined this across three variants: `:8090` and the diagnostic `:17000` shell (and the config subsystem behind it that `getpdo` reads) do **not** become ready at the same time — waiting for `:8090` and then immediately reading over `:17000` returned an empty response even though the box was otherwise up. Ten observed reboots: down in 2.3–5.3s, ready (able to answer `getpdo` correctly) in 55.1–91.8s, median ~69.8s ([#471 comment 5232046477](https://github.com/gesellix/Bose-SoundTouch/issues/471#issuecomment-5232046477)). Anything automated should wait for the specific interface it's about to use, not for a different port to answer first — see the troubleshooting guide's [power-cycle retry note](../guides/TROUBLESHOOTING.md) for the user-facing version of this. + --- ## Out of scope here, but worth recording diff --git a/docs/content/docs/guides/TROUBLESHOOTING.md b/docs/content/docs/guides/TROUBLESHOOTING.md index 23184d8..cf9450f 100644 --- a/docs/content/docs/guides/TROUBLESHOOTING.md +++ b/docs/content/docs/guides/TROUBLESHOOTING.md @@ -634,6 +634,20 @@ If the telnet method isn't available for your model, factory reset the speaker, After this the radio sources activate normally. Note the factory reset rewrites the speaker's `Sources.xml` to defaults, so any **account-bound** source (for example a music-streaming login) has to be re-added afterwards; your presets for it come back once the source is present again. +### ❌ `setup enable-ssh` (or a telnet command) fails right after a power-cycle, but works if you wait + +**Symptoms:** + +- You power-cycled the speaker — as our own retry guidance suggests after a `setup enable-ssh` timeout — and immediately re-ran the command (or a telnet migration/pairing step). +- You get `telnet dial :17000: connection refused` or the command otherwise fails as if the port were closed. +- Running the exact same command again a minute or two later works fine, on the same device. + +**Cause:** + +Confirmed on hardware across five device variants (2026-08-09): different ports on the same speaker become ready at very different times after a cold boot. HTTP `:8090` typically answers first, but the diagnostic telnet shell on `:17000` — and the config subsystem behind it that `getpdo` reads — takes longer: 55–92 seconds observed, median ~70s. "The box answers on one port" is a weaker signal than "the box can answer on the specific port you need." See [TELNET-COMMAND-REFERENCE.md](../analysis/TELNET-COMMAND-REFERENCE.md) for the underlying mechanism. + +**Fix:** After a power-cycle, wait at least 90 seconds before retrying any telnet-based command. If it still fails after that, wait a full 2 minutes before assuming the port is genuinely closed on that firmware rather than just slow to come up. + ## 🔊 **Volume & Audio Issues** ### ❌ "Volume control not working"