From 675288a329ff9746c0feb67a39b76d93537edcc4 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sat, 16 May 2026 12:01:08 +0200 Subject: [PATCH] docs(migration): add CLI-driven factory-reset alternative MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The web-UI wizard is in-place migration: it preserves the speaker's existing pairing and synced data. The CLI sequence is a different shape — full factory-reset → wifi-push → pair against AfterTouch from scratch — and it's the right tool when you want a clean, scriptable, reproducible setup (automation, batched onboarding, or just starting from a reset speaker). Documents the full 6-step CLI flow (plan / factory-reset / wait-ap / wifi-push / wait-online / setup pair --mode=full), the verification checks, and a side-by-side comparison so users can pick the right path. Placed after "Repeat for each speaker" so the wizard remains the recommended default for one-off migrations. The flow assumes #195 and #269 are fixed in v0.80.2 — without the AUX/sources filter, the CLI factory-reset path produces a speaker where AUX won't dispatch. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guides/MIGRATION-GUIDE.md | 76 ++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/docs/guides/MIGRATION-GUIDE.md b/docs/guides/MIGRATION-GUIDE.md index 96a1b16..676a9dc 100644 --- a/docs/guides/MIGRATION-GUIDE.md +++ b/docs/guides/MIGRATION-GUIDE.md @@ -206,6 +206,82 @@ Each speaker is migrated independently. You can run multiple migrations in paral --- +## Alternative: CLI-driven factory-reset workflow + +If you prefer scripting the migration, or the wizard isn't an option (headless server, automation, batch onboarding of many speakers), `soundtouch-cli` exposes the same building blocks. The flow below is **not** an in-place migration — it factory-resets the speaker and brings it up fresh against AfterTouch, so any data Bose preserved on the device is wiped. Use this when: + +- You're starting from a factory-reset speaker anyway. +- The wizard's in-place migration didn't take and you want a clean slate. +- You're scripting setup for many speakers and want a reproducible recipe. + +### Prerequisites + +- AfterTouch service running and reachable at a stable URL (e.g., `https://soundtouch.local` from your `.env`). +- The speaker reachable on its current IP (passed as `--host`). +- For the AP-mode handover step, your laptop must be able to join the speaker's `Bose SoundTouch` Wi-Fi (you'll switch between home Wi-Fi and the speaker's AP). + +### The full sequence + +```bash +# 1. Plan what the reset+pair pipeline will write (dry run, no changes yet). +soundtouch-cli --host 192.168.1.50 setup plan \ + --reset=true --include-pair=false \ + --service-url='https://soundtouch.local' + +# 2. Trigger the factory reset. The speaker reboots into AP mode. +soundtouch-cli --host 192.168.1.50 setup factory-reset + +# --- Manual step: join the speaker's Wi-Fi AP (SSID "Bose SoundTouch ...") --- + +# 3. Wait for the AP-mode endpoint to answer. +soundtouch-cli setup wait-ap + +# 4. Push your home Wi-Fi credentials to the speaker. +# Run twice if the first attempt's ACK races the AP teardown — the second +# one is a no-op if the first succeeded. +soundtouch-cli setup wifi-push --ssid="YourHomeSSID" --pass='your-wifi-password' + +# --- Manual step: switch your laptop back to the home Wi-Fi network --- + +# 5. Wait for the speaker to come back online on the home network. +# --match takes the last 4-6 hex chars of the speaker's MAC (visible on +# the bottom of the device). +soundtouch-cli setup wait-online --match=42CAFE + +# 6. Pair the speaker with an AfterTouch account. +# --mode=full runs the canonical WebSocket SETUP sequence (matches the +# Bose app's flow); --account is the 7-digit account ID AfterTouch +# should attach the speaker to. +soundtouch-cli --host 192.168.1.50 setup pair \ + --mode=full --account=1111111 \ + --service-url='https://soundtouch.local' +``` + +### Verifying the result + +After pairing completes: + +- The speaker should appear on the **Devices** tab in the web UI. +- AUX should switch and play audio when selected. +- Pressing presets should fetch their content from AfterTouch (the `[LOG]` rows on the service confirm). +- TuneIn search and playback should work end-to-end. + +If any of these fail post-pair, see [Troubleshooting](TROUBLESHOOTING.md) — most commonly the speaker just needs a power cycle to pick up everything cleanly. + +### Differences vs the wizard + +| Aspect | Wizard (in-place migration) | CLI factory-reset workflow | +|-------------------------------------|---------------------------------------------------------|---------------------------------------------------------| +| Preserves speaker's existing state | yes (Presets, recents, attached account) | **no** — wipes everything | +| Requires Wi-Fi-network switching | no | yes (laptop joins speaker AP, then home network) | +| Scriptable / reproducible | clickable, not scriptable | full bash recipe | +| Cloud-side data (Bose Marge backup) | preserved if Sync ran while cloud was alive | not relevant — fresh account on AfterTouch | +| Best for | "I want this speaker to keep working with what's on it" | "I want a clean, reproducible setup against AfterTouch" | + +The wizard is still the recommended path for a one-off migration of an existing setup. The CLI workflow is the right choice when you're scripting, batching, or already starting from a reset. + +--- + ## Rollback If you need to undo a migration: