diff --git a/README.md b/README.md index 5188d58..5325ad2 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ See the [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVI A local server that replaces the Bose cloud ("AfterTouch"). Once your speaker is redirected to it, you have full control without any Bose cloud dependency. The built-in web UI at `http://localhost:8000` handles all setup — no config files needed to get started. -If you don't want to run a server for this - no problem. The service is small enough to run on the SoundTouch itself. See the [On-Device Installer](./scripts/on-device-install/README.md) for instructions. +Not sure which approach fits your situation? See the [Deployment Overview](./docs/guides/DEPLOYMENT-OVERVIEW.md) — it compares running AfterTouch on a Raspberry Pi or other always-on host against running it directly on the SoundTouch speaker, with links to step-by-step walkthroughs for each path. **Two scenarios:** diff --git a/docs/DEVICE-LOCAL-INSTALL.md b/docs/architecture/DEVICE-LOCAL-INSTALL.md similarity index 98% rename from docs/DEVICE-LOCAL-INSTALL.md rename to docs/architecture/DEVICE-LOCAL-INSTALL.md index 99ba475..35b526f 100644 --- a/docs/DEVICE-LOCAL-INSTALL.md +++ b/docs/architecture/DEVICE-LOCAL-INSTALL.md @@ -1,5 +1,15 @@ # Device-Local Install: Four User Journeys +> **Looking for how to actually install AfterTouch?** +> See the [Deployment Overview](../guides/DEPLOYMENT-OVERVIEW.md) for user-friendly +> step-by-step guides for both deployment scenarios (external host and on-device). +> +> This document is an **architectural analysis** — user journeys, install patterns, +> technology tradeoffs, and future directions. It is aimed at contributors and +> project planning, not at end users. + +--- + A user-journey-shaped view of where AfterTouch sits today and where it could go. The same speaker, the same constraints, but four different audiences with non-overlapping needs: 1. **Initial setup / install** — getting AfterTouch onto a fresh or freshly-orphaned speaker. diff --git a/docs/guides/DEPLOYMENT-OVERVIEW.md b/docs/guides/DEPLOYMENT-OVERVIEW.md new file mode 100644 index 0000000..037253d --- /dev/null +++ b/docs/guides/DEPLOYMENT-OVERVIEW.md @@ -0,0 +1,66 @@ +# AfterTouch Deployment Overview + +AfterTouch replaces the Bose SoundTouch cloud, which shut down on 2026-05-06. There are two +ways to run it — pick the one that fits your situation. + +--- + +## Which deployment is right for me? + +| | External host | On-device | +|--|---------------|-----------| +| **What it means** | AfterTouch runs on a separate computer (Raspberry Pi, NAS, PC) on your LAN. Speakers are pointed at that host. | AfterTouch runs directly on the SoundTouch speaker itself. No extra hardware. | +| **Extra hardware needed** | Yes — a Raspberry Pi or any always-on machine | No | +| **Multiple speakers** | Easy — one instance serves all speakers on the LAN | Each speaker needs its own install | +| **Invasiveness** | Low — only the speaker's server-URL config changes | Slightly higher — writes to the speaker's persistent storage | +| **Updates** | Update the host; speakers pick it up automatically | SSH into each speaker to update | +| **Good for** | Households with several speakers; users who want a central dashboard | Single-speaker households; users who don't have an always-on computer | + +--- + +## Option A — External host (Raspberry Pi, NAS, PC) + +The speaker stays unmodified. You run AfterTouch on a machine you already have +on your home network, then tell the speaker to use it instead of the Bose cloud. + +| | Link | +|--|------| +| **User-friendly walkthrough** | [External Host Walkthrough](EXTERNAL-HOST-WALKTHROUGH.md) — step-by-step from install through preset setup | +| **Raspberry Pi quick-install** | [Raspberry Pi Guide](RASPBERRY-PI.md) — one-command installer, systemd integration | +| **Technical reference** | [Deployment Guide](DEPLOYMENT.md) — Docker, Kubernetes, systemd unit, configuration | + +--- + +## Option B — On-device (AfterTouch on the speaker) + +AfterTouch runs on the SoundTouch speaker itself. Requires one SSH session to +install; after that, the speaker self-hosts its own AfterTouch. + +| | Link | +|--|------| +| **User-friendly walkthrough** | [On-Device Install Walkthrough](ON-DEVICE-INSTALL-WALKTHROUGH.md) — SSH connection through verified radio preset playback | +| **Installer reference** | [On-Device Installer README](../../scripts/on-device-install/README.md) — flags, paths, VERSION override, update/rollback | + +--- + +## After choosing a deployment path + +Once AfterTouch is running and your speaker is migrated, the next steps are the +same regardless of which deployment you chose: + +- **Health tab** — open the AfterTouch UI → Health, and run any QuickFixes shown + (especially *"empty margeAccountUUID"* if present). +- **Music sources** — the Health tab also shows whether Internet Radio, TuneIn, + and Radio Browser are active. +- **Presets** — use the AfterTouch web UI or `soundtouch-cli preset store-current` + to program the physical preset buttons. + +For troubleshooting either deployment see [TROUBLESHOOTING.md](TROUBLESHOOTING.md). + +--- + +## Architecture and planning documents + +If you're a contributor or interested in the technical design decisions +(install patterns, user journeys, Gio/Wails tradeoffs, mini-build discussion), +see [docs/architecture/DEVICE-LOCAL-INSTALL.md](../architecture/DEVICE-LOCAL-INSTALL.md). diff --git a/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md b/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md new file mode 100644 index 0000000..5fdb306 --- /dev/null +++ b/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md @@ -0,0 +1,245 @@ +# External Host Walkthrough + +A step-by-step guide to running AfterTouch on a Raspberry Pi (or any always-on +computer) and migrating your Bose SoundTouch speakers to use it. + +By the end you'll have AfterTouch running on your host, your speaker(s) pointed +at it, and your radio presets working again. + +For a comparison with the on-device install option see +[DEPLOYMENT-OVERVIEW.md](DEPLOYMENT-OVERVIEW.md). + +--- + +## What you need + +- A **Raspberry Pi** (Zero 2W, 3, or 4), a NAS, or any always-on Linux/macOS/Windows + machine on your home network. +- Your **Bose SoundTouch speaker** on the same network. It doesn't need SSH enabled. +- A **browser** on any device on the same network. +- The **speaker's LAN IP address** — find it in your router's device list, or run + `arp -a` on your computer. Replace `192.0.2.1` throughout with the real IP. + +--- + +## Step 1 — Install AfterTouch on your host + +### Raspberry Pi (recommended for always-on use) + +```bash +curl -fsSL -o install.sh \ + https://raw.githubusercontent.com/gesellix/bose-soundtouch/main/scripts/raspberry-pi/install.sh +sudo bash install.sh +``` + +The installer detects your Pi's architecture (armv7, arm64, or amd64), downloads +the binary, creates a `soundtouch` system user, and registers a systemd unit that +starts on boot. + +To install a specific version: + +```bash +sudo bash install.sh v0.92.0 +``` + +Check that the service is running: + +```bash +systemctl status soundtouch-service +``` + +The Admin UI is now at **`http://:8000`** — open it in a browser. + +### Other Linux hosts (systemd) + +Download the binary for your architecture from the +[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases), then +install it as a systemd service — see [DEPLOYMENT.md](DEPLOYMENT.md) for the +unit file template. + +### Docker + +```bash +docker run -d \ + --name aftertouch \ + --network host \ + -e SERVER_URL=http://192.0.2.10:8000 \ + -v aftertouch-data:/data \ + ghcr.io/gesellix/bose-soundtouch:latest +``` + +Replace `192.0.2.10` with the host machine's LAN IP. The `--network host` flag +is required so AfterTouch can reach the speakers and respond to mDNS discovery. + +--- + +## Step 2 — Note your host's LAN IP and open the Admin UI + +Your host's LAN IP is the address your speakers will use to reach AfterTouch. +Find it with: + +```bash +# Linux / macOS +ip addr show # or: hostname -I +# Windows +ipconfig +``` + +Open **`http://:8000`** in a browser. You should see the AfterTouch +Admin UI. If it's not reachable, check that port 8000 is not blocked by a +firewall on the host. + +--- + +## Step 3 — Discover your speaker + +In the Admin UI: + +1. Go to the **Devices** tab. AfterTouch runs mDNS discovery automatically — + your speaker should appear within a minute or two. +2. If it doesn't appear, click **Trigger Discovery**. If it still doesn't appear, + add it manually: enter `192.0.2.1` (your speaker's IP) and click **Add**. + +You should now see your speaker listed with its name and model. + +--- + +## Step 4 — Migrate the speaker + +This step tells the speaker to use your AfterTouch instance instead of the +defunct Bose cloud. **The speaker gets a new server URL written to it; this is +reversible via the "Revert" button.** + +1. Click your speaker in the Devices list. +2. Click **Migrate** (or open the Migration wizard from the speaker's detail page). +3. The wizard shows a summary of what will change. Review it and click **Confirm**. +4. AfterTouch rewrites the speaker's server-URL config and reboots it. +5. Wait 2–3 minutes for the speaker to come back up. + +After the reboot the speaker reconnects to AfterTouch. You should see its status +turn green in the Devices tab. + +> **If the migration wizard asks for your AfterTouch URL**, enter +> `http://:8000` (the same URL you used to open the Admin UI). + +--- + +## Step 5 — Check the Health tab and run QuickFixes + +1. Click your speaker in the Devices list, then open the **Health** tab. +2. Click **Run health checks** (or wait for them to run automatically). +3. Look for any warnings. The most common after a fresh migration: + + | Warning | QuickFix action | + |---------|----------------| + | *Speaker reports an empty ``* | Click **Pair account** / **Apply QuickFix** and confirm. The speaker will reboot. | + | *INTERNET_RADIO source is a stale stub* | Click **Remove INTERNET_RADIO source**. | + | *TuneIn / Radio Browser missing from sources* | These appear automatically once the speaker has paired; if still missing after a QuickFix reboot, trigger discovery again. | + +4. After any QuickFix that reboots the speaker, re-run the health checks to + confirm the warning is gone. + +--- + +## Step 6 — Verify pairing and sources + +After the health checks are green, confirm from your browser: + +- In the **Devices** tab, click the speaker. Its **Account** field should show + a non-empty UUID, not `default`. +- In the **Sources** tab (if present), or via the health checks, confirm + `LOCAL_INTERNET_RADIO`, `TUNEIN`, and `RADIO_BROWSER` are listed. + +You can also check directly from any machine on the LAN: + +```bash +# Replace 192.0.2.1 with your speaker's IP +curl -s http://192.0.2.1:8090/info | grep -i marge +curl -s http://192.0.2.1:8090/sources +``` + +`margeAccountUUID` must not be empty. Sources should include +`LOCAL_INTERNET_RADIO`, `TUNEIN`, and `RADIO_BROWSER`. + +--- + +## Step 7 — Set up preset buttons (optional) + +### Via the AfterTouch web UI + +1. Open **`http://:8000`** and navigate to your speaker. +2. Use the **Radio Browser** or **TuneIn** tab to find a station. +3. Click the station to play it. +4. Click **Store as preset → slot 1** (or whichever slot you want). +5. Repeat for slots 2–6. + +### Via soundtouch-cli (any machine on the LAN) + +Download the CLI for your machine from the +[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases), then: + +```bash +# Play a custom radio stream on the speaker +soundtouch-cli --host 192.0.2.1 source custom-radio \ + --url "https://stream.laut.fm/country-nonstop" \ + --name "Country Nonstop" \ + --service-url "http://:8000" +sleep 5 + +# Store it to preset slot 1 +soundtouch-cli --host 192.0.2.1 preset store-current --slot 1 +``` + +Repeat for each slot. See the +[On-Device Install Walkthrough](ON-DEVICE-INSTALL-WALKTHROUGH.md#step-9--store-custom-radio-streams-to-preset-buttons) +for six worked examples with Austrian internet radio stations. + +--- + +## Step 8 — Verify and enjoy + +Press a preset button on the speaker briefly (a long press overwrites the preset). +Each slot should play the corresponding stream. + +To check what's stored: + +```bash +curl -s http://192.0.2.1:8090/presets +``` + +--- + +## Updating AfterTouch + +### Raspberry Pi + +```bash +sudo bash install.sh # updates to latest release +sudo bash install.sh v0.93.0 # updates to a specific version +``` + +The installer stops the service, downloads the new binary, and restarts +automatically. + +### Checking current version + +```bash +systemctl status soundtouch-service # shows the running version in the log +curl -s http://:8000/health | grep version +``` + +--- + +## Troubleshooting + +| Symptom | First check | +|---------|------------| +| Speaker not appearing in Devices | Click **Trigger Discovery**; try adding the IP manually | +| Migration fails | Confirm the speaker can reach `http://:8000` — try `curl http://:8000` from the speaker's SSH shell | +| `margeAccountUUID` still empty after QuickFix + reboot | Re-run Health QuickFix, reboot again | +| Radio source error 1005 | `margeAccountUUID` is empty — complete Step 5 first | +| Speaker reverts to Bose cloud after router restart | Your router's DNS is overriding AfterTouch's server URL — see [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md) for DNS-interception setup | +| Admin UI not reachable | Check `systemctl status soundtouch-service` and firewall rules for port 8000 | + +For more detail see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) and +[MIGRATION-GUIDE.md](MIGRATION-GUIDE.md). diff --git a/docs/guides/RASPBERRY-PI.md b/docs/guides/RASPBERRY-PI.md index a633083..cbdb606 100644 --- a/docs/guides/RASPBERRY-PI.md +++ b/docs/guides/RASPBERRY-PI.md @@ -2,6 +2,11 @@ This guide explains how to install the `soundtouch-service` as a persistent systemd service on a Raspberry Pi (tested on Raspberry Pi Zero 2W, 3, and 4). +For a complete walkthrough — from install through speaker migration and preset setup — see +[EXTERNAL-HOST-WALKTHROUGH.md](EXTERNAL-HOST-WALKTHROUGH.md). +Not sure whether to use a Pi or run AfterTouch on the speaker itself? See +[DEPLOYMENT-OVERVIEW.md](DEPLOYMENT-OVERVIEW.md). + ## Automated Installer We provide a specialized installer script located in the `scripts/raspberry-pi/` directory of the repository. @@ -30,7 +35,7 @@ You can customize the installation using environment variables: ```bash sudo \ - VERSION=v0.17.0 \ + VERSION=v0.92.0 \ HOSTNAME_FQDN=soundtouch.local \ HTTP_PORT=80 \ HTTPS_PORT=443 \ @@ -42,7 +47,7 @@ sudo \ To update the service to a specific version, run the installer with the version as an argument: ```bash -sudo bash install.sh v0.18.1 +sudo bash install.sh v0.92.0 ``` The installer will automatically fetch the latest version of itself for that release and then update the service binary and restart it.