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.

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.103.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.103.0

Verify the installed version:

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

The JSON response should include "version":"v0.103.0" (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:

Open the Health tab.
Run or refresh the health checks.
Look for the warning:
Speaker reports an empty <margeAccountUUID>
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.103.0/soundtouch-cli-v0.103.0-linux-armv7
chmod +x soundtouch-cli

/tmp/soundtouch-cli --version

Replace v0.103.0 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

Symptom	First check
SSH “no matching host key type”	Add `-oHostKeyAlgorithms=+ssh-rsa`
Port 8000 not reachable from LAN	Use the SSH tunnel (Step 5)
`margeAccountUUID` still empty after reboot	Re-run Health QuickFix, reboot again
Radio source error 1005	`margeAccountUUID` is empty — complete Step 6 first
`http://localhost:8000` not responding after install	`logread \| grep aftertouch \| tail -20`
No space left on device during install	Run the cleanup in Step 2; check `df -h /mnt/nv`

For more detail see TROUBLESHOOTING.md.

Updating AfterTouch

Re-run the installer with the version you want. The script backs up the running binary (named after its version), installs the new one, and prunes older artefacts to keep /mnt/nv free:

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

# Update to a specific version — three equivalent forms
VERSION=0.103.0 rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh

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

curl -sSLo install.sh https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh
sh install.sh --version 0.103.0

Rollback: the installer keeps a .backup file alongside the binary:

ls /mnt/nv/aftertouch/aftertouch-service*.backup
cp /mnt/nv/aftertouch/aftertouch-service.<old-version>.backup \
   /mnt/nv/aftertouch/aftertouch-service
/etc/init.d/aftertouch restart

Service management

/etc/init.d/aftertouch start
/etc/init.d/aftertouch stop
/etc/init.d/aftertouch restart
/etc/init.d/aftertouch status   # distinguishes "running + listener up" from "PID alive but listener down"

Logs

The daemon writes to BusyBox syslog (tagged aftertouch). Disk usage stays bounded — the syslog ring buffer is in memory:

logread        | grep aftertouch | tail -20   # recent entries
logread -f     | grep aftertouch              # live tail

If the service is running but port 8000 isn’t responding, check the syslog tail first — panics and startup errors appear there.

Uninstalling

Before uninstalling, consider reverting the speaker migration from the AfterTouch Admin UI so the speaker URL is set back to the Bose cloud (though neither Bose nor AfterTouch will be reachable once both are removed).

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

Last updated on May 31, 2026

MQTT Integration Design for SoundTouch Service Raspberry Pi Installation Guide