Bose SoundTouch Telnet (Port 17000) Command Reference

A consolidated reference for the diagnostic shell that listens on TCP port 17000 across the SoundTouch line. Compiled from multiple community sources to give a single map of what’s been observed in the wild — useful both for implementing automation against it (see TELNET-MIGRATION-METHOD.md) and for manual recovery / WiFi setup.

Important caveat. The command set is firmware-dependent. Anything that existed in firmware 1.x–7.x (flarn2006’s era) was progressively trimmed; some commands listed here have been removed on firmware 27.x. Where a command’s availability is known to vary, the Availability column says so.

Telnet via Docker (when not installed locally)

docker run --rm --name telnet -it --env IP=192.0.2.123 alpine:edge ash -c 'apk add -U busybox-extras && telnet $IP 17000'

Sources

Connecting to the shell

From an already-on-network device

The shell binds to TCP port 17000 on every device family observed (ST 10/20/300, Wave III/IV, ST 520, SA-5 — see §“Firmware era notes” for caveats). No authentication.

# A no-op probe just to verify reach.
echo '' | nc -w 2 <device-ip> 17000

# Or interactively — works the same.
telnet <device-ip> 17000

The bose script (S4) goes one level lower and writes commands directly to a /dev/tcp/<ip>/17000 redirection target instead of using nc. That’s the same wire protocol with no library between.

From a factory-fresh / WiFi-less device

Per S2/S3 — newer firmware may have closed this on some models:

1. Enter setup mode. Press and hold key 2 + volume down for 5 seconds until the WiFi LED turns amber.
2. Connect your laptop to the speaker’s open access point. The speaker becomes its own AP.
3. Telnet to 192.0.2.1 on port 17000.

Once you’ve added a WiFi profile (see network wifi profiles add below) the speaker reboots into station mode and the AP goes away.

Hardware key combinations on the device itself

The network family — WiFi & interfaces

Example session — adding a network from setup mode (S3):

network wifi profiles add foobarHub wpa_or_wpa2 topsecret

The speaker stores the profile, drops the setup AP, and reboots into station mode.

The key family — front-panel button emulation

Each key … command emulates a press of a physical button on the speaker or remote. Confirmed working on ST 10 / FW 27.0.6.46330.5043500 (S5); also visible on the ST 20/300/Wave captures in #221. Different from the sys presetkey N p form (S4) — the key prefix_N shape on FW 27 is what the device’s own remote sends.

The S4 bose script’s sys presetkey N p form still works, but key prefix_N is shorter and matches what the remote already does on FW 27.x.

The sys family — system control & service URLs

The sys family is the one our migration uses (see §“What we use during migration”). Two distinct sub-syntaxes coexist:

• Single-token verbs: sys reboot, sys volume, sys power, etc.
• sys configuration <key> <value> setters that modify persisted runtime configuration. Used for the four service URLs (margeServerUrl, statsServerUrl, swUpdateUrl, bmxRegistryUrl).

Each sys configuration setter is reported by users to return OK on success. Wait for that token between commands (S6, foob61451).

The envswitch family — parallel persistence layer

envswitch writes to a separate, lower-level persistence store that wins on next reboot if the corresponding sys configuration value differs. So our migration writes both — see TELNET-MIGRATION-METHOD.md §2.1.

The getpdo family — read persisted configuration

getpdo <selector> prints the contents of a persisted-data-object. We use it as the verification step after writing URLs.

The scm family — service control

scm (System Control / Module manager) lets you inspect and restart internal services.

Shell-unlock commands

These are the commands that gated SSH access on older firmware. Both have been progressively removed; on FW 27.x they generally do nothing useful.

The ws and swupdate families

help

Lists the commands available on the running firmware. Frequently removed on later firmware — returns Command not found on FW 27.x in many of the captures we have. Still worth probing once during preflight: a successful response is a quick way to enumerate what this specific build supports without trial-and-error.

Device codenames (S1)

These show up in getpdo, network status, and SSH-side hostnames. Useful for matching captures to hardware.

Firmware era notes

• Firmware 1.x–7.x (S1 era): everything — help, remote_services on, full scm, and an in-shell login prompt. flarn2006 documents the original Linux insides.

• Firmware 8.x–14.x (S2 era): remote_services on removed; network, sys, envswitch, getpdo still present. local_services on works on some Wave/SA-5 models.

• Firmware 27.x (S5/S6 era — the long-lived “frozen” build that survived through EOS): help, remote_services on, and sys ver removed in some builds; sys configuration … and envswitch … confirmed working on ST 10, ST 20, ST 300, Wave III, Wave IV. This is the firmware our migration targets. The Portable on more recent firmware drops further commands and is the hardest target.

  S5 enumerated the top-level command roots that don’t return “Command not found” on a vanilla ST 10 (rhino) running 27.0.6.46330.5043500:

  key
  net
  sys
  getpdo

  Notably absent from that probe: network, envswitch, scm, ws, swupdate, remote_services, local_services, demo, mode, help. However, other captures on the same firmware family (S6, ST 20 / Wave III / Wave IV) accept envswitch …, suggesting either per-model variation in the shipped command table or an SSH/role gate the S5 author didn’t trip. Implementations that use envswitch should treat its absence as a recoverable preflight outcome (we already do).

  net is observed as a valid root by S5 but its sub-commands aren’t enumerated; it may be a shorthand alias for network on FW 27.x ST 10.

What we use during migration

For quick reference, the exact sequence our pkg/service/setup.migrateViaTelnet issues, all on the same connection, in this order:

sys configuration bmxRegistryUrl <serverURL>/bmx/registry/v1/services
sys configuration statsServerUrl <serverURL>
sys configuration margeServerUrl <serverURL>
sys configuration swUpdateUrl    <serverURL>/updates/soundtouch
envswitch boseurls set <serverURL> <serverURL>/updates/soundtouch
getpdo CurrentSystemConfiguration

Plus, when pairing a fresh device whose :8090/setMargeAccount is missing or wedged, the helper falls back to:

envswitch accountid set <7-digit-id>

Reboot is not part of these sequences — it stays a user-initiated action via the existing reboot button, which now accepts ?method=telnet|ssh and sends sys reboot when telnet is picked.

Out of scope here, but worth recording

• Setup-mode WiFi onboarding via 192.0.2.1. The community uses this to add a fresh device to a network without the Bose app. Our soundtouch-service does not currently automate this, but network wifi profiles add is the entry point if we ever do.
• Direct preset / playback control via sys. The S4 bose script demonstrates a viable headless remote-control path that does not need our marge emulation at all. Useful as a fallback for tooling on devices that refuse to talk to any cloud.
• scm restart <service>. Not used today, but a possible recovery primitive on older firmware where a stuck service blocks streaming.