SoundTouch Messages ¶

The API makes use of an object oriented caller model where Uri-objects are used to specify a specific path and action on the device.

Classes ¶

SoundTouchUri ¶

class boseapi.common.message.SoundTouchUri(path: str, scope=SoundTouchUriScope.OP_SCOPE_PUBLIC, uri_type=SoundTouchUriType.OP_TYPE_REQUEST)¶

A class barely behaving like a string instance.

An SoundTouchUri object can be used in several ways. Since, the object can not be edited, there is no editing available.

The __str__ and __repr__ method will return the assigned path name (created when initiating a new instance).

Attributes:: path: str The target uri which will be formatted into the url in a request. scope: SoundTouchUriScope The scope of this URI object. If it is private, the client may not request the reSource. uri_type: SoundTouchUriType Defines the type of this uri - it can be either ‘request’ or ‘event’.

Some usage examples and behaviour of an SoundTouchUri object.

from boseapi.common import nodes, SoundTouchUri

# Example for the 'volume' node:
uri = SoundTouchUri("volume")

# len()
assert len(uri) != 0

# iterating over each character
for char in uri:
  print(char)

# compare to another uri
assert uri == nodes.volume

SoundTouchMessage ¶

class boseapi.common.message.SoundTouchMessage(uri: Optional[SoundTouchUri] = None, xml_message: Optional[str] = None, response: Optional[Element] = None)¶

A class representing an exchange object.

In order to exchange data between a client and the device, this class type is used. It stores the request text/uri and the response as an XML- Element.

Attributes:: uri: SoundTouchUri The target uri which should be queried. xml_message: str If a key should be pressed or new data should be saved on the target device, a xml formatted string is needed. response: xml.etree.ElementTree.Element The response object as an XML-Element.

get_message() → str¶: Returns the xml formatted message string.

set_response(response_object: Element)¶: Set the response object.

A simple example of how to use an SoundTouchMessage object follows. It is recommended that this class should only be used internally by the client object.

from boseapi.all import *

# simple message instance
message = SoundTouchMessage(nodes.volume)
device = new_device('127.0.0.1')

with SoundTouchClient(device, errors='ignore') as client:
  # This call writes the response object into the message object
  # and returns the response headers on success, 400 otherwise.
  assert type(client.make_request('GET', message)) != int
  volume = Volume(message.response)

# The code above is equal to:
with SoundTouchClient(device, errors='ignore') as client:
  volume = client.volume()

The chosen URI scopen can be either OP_SCOPE_PUBLIC or OP_SCOPE_PRIVATE.

OP_SCOPE_PUBLIC = 0¶: URIs that are public and can be accessed by everyone will be declared with OP_SCOPE_PUBLIC.

OP_SCOPE_PRIVATE = 1¶: URIs that are private and can not be accessed by everyone.

SoundTouchUriType ¶

class boseapi.common.message.SoundTouchUriType(value)¶

A simple EnumWrapper defining the URI type.

OP_TYPE_EVENT = 4¶: URIs that are used to capture events can not be queried with a client. Therefore, the BoseWebSocket should be used.

OP_TYPE_REQUEST = 8¶: Standard URI type.

Keys ¶

class boseapi.common.message.Key(value)¶: This class contains all usable that can be ‘pressed’ on a BOSE-device. To use a key within an action of the client, type: client.action(Key.<KEY>)

Some keys in action:

from boseapi.all import new_device, Key, SoundTouchClient

device = new_device('127.0.0.1')
with SoundTouchClient(device) as client:
  # mute the device with the action() method
  client.action(Key.MUTE)
  # set the device's power on/off
  client.action(Key.POWER)
  # select the device's preset no. 1
  client.action(Key.PRESET_1)

Source ¶

class boseapi.common.message.Source(value)¶: Defines the Source of a ContentItem. With client.select_source(), the input Source of the current media can be changed.