From ae9b02a42b01cf417f34054aec3a5953dc256257 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Mon, 11 May 2026 00:19:00 +0200 Subject: [PATCH] docs(service): API reference for the *_url option family + telnet-probe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The /setup/migrate/{deviceIP} reference table covered only the legacy self/proxied/original mode selectors, with a one-line "Custom service URL" mention of target_url. The wizard has been writing literal per-field URLs via marge_url / stats_url / sw_update_url / bmx_url for weeks; external API callers had nothing to read. Expanded the table into three blocks with precedence rules: 1. Top-level params — method, target_url, proxy_url with the four migration mechanisms (xml / telnet / resolv, hosts marked deprecated). 2. Per-field implementation mode — the legacy self/proxied/original family, kept for API back-compat with a note that the UI no longer sets them. 3. Per-field literal URL overrides — marge_url / stats_url / sw_update_url / bmx_url with a "literal wins over mode" rule and the soundcork-suffix-propagates-to-envswitch note. Three example curl invocations (canonical XML, soundcork telnet, resolv with HTTPS) replace the old proxy=original-only snippet up top. Also added stub reference entries for POST /setup/telnet-probe and the internal GET /probe/{token}[/*] catch-all — the SSH-less reachability check the wizard runs automatically in its pre-flight panel. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guides/SOUNDTOUCH-SERVICE.md | 87 +++++++++++++++++++++++++++---- 1 file changed, 78 insertions(+), 9 deletions(-) diff --git a/docs/guides/SOUNDTOUCH-SERVICE.md b/docs/guides/SOUNDTOUCH-SERVICE.md index e98bda0..f96351b 100644 --- a/docs/guides/SOUNDTOUCH-SERVICE.md +++ b/docs/guides/SOUNDTOUCH-SERVICE.md @@ -225,13 +225,21 @@ curl http://localhost:8000/setup/devices #### Advanced Migration Options ```bash -# Migration with proxy fallback for original services -curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?proxy_url=http://localhost:8000&marge=original&stats=original" - # Migration with custom target URL curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?target_url=https://my-server.com:8000" + +# Per-field literal URL overrides (preferred — used by the web wizard) +curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=xml&target_url=http://server:8000&marge_url=http://server:8000/marge" + +# SSH-less migration over the device's port-17000 diagnostic shell +curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=telnet&target_url=http://server:8000" + +# Legacy proxy-fallback for selected fields (kept for API back-compat) +curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?proxy_url=http://localhost:8000&marge=original&stats=original" ``` +See the full parameter reference at `POST /setup/migrate/{deviceIP}` below for `method`, `target_url`, `*_url`, and the legacy mode selectors. + ### Post-Migration Verification After migration, verify the device is working correctly: @@ -393,12 +401,73 @@ Analyzes device configuration and provides migration preview. Migrates device to use local services. **Query Parameters:** -- `target_url`: Custom service URL (optional) -- `proxy_url`: Proxy URL for fallback (optional) -- `marge`: Set to "original" to proxy Marge requests (optional) -- `stats`: Set to "original" to proxy stats requests (optional) -- `sw_update`: Set to "original" to proxy update requests (optional) -- `bmx`: Set to "original" to proxy BMX requests (optional) + +| Parameter | Values | Notes | +|--------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `method` | `xml` (default), `telnet`, `resolv`, `hosts` (deprecated) | Picks the redirect mechanism. `xml` writes `SoundTouchSdkPrivateCfg.xml` via SSH; `telnet` flips the four URLs via the device's port-17000 diagnostic shell; `resolv` installs the `/etc/resolv.conf` priority-nameserver hook and the local CA via SSH. | +| `target_url` | Any URL, e.g. `http://soundtouch.local:8000` | Service base URL the per-field defaults derive from. Falls back to the service's configured `ServerURL` when omitted. | +| `proxy_url` | Any URL | Proxy base used when the legacy `marge=proxied` / `stats=proxied` / `sw_update=proxied` / `bmx=proxied` modes are set. Defaults to `target_url`. | + +**Per-field implementation mode** (XML method's legacy semantics — kept for API back-compat, UI no longer sets them): + +| Parameter | Values | Effect on the matching `*ServerUrl` / `*RegistryUrl` field | +|-------------|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `marge` | `self` (default), `proxied`, `original` | `self`: write `target_url` (canonical). `proxied`: write `/proxy/`. `original`: keep the speaker's existing value. | +| `stats` | same | same | +| `sw_update` | same | same | +| `bmx` | same | same | + +**Per-field literal URL overrides** (preferred — used by the wizard's Plan card; honored for both `xml` and `telnet` methods): + +| Parameter | Effect | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `marge_url` | Writes the exact URL to `` regardless of `target_url` derivation or `marge` mode. Empty / missing → fall back to canonical default from `target_url`. | +| `stats_url` | Same shape for ``. | +| `sw_update_url` | Same for ``. | +| `bmx_url` | Same for ``. | + +**Precedence**: `*_url` overrides win over the `marge / stats / sw_update / bmx` mode selectors. The setup package applies `applyProxyOptions` first, then `applyURLOverrides` clobbers any field where a literal `*_url` was supplied. So if you send both `marge=proxied&marge_url=http://x:8000/marge`, the literal `http://x:8000/marge` is written. + +**Soundcork redirect**: append `/marge` to `marge_url`. The telnet method derives `envswitch boseurls set ` from the final URLs verbatim, so the suffix propagates to the parallel persistence layer automatically — no separate flag needed. + +**Examples**: + +```bash +# Canonical XML migration over SSH to the default service URL +curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=xml" + +# Telnet migration with the soundcork redirect (only marge gets the /marge suffix) +curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=telnet&target_url=http://soundcork.local:8000&marge_url=http://soundcork.local:8000/marge" + +# DNS interception (writes /etc/resolv.conf hook + installs CA) — *_url overrides are ignored +curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=resolv&target_url=https://my-server.com:8443" +``` + +#### `POST /setup/telnet-probe/{deviceIP}` +SSH-less reachability check. Temporarily flips the speaker's `swUpdateUrl` via the port-17000 diagnostic shell, triggers `:8090/swUpdateCheck` on the device, and observes whether the resulting outbound lands on this service's `/probe/{token}` handler within 6 s. Always attempts to restore the original `swUpdateUrl` even on failure. + +**Query Parameters:** +- `target_url` (optional): defaults to the service's configured `ServerURL`. The probe URL written to the device is `/probe/`. + +**Response:** +```json +{ + "ok": true, + "result": { + "reached": true, + "restored": true, + "original_url": "https://worldwide.bose.com/updates/soundtouch", + "probe_url": "http://soundtouch.local:8000/probe/abc123…", + "elapsed_ms": 412, + "logs": "…" + } +} +``` + +`reached=true` means the device's outbound landed on our `/probe/{token}` route within the timeout. `restored=true` means the runtime `swUpdateUrl` was reverted to its captured original (the envswitch persistence layer is left untouched throughout, so a reboot heals the device naturally if our restore step fails). + +#### `GET /probe/{token}[/*]` +Catch-all endpoint that signals the matching pre-flight probe channel. Used internally by `/setup/telnet-probe/{deviceIP}`; not intended to be called directly by API consumers. Returns a minimal `` XML so the device's `swUpdateCheck` doesn't choke on a missing structure. ### BMX Services (Bose Media eXchange)