bosesoundtouchapi.soundtouchdevice

@export
class SoundTouchDevice:

This class contains device-related information, such as: host ip address, device name/type/id, a list of the device's components, a list of supported URLs and the current network configuration.

The supported URLs are used by the SoundTouchClient to verify the requested URL is supported by the device.

In order to load all properties and attributes of the SoundTouchDevice object, some special URLs will be queried: - http://host:8090/info (contains basic device information) - http://host:8090/supportedURLs (contains URL's supported by the device)

Click the Sample Code links in the individual methods for sample code examples.

SoundTouchDevice( host: str, connectTimeout: int = 30, proxyManager: urllib3.poolmanager.ProxyManager = None, port: int = 8090)

Initializes a new instance of the class.

Arguments:
  • host (str): An Ipv4 address of the device; it must the following regular expression pattern for a IP V4 network address: r"\d{1,3}([.]\d{1,3}){3}".
  • connectTimeout (int): Controls how long (in seconds) a connection request is allowed to run before being aborted.
    Only used if the proxy argument is null (e.g. default proxy manager is used).
    Default is 30 seconds.
  • proxyManager (Optional[urllib3.ProxyManager]): If a custom proxy should be used, it can be specified here; otherwise, a default urllib3.PoolManager is used for http requests / responses.
  • port (int): IPV4 port number the Bose WebAPI is listening on for incoming requests on the device. Default is 8090, the standard WebAPI port number.
Raises:
  • SoundTouchError: SoundTouch host address is not recognized as a valid IPV4 network address.
    Could not retrieve SoundTouch device information.
    Could not retrieve SoundTouch device supported urls.
    If the method fails for any other reason.

This method loads all components and device properties allocated at the given SoundTouch host.

Sample Code

from bosesoundtouchapi import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.81") # Bose SoundTouch 10

    # display device basic details and all installed components.
    print(device.ToString(True))

    # iterate over all components that match the given category.
    print("\nDisplaying specific components - SCM ...")
    for component in device.GetComponents('SCM'):
        print(component.ToString())

    # iterate over all components that match the given category.
    print("\nDisplaying specific components - LPM ...")
    for component in device.GetComponents('LPM'):
        print(component.ToString())

    # iterate over all components that match the given category.
    print("\nDisplaying specific components - LPMBL ...")
    for component in device.GetComponents('LPMBL'):
        print(component.ToString())

    # iterate over all components that match the given category.
    print("\nDisplaying specific components - BASS ...")
    for component in device.GetComponents('BASS'):
        print(component.ToString())

    # dump the webapi list of uri's this device supports.
    print("\nSupported URI's for device '%s':" % (device.DeviceName))
    for item in device.SupportedUris:
        print("- %s" % (str(item)))

except Exception as ex:

    print("** Exception: %s" % str(ex))

Components: list[bosesoundtouchapi.models.component.Component]

List of Component objects containing various information about the device's components (e.g. SCM, LPM, BASS, etc).

ConnectTimeout: int

Controls how long (in seconds) a connection request is allowed to run before being aborted.
Only valid if the proxy argument is null (e.g. default proxy manager is used) on the class constructor.

CountryCode: str

Country code of the device as assigned by the manufacturer (e.g. 'US', etc).

DeviceId: str

Unique device identifier as assigned by the manufacturer (e.g. '9070658C9D4A', etc).

DeviceName: str

Friendly name assigned to the SoundTouch device (e.g. 'Home Theater SoundBar', etc).

DeviceType: str

Type of device as assigned by the manufacturer (e.g. 'SoundTouch 10', 'SoundTouch 300', etc).

Host: str

Ipv4 address of the SoundTouch device. This property is read-only, and supplied by the class constructor.

LogReadUrl: str

URL to download a logread file from this device.

The format of the returned url is:
http://{Host}:8091/logread.dat

Example with Host = '192.168.1.81':
http://192.168.1.81/logread.dat

MacAddress: str

MAC address (media access control address) assigned to the device.

ModuleType: str

Radio module type used in the device, as assigned by the manufacturer (e.g. 'SM2', etc).

NetworkInfo: list[bosesoundtouchapi.models.infonetworkinfo.InformationNetworkInfo]

List of InformationNetworkInfo objects containing the current network configuration of the device.

Port: str

Ipv4 address of the SoundTouch device. This property is read-only, and supplied by the class constructor.

RegionCode: str

Region code of the device as assigned by the manufacturer (e.g. 'US', etc).

StreamingAccountUUID: str

Bose Streaming account UUID, as assigned by the manufacturer (e.g. '1234567', etc).

StreamingUrl: str

Bose Streaming URL, as assigned by the manufacturer (e.g. 'https://streaming.bose.com', etc).

SupportedUris: list[bosesoundtouchapi.uri.soundtouchuri.SoundTouchUri]

List of SoundTouchUri objects that the device supports.

These URI's are used by the SoundTouchClient class to obtain information from the device (e.g. info, nowPlaying, etc).

PtsUrl: str

URL to download a logread file.

The format of the returned url is:
http://{Host}:8091/pts.dat

Example with Host = '192.168.1.81':
http://192.168.1.81/pts.dat

UnknownUrlNames: list[str]

List of url names that the device support, but are NOT recognized by the SoundTouch API.

UnSupportedUrlNames: list[str]

List of url names that are NOT supported by the device.

UpnpUrl: str

Universal Plug and Play (UPnP) root URL for this device.

The document located at the returned URL contains additional information about methods and properties that can be used with UPnP.

The format of the returned url is:
http://{Host}:8091/XD/BO5EBO5E-F00D-F00D-FEED-{DeviceId}.xml

Example with Host = '192.168.1.81', DeviceId = 'E8EB11B9B723':
'http://192.168.1.80:8091/XD/BO5EBO5E-F00D-F00D-FEED-E8EB11B9B723.xml'

Variant: str

Variant value (e.g. 'ginger', etc).

VariantMode: str

Variant mode value (e.g. 'noap', etc).

def GetComponents( self, componentCategory: str) -> bosesoundtouchapi.models.component.Component:

Iterates over all components discovered at class initialization that match the given category.

Arguments:
  • componentCategory (str): The component's category
Returns:

An iterator over the filtered Component components.

This yields a device component for the given category.

def RebootDevice(self, sshPort: int = 17000) -> str:

Reboots the operating system of the SoundTouch device.

Arguments:
  • sshPort (int): SSH port to connect to; default is 17000.
Returns:

The SSH server response, in string format.

This method will open a telnet connection to the SoundTouch SSH server running on the device (port 17000). It will then issue a sys reboot command to reboot the device. The telnet session will fail if any other process has a telnet session open to the device; this is a SoundTouch device limitation, as only one SSH session is allowed per device.

If successful, all communication with the device will be lost while the device is rebooting. SoundTouch web-services API connectivity should be restored within 45 - 60 seconds if the reboot is successful.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.81") # Bose SoundTouch 10

    # reboot device.
    print("Rebooting device: '%s' ..." % device.DeviceName)
    response:str = device.RebootDevice()
    print("Device Response:\n%s" % response)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def ToString(self, includeItems: bool = False) -> str:

Returns a displayable string representation of the class.

Arguments:
  • includeItems (bool): True to include all items in the list; otherwise False to only include the base list.