On-Device Install Walkthrough

A complete end-to-end runbook for installing AfterTouch directly on a Bose SoundTouch speaker — from first SSH connection through verified radio preset playback.

Credit: This guide is based on a step-by-step walkthrough contributed by weissigera in issue #329, documenting a successful fresh installation on a SoundTouch 20 Series I.

For the installer reference and troubleshooting tips see scripts/on-device-install/README.md.

Prerequisites

• SSH enabled on the speaker (the usual “Stick with remote_services” procedure).
• Your machine can reach the speaker on the LAN.
• The speaker’s LAN IP address — replace 192.0.2.1 throughout with the actual address shown in your router or arp -a.

Note on SSH host-key negotiation: SoundTouch speakers only advertise legacy host-key algorithms (ssh-rsa, ssh-dss). Modern OpenSSH clients reject these by default. The -oHostKeyAlgorithms=+ssh-rsa flag below opts them back in. Without it you’ll see no matching host key type found.

Step 1 — Connect to the speaker via SSH

ssh -oHostKeyAlgorithms=+ssh-rsa root@192.0.2.1

You should see a prompt such as root@soundtouch-device:~#.

Step 2 — Check free space (and clean up if needed)

The persistent /mnt/nv partition typically has 20–40 MB free — enough for the AfterTouch binary (~12 MB) plus one backup. Check first:

rw            # remount rootfs read-write
df -h /mnt/nv

If you have an older installation with multiple backup or artefact files left behind by earlier upgrades, remove them:

# List what's there
ls -lh /mnt/nv/aftertouch/

# Remove specific stale files (adjust version numbers to what you see)
rm -f /mnt/nv/aftertouch/aftertouch-service.v0.80.1.backup
rm -f /mnt/nv/aftertouch/aftertouch-service.v0.86.0.backup
rm -f /mnt/nv/aftertouch/aftertouch-service.v0.86.0.old
rm -f /mnt/nv/aftertouch/aftertouch-service.new
rm -f /mnt/nv/soundtouch-cli        # cli binary if left there by hand
rm -f /mnt/nv/aftertouch/soundtouch-cli

df -h /mnt/nv   # confirm space recovered

From v0.89.0 onwards the installer prunes stale artefacts automatically during every upgrade — manual cleanup should no longer be necessary on fresh installs.

Step 3 — Install (or upgrade) AfterTouch

Run the canonical one-liner. It downloads the binary and init script, creates /mnt/nv/aftertouch/, symlinks /opt/aftertouch, backs up the currently running binary, and starts the service:

rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh

To target a specific version instead of the default:

# Via environment variable (works with pipe-to-sh)
VERSION=0.92.0 rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh

# Via command-line flag (pass args after sh -s --)
curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh -s -- --version 0.92.0

Verify the installed version:

wget -qO- http://localhost:8000/health

The JSON response should include "version":"v0.93.1" (or whichever version you installed).

Step 4 — Reboot the speaker

sync
reboot

Wait 2–3 minutes for the speaker to come back up, then reconnect:

ssh -oHostKeyAlgorithms=+ssh-rsa root@192.0.2.1

Step 5 — Open an SSH tunnel and access the Admin UI

Open a new terminal on your machine (not inside the speaker’s SSH session — see issue #250 for the port-forward-from-inside trap) and run:

ssh -oHostKeyAlgorithms=+ssh-rsa -L 8000:localhost:8000 root@192.0.2.1

Keep this terminal open. Navigate to http://localhost:8000 in your browser.

Skip this step if your speaker’s firmware exposes port 8000 on the LAN directly — you can reach http://192.0.2.1:8000 without a tunnel in that case.

Step 6 — Run the Health QuickFix for empty margeAccountUUID

In the AfterTouch UI:

1. Open the Health tab.
2. Run or refresh the health checks.
3. Look for the warning:

   Speaker reports an empty <margeAccountUUID>

4. Click the QuickFix button (labelled “Fix”, “Pair account”, or “Apply QuickFix” depending on the version) and confirm.

Then reboot again to let the pairing take effect:

sync
reboot

Step 7 — Verify pairing and sources

After the reboot reconnect via SSH and check:

ssh -oHostKeyAlgorithms=+ssh-rsa root@192.0.2.1

# margeAccountUUID must NOT be empty after the QuickFix
wget -qO- http://localhost:8090/info | grep margeAccountUUID

# Sources must include LOCAL_INTERNET_RADIO, TUNEIN, and RADIO_BROWSER
wget -qO- http://localhost:8090/sources

If margeAccountUUID is still empty, re-run the Health QuickFix (Step 6) and reboot again.

Step 8 — Download soundtouch-cli (optional, for preset setup)

If you want to program preset buttons from the command line, download the CLI binary to the speaker’s /tmp (tmpfs, so it survives only until the next reboot — which is fine for a one-time setup run):

cd /tmp

curl -L --fail -o soundtouch-cli \
  https://github.com/gesellix/Bose-SoundTouch/releases/download/v0.93.1/soundtouch-cli-v0.93.1-linux-armv7
chmod +x soundtouch-cli

/tmp/soundtouch-cli --version

Replace v0.93.1 with the version you installed.

Step 9 — Store custom radio streams to preset buttons

Each station must be playing before it can be saved. The sleep 5 gives the speaker time to buffer and confirm the stream before storing.

Press preset buttons briefly. A long press on the physical hardware overwrites the stored preset.

# Preset 1 — Hitradio OE3
/tmp/soundtouch-cli --host 127.0.0.1 source custom-radio \
  --url "http://orf-live.ors-shoutcast.at/oe3-q2a" \
  --name "Hitradio OE3" \
  --service-url "http://localhost:8000"
sleep 5
/tmp/soundtouch-cli --host 127.0.0.1 preset store-current --slot 1

# Preset 2 — Lounge FM
/tmp/soundtouch-cli --host 127.0.0.1 source custom-radio \
  --url "http://188.138.9.183/digital.mp3" \
  --name "Lounge FM" \
  --service-url "http://localhost:8000"
sleep 5
/tmp/soundtouch-cli --host 127.0.0.1 preset store-current --slot 2

# Preset 3 — Country Nonstop
/tmp/soundtouch-cli --host 127.0.0.1 source custom-radio \
  --url "https://stream.laut.fm/country-nonstop" \
  --name "Country Nonstop" \
  --service-url "http://localhost:8000"
sleep 5
/tmp/soundtouch-cli --host 127.0.0.1 preset store-current --slot 3

# Preset 4 — Radio Piterpan
/tmp/soundtouch-cli --host 127.0.0.1 source custom-radio \
  --url "https://klasse1.fluidstream.eu/piterpan.mp3?FLID=8" \
  --name "Radio Piterpan" \
  --service-url "http://localhost:8000"
sleep 5
/tmp/soundtouch-cli --host 127.0.0.1 preset store-current --slot 4

# Preset 5 — kronehit
/tmp/soundtouch-cli --host 127.0.0.1 source custom-radio \
  --url "https://secureonair.krone.at/kronehit-hp.mp3" \
  --name "kronehit" \
  --service-url "http://localhost:8000"
sleep 5
/tmp/soundtouch-cli --host 127.0.0.1 preset store-current --slot 5

# Preset 6 — Radio Niederösterreich
/tmp/soundtouch-cli --host 127.0.0.1 source custom-radio \
  --url "http://orf-live.ors-shoutcast.at/noe-q2a" \
  --name "Radio Niederoesterreich" \
  --service-url "http://localhost:8000"
sleep 5
/tmp/soundtouch-cli --host 127.0.0.1 preset store-current --slot 6

These are the stations from weissigera’s setup (Austrian public and internet radio). Replace any or all of them with your own streams — the pattern is the same regardless of station.

Step 10 — Verify presets and final reboot

wget -qO- http://localhost:8090/presets

You should see all six preset slots populated. Then do a final reboot and test the physical buttons:

sync
reboot

After the speaker comes back up, press preset buttons 1–6 briefly — each should start playing the corresponding stream.

Troubleshooting

For more detail on any of these, see TROUBLESHOOTING.md and the on-device installer README.