Bose SoundTouch

The Bose SoundTouch driver controls SoundTouch speakers and soundbars (10/20/30, SoundTouch 300, Wave SoundTouch IV) through the local HTTP+XML API on port 8090. One GEM device represents one speaker.

Status

Transport (play/pause/stop/skip), volume and mute, presets 1-6, source switching (AUX/Bluetooth), and live now-playing polling are wired. The passthrough style command and group/zone (multi-room) management are not implemented in this driver — for whole-home grouping use the SoundTouch app or wire each speaker as its own GEM device.

Prerequisites

• SoundTouch speaker on the LAN with current firmware and the SoundTouch mobile app paired.
• Static IP or DHCP reservation on the speaker — GEM does not auto-discover SoundTouch units.
• TCP 8090 reachable from the GEM host to the speaker.

Setup

1. Pair the speaker in the Bose SoundTouch mobile app and configure presets 1-6.
2. Reserve the speaker's IP in DHCP.
3. In System > Devices, create a device with driver bose_soundtouch. Set the ip attribute. Port defaults to 8090.
4. Verify connectivity from the Script Console:

   await gem.command({device_id: <device_id>, command: 'get_info'});

   The response will include the speaker's name and MAC.
5. The driver polls /now_playing and /volume every status_interval ms; track, artist, source, volume, mute, and play state attributes update automatically.

Attribute reference

Device attributes

Attribute	Type	Required	Description
ip	string	yes	LAN IP of the speaker.
port	int	no	HTTP port. Default 8090. Some early units use 8091. A value that is not a whole port number (1-65535) falls back to 8090 with a warning in the log.
status_interval	int	no	Poll interval in milliseconds. Default 5000, minimum 1000. A value that cannot be read, zero or negative uses 5000.

The driver reflects the following attributes onto the device as state changes:

Attribute	Type	Source
volume	int	/volume actualvolume (0-100).
mute_state	string	on / off.
play_state	string	PLAY_STATE, PAUSE_STATE, STOP_STATE, BUFFERING_STATE, etc.
source	string	STANDBY, INTERNET_RADIO, BLUETOOTH, AUX, etc.
track	string	Now-playing track title (when present).
artist	string	Now-playing artist (when present).

Polling and connection state

A speaker in standby still answers on port 8090 (its source reads STANDBY), so a sleeping speaker stays connected and is polled at the normal rate. Only a speaker that does not answer at all is marked disconnected. After three polls in a row go unanswered, the driver backs off: the interval doubles with each further miss, up to 5 minutes (or status_interval, if that is longer), and the log says so once rather than on every poll. The first poll that gets an answer returns to the normal rate, and so does any command the speaker answers in the meantime.

Zone address format

This driver does not use zones — each speaker is its own device.

Commands

Command	Args	Notes
play / pause / stop / play_pause	—	Transport keys.
next_track / previous_track	—
power_toggle	—	SoundTouch only exposes a single POWER toggle key — there is no on/off pair.
volume	level (0-100)	Sets absolute volume.
volume_up / volume_down / mute_toggle	—
play_preset	preset (1-6)	Triggers the preset configured in the SoundTouch app.
set_source	source (AUX_INPUT, BLUETOOTH)	Switches inputs.
send_key	key	Sends any raw SoundTouch key press.
get_now_playing / get_volume / get_info / get_presets / get_sources	—	Read endpoints.

Commands return the speaker's reply parsed from XML. When the speaker refuses a request — a non-2xx HTTP status, or an <errors> document — the result also carries an error field (and status for a non-2xx reply), alongside the parsed reply, so a macro can tell a refusal from success. Out-of-range or unreadable arguments (a volume outside 0-100, a preset outside 1-6, an unknown key) are refused without sending anything.

Known limitations

• Multi-room grouping (zones) is not supported by this driver. The Bose Zone API is documented but commercial install patterns are usually one-speaker-per-room, so we kept the surface focused.
• The SoundTouch API does not expose per-track album art beyond a URL field; only track and artist text are mirrored as attributes.
• Source switching is key-based, not name-based — there is no "set input HDMI-2" call. Use play_preset for source-tied presets.

Troubleshooting

Symptom	Check
No response on port 8090	Verify firmware is current and the SoundTouch app can control the speaker. Try port 8091 on early units.
Volume changes but state does not appear in GEM	Reduce status_interval to 2000ms while debugging.
Presets do nothing	Open the SoundTouch app and assign presets 1-6 first; the driver triggers PRESET_N keys but does not assign them.
401 / 403 from /info	Some firmware locks down API access until the speaker has been paired in the SoundTouch mobile app. Run pairing in the app first.