[App][Pro] Bose Devices

[Shakesbeard]

Bose Devices

Adds support for all SoundTouch enabled devices.

App Store: Bose Devices
Frequently Asked Questions
Change Log

Supported Languages

English
German
Netherlands

The New Bose Smarthome Devices Line (Rant Warning)

I am still planning to support those devices, if I ever get onboarded for that, in the Bose developer portal.
Sadly I have been trying to get access to that section for over half a year now, annoying every communication option Bose offers. This includes (the actual responsible) developer forum moderators, Bose support and Community Relations without any success.
In fact, only their support responded and apologized for not being of any help in that matter.
It would be possible to reverse engineer the protocol from other ports, but I cannot get it operational without an app authorization key.
I am sorry to say, but for the time being there is no way for me to support those devices.

UI Features

Device UI

• Power Toggle
• Playback Control & Album Artwork
• Volume Control & Mute
• Bass Level Control & Reset
• Input Source Selection
• Play Preset
• Energy Consumption

Advanced Device Settings

• Displays the IP and port of the last successful connection with the device.
• You can now toggle to use the manually set values instead of relying on the zero configuration network protocols for device discovery. (You still need to pair the device using auto discovery first)

Available Flowcards

Triggers

Turned On

Triggers when the device has been turned on / became active from standby.

Turned Off

Triggers when the device has been turned off / gone into standby.

Playback Started

Triggers when the device starts playing anything. This also happens for sources like TV.

Playback Stopped

Triggers when the device stops playing.

Artist Changed

Triggers when a new artist is playing.

Tokens

• ‘Artist’ as text

Album Changed

Triggers when a new album is playing.

Tokens

• ‘Album’ as text

Track Changed

Triggers when a new title is playing.

Tokens

• ‘Track’ as text

Muted

Triggers when the device is muted.

Unmuted

Triggers when the device is unmuted.

New Artwork

Triggers when a new artwork is loaded. This also happens when changing to local sources giving the bose logo as default. For the bose logo the ‘Artwork URL’ is an empty text.

Tokens

• ‘Artwork URL’ as text
• ‘Image’ as image

Volume Changed

Triggers when the device reports a change of the volume.

Tokens

• ‘Volume’ in % as number

New Bass Level

Triggers when the device reports a change of the bass level.

Tokens

• ‘Bass Level’ in % as number

New Preset Playing

Triggers when the devices starts playing a [new] preset.

Tokens

• ‘Preset’ as number

New Source Active

Triggers when the device reports a change of the input source.

Tokens

• ‘Source Name’ as text

Favorite started playing

Triggers when an item maked as favorite is played.

Tokens

• ‘Title’ as text
• ‘Artist’ as text
• ‘Album’ as text

Not playing favorites anymore

Triggers when a new item is played which is not maked as favorite anymore.

Joined a Zone

Triggers when the device was added to a zone.

Left a Zone

Triggers when the device left a zone.

Conditions

Is/Isn’t on

Whether the device’s is on stanby or active.

Is/Isn’t playing

Whether the device is currently playing anything.

Is/Isn’t muted

Whether the device’s volume is muted.

Is/Isn’t playing a favorite

Whether the device is currently playing an item maked as favorite.

Source is/isn’t selected

Whether a specific source is selected or not. Supports all possible sources known by the device.

Arguements

• ‘Source’ as autocomplete selector

Is/Isn’t master of zone

Whether the device is master of the zone. Also reports false if device is not in a zone.

Is/Isn’t in a zone

Whether the device is member of a zone.

Is/isn’t in a zone with device

Whether the device is in a zone together with another device.

Arguements

• ‘Device’ as autocomplete selector, providing all paired devices.

Actions

Turn on

Turns the device on.

Turn off

Turns the device off / sends it to standby.

Toggle on/off

Toggles the device on or off depending on its current state.

Play

Starts the playback if supported by the current source.

Stop

Stops the playback if supported by the current source.

Toggle Play/Pause

Toggles between playback and pause if supported by the current source.

Next

Skips playback to the next track if supported by the current source.

Previous

Skips playback to the previous track if supported by the current source.

Shuffle on

Enables shuffled playback if supported by the current source.

Shuffle off

Disables shuffled playback if supported by the current source.

Repeat

Enables repeat playlist, repeat track or disables repeat playback if supported by the current source.

Set Volume

Sets the volume.

Arguements

• ‘Level’ as range selector in percent. (0.0 to 1.0)

Set Relative Volume

Sets the volume relatively to the current volume.

Arguements

• ‘Volume Change’ as range selector in percent. Accepts number tokens giving values -50 to 50.

Mute Volume

Mutes the device.

Unmute Volume

Unmutes the device.

Play a Preset

Starts playing a stored preset.

Arguements

• ‘Preset’ as range selector. Can consume a numeric token.

Set Bass Level

Sets the bass level.

Arguements

• ‘Level’ as range selector in percent. Can consume a numeric token.

Select Source

Changes a source. WIll fail if the source is not available/ready.

Arguements

• ‘Source’ as autocomplete selector. Supports sources local to the device only.

Send Command

Whether a command is supported depends on the state of the device. If the command is [currently] not supported it will silently fail. Example: Sending the ‘Next Track’ command while playing internet radio or watching TV will simply do nothing.

Arguements

• ‘Command’ as autocomplete selector.

Create Zone / Add Device

Adds a device to an existing zone if we are master of the zone or creates a new zone with the selected device. Will fail if we are in a zone but not the master of that zone, or if the device is not available.
NOTE: For the zones feature to work properly, all your devices should be paired to the app. Otherwise you might experience sideeffects if you change the zone configuration from within another 3rd party app or the Bose apps.

Arguements

• ‘Device’ as autocomplete selector, providing all paired devices.

Remove Device From Zone

Removes a device from an existing zone. Will fail is there is no zone or if we are not master of the zone.

Arguements

• ‘Device’ as autocomplete selector, providing all paired devices.

Play Notification

Plays a media file as notification on the device. The device pauses what it is currently doing and continues whatever it was doing after the notification was played. The devices will wake up from standby and go back to standby if necessary.
According to the api documentation this is support for the following devices only: SoundTouch 10, SoundTouch 20 Series III, and SoundTouch 30 Series III

Arguements

• ‘Soundfile URL (MP3, AAC, HE-AAC, WMA, Vorbis, FLAC or ALAC)’ as text.
  Supported formats are:
  • MP3 - 8kbit/s to 320kbit/s
  • AAC - 24kbit/s to 128kbit/s
  • HE-AAC - 48kbit/s to 64kbit/s
  • WMA - 8kbit/s to 320kbit/s
  • Vorbis - 32kbit/s to 500kbit/s
  • FLAC - VBR: 0bit/s to 1.4Mbit/s; up to CD quality (2 channel / 48kHz / 16bit)
  • ALAC - 300kbit/s to 5Mbit/s; HD (2 channel / 96kHz / 32 bit)
• ‘Reason’ as text.
• ‘Message’ as text.
• ‘Volume’ as range selector. Only values from 10 to 70 are allowed. This restriction is made by bose, not this app.

Restore Previous Playback

Instructs the device to restore the previously playing source. This greatly differs from the “Select Source” function. Previous Playback can not just be a different input but also be a different playlist or radio station. The device will try to resume the previous playback where you left off.

Special Thanks Goes To

Stefan Simon (aka @SlicingHaunt) for helping me with getting this sound.

[Shakesbeard]

Frequently Asked Questions

Q: I am using Stefan’s (SlicingHaunt’s) Bose Soundtouch app. Do I need to remove my devices to use them with this app?
A: No. You can use both apps in parallel and transition at your own pace.

Q: My device is not recognized anymore, what happened?
A1: Do not worry. This is most likely just a network issue, preventing the device detection to fail. Sometimes, when you device loses the network connection and then becomes reconnected, it does no longer respond to discovery requests. Please restart your device in this case and wait some minutes for the discovery to recover.
A2: If you struggle with this problem on regular basis you can now (v1.2.0+) provide the connection details manually in the devices advanced settings menu. To do so, please configure a fixed IP address for your device. Pair the device if not paired yet. Go to the device’s advanced settings and enable manual address mode. Make sure your fixed IP for the devices is entered in the IP address field.

Q: What exactly do you mean if a feature/card’s name starts with “Experimental”?
A: This can have several reasons.

• The feature has not been tested in all possible combinations
• The feature has not been tested on many devices
• I have no device which supports that feature and therefor cannot test it myself at all
• I have not received any feedback about that feature, yet

If you can test one of those features, please PM me your feedback. Thanks in advance!
Even though it is unlikely, experimental features might change in a breaking manner with updates or be removed completely. Just so you are aware.

Q: My device does not show any energy consumption data, what’s wrong?
A: Nothing wrong. The energy data for the device simply is not known (,yet) If you can, please send me the consumption values for your device when it is in standby and when it is playing on max volume. I will add the values to the app.

Q: Why is one of my input sources not showing in the device UI of the Homey app?
A: Maybe you have a device which has a source I am not aware of, yet. Please contact me using the support email given in the app store page or PM me on the forum here.

Q: When I press a button in the UI of the device in the Homey app nothing happens?
A: Unfortunately I cannot temporarily disable buttons not allowed to press. If the current playback mode does not support a particular botton/option, then it will silently fail. If you still think this is an error, open a Bose Soundtouch app and see whether the button/option is presented there for the current playback mode, before sending a bug report.

Q: The memory consumption of the app explodes rapidly and it becomes paused.
A: I have tried to reproduce this, but up until now I have been unsuccessful doing so. However, I have observed something strange with Homey which caused exactly this effect. But I do not think that it is related to this app directly as I was able to see other apps react similiar at the same time. The others did not get paused as the effect was not as strong as for the Bose app. But it clearly was a general thing caused by the Homey firmware. I will keep monitoring this.

[Shakesbeard]

Change Log

v2.0.12

• Fixed: This is just a hotfix for bug introduced in .11.

v2.0.11

• Fixed: Added a hotfix trying to avoid app crash when for any reason the zone info reported by the device is ‘null’.

v2.0.10

• Fixed: Stability fix for the internal realtime communication handler when devices are removed from Homey.
• Fixed: Attempt to bulletproof against app crashes when rapidly skipping playback tracks.

v2.0.8

• Fixed: Select Source action flowcard.

v2.0.7

• Fixed: Mute function action flowcards would toggle instead of explicitly setting desired state.

v2.0.6

• Fixed: Edge case crash if a device sends an empty real time api message.

v2.0.5

• Homey Pro 2023 compatibility update.

v2.0.4

• Updated: App migrated to Homey App SDK v3.
• Updated: Removed experimental state of notification flowcard.
• Added: Formatted card titles.
• Removed: Auto restart logic.

v1.2.7

• Updated: New app icon and reduced app store info as requested by Athom.
• Removed: The build-in set relative volume action flowcard has been deprecated, in favor of the now auto generated card. The old card still works but can no longer be added.

v1.2.6

• Added: Experimental workaround for memory related app crash.

v1.2.5

• Fixed: Minor bug in capability auto healing.

v1.2.4

• Removed: Deprecated diagnostics feature. App settings page has been removed for the time being.

v1.2.3

• Fixed: Bluetooth source selection not working
• Updated: Improved pre-pairing device discovery stability

v1.2.0

• Added: A device setting is now available to check on the last successfully conected address and also enables you to provide fixed connection settings.
• Updated: Action card ‘Restore Previous Playback’ is out of experimental stage and now a permanent asset

v1.1.2

• Added: New experimental action card ‘Restore Previous Playback’

v1.0.3

• Fixed: Set Relative Volume not working for some users
• Fixed: Device connection loss is now detected and handled properly

v1.0.1

• Initial Release
• NOTE: The Notification feature is still experimental. I would love to hear feedback about it.

v0.1.0 - v0.1.10

• Pre Publishing Test Releases

[Osorkon]

Can you please share the link to the test version as it is available. Unfortunately there is no possibility in the app store to search for a test version

[Shakesbeard]

Hi @Osorkon,
unfortunately this is not as easy as it sounds. Athom did change the release process so we can offer test versions before release, but every time I push a new version (whilst there was no version released before) the link becomes invalid until Athom has approved the app. At the moment am waiting for the release version to be approved. So no test link available at the moment, sorry.

[DidierVU]

It’s live! Let’s hope the documentation is wrong and “Play Notification” works on ST300, would be nice to use in combination with Ring when someone’s ringing the bell. Going to test this asap.

[Osorkon]

Set Relative Volume don’t work for me (SoundTouch 10 & 20)

[Henri]

Great thanks for your work Thomas !

[Shakesbeard]

Yes. It looks like there is a little bug in still. Does not occur for every user for some reason. I will fix this asap.

[Henri]

Hello,
Is it possible to save what is currently played on the device, save it and play it again later ?
And another question, how to play a Spotify playlist ?
Thanks

[DidierVU]

Which device? On my ST300 I can use the Spotify app from Athom.
Saving state would be handy indeed for a workaround with notifications that are unable on ST300

[Shakesbeard]

Hi @Henri,
the best what the Soundtouch api offers there is the presets functionality. It basically can save what you have currently on playback and can recall it later. But I cannot tell you how this behaves with Spotify. I do not have Spotify myself.
Please share your experience with that if you decide to test that with Spotify

[Henri]

@DidierVU : Hi, I’ve a ST20 in the kitchen (the main), a ST300 near the TV and ST portable in the bathroom
The Spotify app seem to be very limited… Next track, previous, pause/start and that’s all

@Shakesbeard : If you want, you can create a free account on Spotify and try it
It’s realy cool
It seem To be possible to play spotify track, album or playlist with ST api
http://52.42.58.102/#Spotify

[Shakesbeard]

@Henri
Oh this looks interresting. In fact, what is shown on that page is not documented in the official API specification. Let me toy with this a little and see what I can whip up.

Update: I can see why this is not documented. It looks like this is how the Soundtouch app controls the device, using already configured accounts.
The question is, what you actually want to accomplish @Henri
I think it would theoretically be possible to save the very currently playing item and play it again. But I think this would really just play that one thing you been playing originally then.

For the spotify playlist. Well, I am not planning on implementing a spotify api there. But what you could do is just select your spotify playlist in the Soundtouch app and save it as preset. That should work smoothly.

Update 2: Color me corrected. It is not possible to save the currently playing item. What the payload actually contains is only the playback configuration currently used. I tried jumping between “saved” items. It does continue exactly where you left off when switching but that state information seems to be preserved by the device itself and is not visible on the api.

[DidierVU]

You have to add a device to the Spotify app so your ST300 can use Spotify Connect, then you can choose between anything…

[Shakesbeard]

@Henri @DidierVU
Question: Would there be an interrest in storing the current playback config to jump back and forth between them? And if so, would you like just a “Back to last playback mode” or save individual states?

So for a better understanding. The storable information holds the playlist which is playing or for NAS type storage which folder is playing. For radio it would simply be the station playing.
In other words. It stores the media context you are currently browsing through with the Bose Soundtouch app.

[DidierVU]

Is it also possible to go back to what source it was on? For example, I’m watching TV and someone rings the Ring doorbell: if Ring -> then play Spotify doorbell sound on ST300 and return to previous state (after XX seconds).

Would be a nice replacement for the Notification API that’s not working on all devices.

Edit: Imo saving states so you can use it in the future is something than can be done by creating a flow so jumping back to last state would be great.

[Shakesbeard]

Yes. The playback config item includes the source. I tested it with hopping between sources and playlists successfully. I would assume this works for all possible source services.

[Henri]

Wow, what an enthusiasm!
(Sorry for my poor knowledge of English I am French speaking from Belgium) (I use a translator to write…)
My first need (or rather desire) was to be able to link my st20 with my st300 without using a smartphone.
So I tried to find a key suit on the st20 that I could catch.
I managed to capture a double-click on any preset key, which allows me to put on the 1 key, the st20 only. On the key 2: st20 + st300 and on the key 3: st20 + st300 + st portable.
It works perfectly, only worries (but not so bad) what played on the st20 is replaced by the preset 1 or 2 or 3.
That’s why I wanted to save what was playing so that I could put it back after tying the soundtouch.
I also synchronized the volume between st20 and st300.
No worries if it doesn’t work, thanks for your feedback.
I will dig the trail of the Spotify app proposed by Didiervu

[Shakesbeard]

@Henri That sounds more like the Zones feature. You can easily control the zones with flowcards of this app. No need to capture keys or presets for this. (or am I missing anything?)