SoundTouchPlus Custom Integration

thlucas · October 30, 2023, 2:15pm

I have developed a new SoundTouchPlus Home Assistant custom component integration that hopefully breathes new life into Bose SoundTouch speaker support. I finally got tired of libsoundtouch not being supported, so decided to write an integration that can be distributed via HACS. Since it’s a new integration name (e.g. SoundTouchPlus) it won’t interfere with the built-in SoundTouch integration setup. It’s a simple install to the “custom_components” directory via a HACS UI custom repository installer.

The following Home Assistant media_player Platform services are supplied by this integration.

BROWSE_MEDIA
GROUPING
NEXT_TRACK
PAUSE
PLAY
PLAY_MEDIA
PREVIOUS_TRACK
REPEAT_SET
SELECT_SOURCE
SHUFFLE_SET
STOP
TURN_OFF
TURN_ON
VOLUME_MUTE
VOLUME_SET
VOLUME_STEP

The following custom services are supplied by this integration - more information and YAML examples can be found on my GitHub Project Wiki, Services Provided page:

Play Handoff: Handoff playing source from one SoundTouch device to another.
Play TTS Message: Play Text-To-Speech notification on a SoundTouch device. Note that this is limited to ST10,20,30 devices, as Bose ST300 does not support notifications (AFAIK).
Get Preset List: Retrieves the list of presets defined to the device.
Get Recent List: Retrieves the list of recently played items defined to the device.
Remote Keypress: Simulates the press and release of a key on the SoundTouch device remote control.
Snapshot Restore: Restore SoundTouch device settings from a snapshot.
Snapshot Store: Store SoundTouch device settings to a snapshot.

I also developed the underlying bosesoundtouchapi Python 3 library, which packs quite a few new features that libsoundtouch does not provide. To give credit where credit is due, portions of the code and the overall “flow” were taken from contributions made by MatrixEditor. My original intent was to fork his repository and add some changes, but there were just too many and I wanted to change some things that would have broken backward compatibility with his code so I continued with my own repository. Almost every method is documented with sample code; just click on the “Sample Code” links under the method, and use the “Copy to Clipboard” functionality to copy / paste. Check out the SoundTouchClient class to get you started.

What Bose Speakers are Supported?

Any Bose SoundTouch line of speaker that support the SoundTouch Webservices API should be supported. These include the ST-10, ST-20, ST-30, ST-300, ST-520, etc. I have only tested with the ST-10 and ST-300 products (what can I say; Bose products are expensive, and I can only afford the two! :D), but other SoundTouch devices should be compatible.

Note that the newer line of Bose Speakers (Home Speaker 500, 700, etc) are NOT supported as they are not of the SoundTouch product line and do not utilize the Bose WebServices API for control.

I should also note that there are some features in the bosesoundtouchapi that are only supported for certain SoundTouch devices. For example, the “Notification” service (e.g. PlayNotificationTTS) is only supported by the the ST-10,20,30 and not the ST-300 product.

Please let me know if you run into any issues.

HACS Install Instructions

go to HACS main menu.
click on the 3-dot “overflow menu” in the upper right, and select “custom repositories” item.
copy / paste https://github.com/thlucas1/homeassistantcomponent_soundtouchplus in the Repository textbox and select Integration for the category entry.
click on “Add” to add the custom repository.
you can then click on the SoundTouchPlus repository entry (you may need to filter your list first to find the new entry).
click on “download” to start the download. It will install the soundtouchplus integration to your config/custom_components directory.
restart HA to start using the component.

I submitted the branding icons to the HACS branding repository and they were just approved, so the integration should show the custom component icons soon (same icons as soundtouch integration).

PyPi Install Instructions

Use the following to install just the Python 3 library if you wish:
$ python3 -m pip install bosesoundtouchapi

jones · October 30, 2023, 2:34pm

Wow! Great News and amazing work. I‘ll test your Integration as soon as possible.

vschild · October 30, 2023, 4:16pm

Thanks! Will try it in a couple days

fjesuslsanchez · November 12, 2023, 11:44pm

I’ve trying to connect the Soundtouch without success. I’m running HA supervised on Debian 12 with docker and when I add the integration I’ve the following error:

I made a network scan and I can see that the IP address is OK. The scan says that only ports 80, 7000 and 8080 are open for the given IP address. I’ve tried changing them without success…

Do I need something else in order to add the integration (I followed all the installation steps)?

thlucas · November 13, 2023, 1:55am

Hi there. The Port value (e.g. Bose WebServices API Port of the device) needs to be a value of 8090. The Bose WebServices API listens for requests on port 8090. The port 8080 value is for the WebSocket port.

Note that you will possibly need to open firewall ports to your Bose SoundTouch device for port 8090 if not already opened.

A quick way to test this is to enter the following in your browser (Chrome, etc):
http://192.168.1.27:8090/info

It should display something similar to this if successful:

Hope it helps!

fjesuslsanchez · November 13, 2023, 6:47am

I have the same result if I make http://192.168.1.27:8090/info

In the screenshot you can see the port 8080 but exactly the same result with the 8090

thlucas · November 13, 2023, 12:42pm

Questions:

what is the specific model number of the Bose Speaker you are trying to control (e.g. ST-10, ST-300, etc)?
are you sure you have the correct IP address of the Bose SoundTouch device? Port 8090 should be open and listening if it’s a SoundTouch device.
did you enter http://192.168.1.27:8090/info in a new browser (e.g Chrome, FireFox, Edge, etc) window? Just want to make sure you did not enter that into the IP Address field of the Add Device form. Can you reply with a screen capture of that output from your new browser window please?

Your Add Device form should look like this, assuming you have the correct IP address and that it is a Bose SoundTouch device:

btw, welcome to the community - just noticed that you were a new community member.

thlucas · November 15, 2023, 12:41pm

Hi fjesuslsanchez - just following up to see if you got the SoundTouchPlus integration working?

Inama834 · November 15, 2023, 4:44pm

Inama834 · November 15, 2023, 4:47pm

thlucas · November 15, 2023, 5:16pm

It appears there may be a firewall blocking the connection from Home Assistant to the ST-30 speaker.

Questions:

what browser url did you specify to list the info in your second screen capture? did you use this: http://192.168.0.95:8090/info maybe? If so, that tells me that the ST-30 is responding (to your browser request), which tells me that something is blocking the connectivity between your Home Assistant instance and the ST-30.
what version of Home Assistant are you running? To verify, go to “Settings\About”. It should look something like this:
If you have the Terminal addon installed for HA, can you issue the following command. It will try to ping the ST-30 from the HA instance.
ping 192.168.0.95