bosesoundtouchapi.soundtouchwebsocket
A wrapper class to use the notification system provided by SoundTouch devices.
In order to react to a message, there is a listener system. You can add functions as listener objects. The connection url is defined as follows: 'ws://{Host}:{Port}/'. Port 8080 is used by default.
This class can be used in two ways. First, the object can open a
connection through the StartNotification
method and secondly, the with-statement
can be used to create an instance.
You must first check the device capabilities prior to using the support notifications
functionality; if the device does not support it, then it's not going to work!
To do this, fetch the device's capabilities and check for a IsWebSocketApiProxyCapable = True
value. If true, then the device supports sending notifications; if false, it does not.
For more information and code samples refer to bosesoundtouchapi.soundtouchclient.GetCapabilities
method.
Sample Code
# external package imports.
import time
from xml.etree.ElementTree import Element
from xml.etree import ElementTree
# our package imports.
from bosesoundtouchapi import *
from bosesoundtouchapi.models import Capabilities
class EventHandlerClass:
def OnSoundTouchUpdateEvent(args:Element) -> None:
if (args != None):
ElementTree.indent(args) # for pretty printing
argsEncoded = ElementTree.tostring(args, encoding="unicode")
print("\nStatus update args:\n%s" % argsEncoded)
def OnSoundTouchInfoEvent(args:Element) -> None:
if (args != None):
ElementTree.indent(args) # for pretty printing
argsEncoded = ElementTree.tostring(args, encoding="unicode")
print("\nStatus info args:\n%s" % argsEncoded)
try:
socket:SoundTouchWebSocket = None
# create SoundTouch device instance.
device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10
#device:SoundTouchDevice = SoundTouchDevice("192.168.1.130") # Bose SoundTouch 300
# create SoundTouch client instance from device.
client:SoundTouchClient = SoundTouchClient(device)
# get device capabilities - must have IsWebSocketApiProxyCapable=True
# in order to support notifications.
capabilities:Capabilities = client.GetCapabilities()
if capabilities.IsWebSocketApiProxyCapable:
# create and start a websocket to receive notifications from the device.
socket = SoundTouchWebSocket(client.Device)
# add our listener(s) that will handle SoundTouch device status updates.
#socket.AddListener(SoundTouchNotifyCategorys.ALL, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.connectionStateUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.criticalErrorUpdate, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.errorNotification, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.errorUpdate, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.groupUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.languageUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.LowPowerStandbyUpdate, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.nameUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.nowPlayingUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.nowSelectionUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.presetsUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.recentsUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.soundTouchConfigurationUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.sourcesUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.swUpdateStatusUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.volumeUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
socket.AddListener(SoundTouchNotifyCategorys.zoneUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
# add our listener(s) that will handle SoundTouch device informational events.
socket.AddListener(SoundTouchNotifyCategorys.SoundTouchSdkInfo, EventHandlerClass.OnSoundTouchInfoEvent)
socket.AddListener(SoundTouchNotifyCategorys.userActivityUpdate, EventHandlerClass.OnSoundTouchInfoEvent)
# start receiving updates.
socket.StartNotification()
print("** Notification event loop has started.")
print("** Try pressing some buttons on your SoundTouch remote or device ...")
# for testing status notifications.
maxcnt:int = 1200 # 1200=20 mins, 300=5 mins
for i in range(maxcnt):
# wait 1 second.
time.sleep(1)
else:
print("SoundTouch device '%s' does not support Bose WebSocket API.")
except Exception as ex:
print(str(ex))
raise
finally:
# stop listening for Bose SoundTouch status updates.
if (socket != None):
socket.StopNotification()
Initializes a new instance of the class.
Arguments:
- device (SoundTouchDevice): A SoundTouchDevice instance containing the host ip-address.
- port (int): The port the Bose WebAPI socket is posting notifications on.
Default is 8080.
Adds a listener provided here to the given category.
Since there are different types of events, the category-string can be used to add a listener to a specific notification category. The listener must take only one argument: xml.etree.ElementTree.Element.
Arguments:
- category (SoundTouchNotifyCategorys): The category this listener should be added to.
Use one of the pre-defined SoundTouchNotifyCategorys values to receive updates for that category (e.g. "volumeUpdated", "nowPlayingUpdated", etc). Use SoundTouchNotifyCategorys.Error to receive notifications for WebSocket errors.
Use SoundTouchNotifyCategorys.ALL to receive notifications for any type of update event. - listener (object): A simple listener method which takes the XML-Element as a passed argument.
Returns:
True if the listener was added successfully; otherwise, False.
Please refer to the bosesoundtouchapi.soundtouchnotifycategories.SoundTouchNotifyCategorys
class for more details on what events are raised and why / when they happen.
Searches for a specific category in the registered ones.
This method is a convenient method to return all listeners that were added to a specific context.
Arguments:
- category (str): The category, which has to be one of the SoundTouchNotifyCategorys values.
Returns:
A list containing all listeners linked to the given category.
Notifies all listeners that were stored in the given context.
The name of each context is defined to be the tag element of the update XML-Element.
Arguments:
- category (str): The category of which listeners should be notified from.
- event (xmltree.Element): The event represents an XML-Element with event.tag == category.
Removes a listener from the given category.
Arguments:
- category (str): The category this listener should be removed from.
Use one of the pre-defined SoundTouchNotifyCategorys values to receive updates for that category (e.g. "volumeUpdated", "nowPlayingUpdated", etc). - listener (object): A simple listener method which takes the XML-Element as a passed argument.
Returns:
True if the listener was removed successfully; otherwise, False.
Creates and starts a web socket event loop thread that listens for notifications from the SoundTouch device.
Only one web socket event loop thread will be started for the device.
Stops the web socket event loop thread, if one was previously started using
the StartNotification
method.
This method does nothing if the event loop thread was not started.