vsslctrl 0.1.14.dev1__tar.gz → 0.2.1__tar.gz

{vsslctrl-0.1.14.dev1 → vsslctrl-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: vsslctrl
-Version: 0.1.14.dev1
+Version: 0.2.1
 Summary: Package for controlling VSSL's range of streaming amplifiers
 Author-email: vsslctrl <vsslcontrolled@proton.me>
 Classifier: Development Status :: 4 - Beta
@@ -18,28 +18,30 @@ Requires-Dist: pytest==8.1.1; extra == "dev"
 Requires-Dist: pytest_asyncio==0.23.6; extra == "dev"
 Provides-Extra: optional
 Requires-Dist: zeroconf==0.132.2; extra == "optional"
+Dynamic: license-file
 
 # vsslctrl
 
-Package for controlling [VSSL's](https://www.vssl.com/) range of streaming amplifiers.
+Python package for controlling [VSSL's](https://www.vssl.com/) range of streaming amplifiers.
 
 ## Coverage
 
-Tested on:
+Test suite run on:
 
-| Model       | Software Version | Note |
-| ------------|---------  | -------------
-| A.3x       | p15305.016.3701     | 
+| Model       | Software Version 
+| ------------|---------  
+| `A.1x`       | p15243.022.3703     
+| `A.3x`       | p15305.016.3701     
 
 
 Home Assistant [integration](https://github.com/vsslctrl/integration.home-assistant) with basic functionality working on:
 
 | Model       | Software Version | User Reported |
 | ------------|---------  | -------------
-| A.1       | p15265.033.3703    | ✔️
-| A.3       | p12013.141.3703     | ✔️
-| A.3x       | p15305.016.3701     | 
-| A.6x       | p15305.017.3701     | ✔️
+| `A.1`       | p15265.033.3703    | ✔️
+| `A.3`      | p12013.141.3703     | ✔️
+| `A.3x`       | p15305.016.3701     | 
+| `A.6x`       | p15305.017.3701     | ✔️
 
 
 ## Testers Needed
@@ -54,33 +56,28 @@ There should not be any *[VSSL Agent's](https://vssl.gitbook.io/vssl-rest-api/ge
 
  **`vsslctrl` is not endorsed or affiliated with [VSSL](https://www.vssl.com/) in any manner.**
 
-## TODOs
-
-* Better test coverage
-* A.1(x) testing - e.g output settings
-* More controls - e.g IR Control
-
 ## Basic Usage
 
 `vsslctrl` needs to be running inside a **[asyncio](https://docs.python.org/3/library/asyncio.html)** event loop.
 
-### A.1 Example
+### `A.1(x)` Example
 
 ```python
 import asyncio
-from vsslctrl import Vssl, DeviceModels, Zone, ZoneIDs
+from vsslctrl import Vssl
 
 async def main():
   
   # Represents a physical VSSL amplifier
-  vssl = Vssl(DeviceModels.A1)
+  vssl = Vssl()
+  
   a1 = vssl.add_zone('192.168.1.10')
 
   # Connect and initialise zone.
   await vssl.initialise()
 
   """Control Examples"""
-  # Print device name
+  # Print zone/device name
   print(a1.settings.name)
   # Set volume to 25%
   a1.volume = 25
@@ -95,21 +92,21 @@ async def main():
 asyncio.run(main())
 ```
 
-### A.3x Example
+### `A.3(x)` Example
 
 ```python
 import asyncio
-from vsslctrl import Vssl, DeviceModels, Zone, ZoneIDs
+from vsslctrl import Vssl
 
 async def main():
 	
   # Represents a physical VSSL amplifier
-  vssl = Vssl(DeviceModels.A3X)
+  vssl = Vssl()
 
   # Add each you wish to control
-  zone1 = vssl.add_zone('192.168.1.10', ZoneIDs.ZONE_1)
-  zone2 = vssl.add_zone('192.168.1.11', ZoneIDs.ZONE_2)
-  zone3 = vssl.add_zone('192.168.1.12', ZoneIDs.ZONE_3)
+  zone1 = vssl.add_zone('192.168.1.10')
+  zone2 = vssl.add_zone('192.168.1.11')
+  zone3 = vssl.add_zone('192.168.1.12')
   #... up to 6 zones for A.6(x)
 
   # Connect and initialise zones.
@@ -191,7 +188,7 @@ print(zone1.settings.name)
 ```python
 from vsslctrl.settings import ZoneSettings
 # Setting the zone name and wait for feedback
-future_name = vssl.event_bus.future(ZoneSettings.Events.NAME_CHANGE, zone1.id)
+future_name = vssl.event_bus.future(ZoneSettings.Events.NAME_CHANGE, zone1.host)
 zone1.settings.name = 'Bathroom' 
 # Helper to await a future with timeout
 new_name = await vssl.event_bus.wait_future(future_name)
@@ -205,37 +202,6 @@ print(zone1.settings.name)
 
 # API Reference
 
-# `DeviceModels`
-
-A device model has to be passed to VSSL so it knows internally what features are supported by the device.
-This might be removed in the future if we can differentiate different models from the API.
-
-| Property        | Description |
-| ------------|---------  | 
-| `A1X`       | A.1x      | 
-| `A3X`       | A.3x      | 
-| `A6X`       | A.6x      | 
-| `A1`        | A1        | 
-| `A3`        | A3        | 
-| `A6`        | A6        | 
-
-# `ZoneIDs`
-
-A `ZoneIDs` must be passed to each `zone` you which to control and it must match the zone on the VSSL device.
-
-If you are unsure of your `ZoneIDs` you could use the discovery helper to find out the correct mapping.
-
-| Property        | Description | A.1(x) | A.3(x) | A.6(x)
-| ------------|---------  |--------  | --------  | --------  |  
-| `A1`        |       |✔️ | | |
-| `ZONE_1`    | Zone 1   | | ✔️| ✔️|
-| `ZONE_2`    | Zone 2    |  | ✔️| ✔️|
-| `ZONE_3`    | Zone 3  |  | ✔️| ✔️|
-| `ZONE_4`    | Zone 4     |  | | ✔️|
-| `ZONE_5`    | Zone 5       |  | | ✔️|
-| `ZONE_6`    | Zone 6       |  | | ✔️|
-
-
 # `Vssl`
 
 | Property      	| Description | Type 		| 
@@ -257,13 +223,14 @@ vssl.factory_reset()
 
 ## `Vssl.settings`
 
+`A.1(x)` doesn't use `Vssl.settings.name` use `Zone.settings.name` instead.
+
 | Property      	| Description | Type 		| Model: Default |
 | ---------------------- 	| ----------- | ----------- | ----------- |
-| `name`     			 	| Device name |	`str` |
-| `bus_1_name`   			| Name of Bus 1        |	`str` | <ul><li>A.1: Optical Input</li><li>A.3x/6x: Not Used</li></ul>
-| `bus_2_name`        | Name of Bus 2        |  `str` | <ul><li>A.1: Coax Input</li><li>A.3x/6x: Optical Input</li></ul>
-| `bluetooth`        | Bluetooth enabled / disabled        |  `bool` |
-| `bluetooth_toggle()`        | Toggle Bluetooth        | `func`  |
+| `name`     			 	| Device name |	`str` | 
+| `bus_1_name`   			| Name of Bus 1        |	`str` | <ul><li>`A.1`: Optical Input</li><li>`A.3x`/`A.6x`: Not Used</li></ul>
+| `bus_2_name`        | Name of Bus 2        |  `str` | <ul><li>`A.1`: Coax Input</li><li>`A.3x`/`A.6x`: Optical Input</li></ul>
+| `status_light_mode`        | Status lights - Normal or Dark Mode        |  `str` | [`VsslSettings.StatusLightModes`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/settings.py#L17)
 
 ```python
 """Example"""
@@ -271,17 +238,35 @@ vssl.factory_reset()
 vssl.settings.name = 'My House'
 # Setting bus 2 name
 vssl.settings.bus_2_name = 'Optical Input'
+```
+
+## `Vssl.settings.bluetooth`
+
+`A.1(x)` only.
+
+| Property        | Description | Type    | Values    | 
+| ----------------------  | ----------- | ----------- |----------- |
+| `state`             | Bluetooth state | `int` readonly  | [`BluetoothSettings.States`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/settings.py#L130)
+| `on()`        | Enable Bluetooth        | `func`
+| `off()`        | Disable Bluetooth        | `func`
+| `clear_pairs()`        | Clear pairings        | `func`
+| `enter_pairing()`        | Enter pairing        | `func`
+| `exit_pairing()`        | Exit pairing        | `func`
+| `toggle()`        | Toggle Bluetooth        | `func`  |
+
+```python
+"""Example"""
 # Enable Bluetooth
-vssl.settings.bluetooth = True
+vssl.settings.bluetooth.on()
 # Toggle Bluetooth
-vssl.settings.bluetooth_toggle()
+vssl.settings.bluetooth.toggle()
 ```
 
 ## `Vssl.settings.power`
 
 | Property      	| Description | Type		| Values 		| 
 | ---------------------- 	| ----------- | ----------- |----------- |
-| `state`     			 	| Power state |	`int` readonly	| `VsslPowerSettings.States`
+| `state`     			 	| Power state |	`int` readonly	| [`VsslPowerSettings.States`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/settings.py#L243)
 | `adaptive`   			| Power adaptive        |	`bool`
 
 ```python
@@ -295,7 +280,7 @@ vssl.settings.power.adaptive = True
 
 | Property      	| Description | Type		| Values 		| 
 | ---------------------- 	| ----------- | ----------- |----------- |
-| `id`     			 	| Zone number / ID |	`int` readonly	| `ZoneIDs`
+| `id`     			 	| Zone number / ID |	`int` readonly	| [`ZoneIDs`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/data_structure.py#L75)
 | `host`   			| IP address        |	`str` readonly
 | `volume`   			| Volume        |	`int`  | `0...100`
 | `volume_raise([step=1])`   			| Raise volume by `step`       |	`func`  | step: `int` `1...100`
@@ -308,8 +293,9 @@ vssl.settings.power.adaptive = True
 | `next()`   			| Next track       |	`func`  |
 | `prev()`   			| Begining of track or previous track        |	`func`  |
 | `reboot()`   			| Reboot zone        |	`func`  |
-| `play_url([url], [all_zones])`   			| Play a URL       |	`func`  | url: `str`, all_zones: `bool`
+| `play_url([url], [all_zones], [volume])`   			| Play a URL       |	`func`  | url: `str`<br/>all_zones: `bool`<br/>volume: `int` `1...100`
 
+**Note:** `play_url()` is intended as a PA system. The zone will stop repsonding to commands (e.g transport, volume etc.)  until the requested file has finished playing.
 
 ```python
 """Examples"""
@@ -325,19 +311,19 @@ zone1.mute_toggle()
 zone1.pause()
 # Next track
 zone1.next()
-# Play a URL on this zone1
-zone1.play_url('http://soundbible.com/grab.php?id=2217&type=mp3')
-# Play a URL on all zones
+# Play a URL on this zone1 at 15% volume
+zone1.play_url('http://soundbible.com/grab.php?id=2217&type=mp3', volume=15)
+# Play a URL on all zones at current volume level
 zone1.play_url('http://soundbible.com/grab.php?id=2217&type=mp3', True)
 ```
 
 ## `Zone.transport`
 
-A VSSL amplifier can not start a stream except for playing a URL directly. This is a limitation of the hardware itself.
+A VSSL amplifier can not start a stream except for when using `zone.play_url()`. This is a limitation of the hardware itself.
 
 | Property      	| Description | Type		| Values 		| 
 | ---------------------- | ----------- | ----------- |----------- |
-| `state`     			 | Transport state. i.e Play, Stop, Pause | `int`	| `ZoneTransport.States`
+| `state`     			 | Transport state. i.e Play, Stop, Pause | `int`	| [`ZoneTransport.States`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/transport.py#L9)
 | `play()`   		 | Play   |	`func`  |
 | `stop()`   		 | Stop     |	`func`  |
 | `pause()`   		 | Pause     |	`func`  |
@@ -346,7 +332,7 @@ A VSSL amplifier can not start a stream except for playing a URL directly. This
 | `is_playing`   			| Is the zone playing        |	`bool` readonly
 | `is_stopped`   			| Is the zone stopped        |	`bool` readonly
 | `is_pasued`   			| Is the zone pasued        |	`bool` readonly
-| `is_repeat`     			 | Repeat state. i.e all, one, off | `int` readonly	| `ZoneTransport.Repeat`
+| `is_repeat`     			 | Repeat state. i.e all, one, off | `int` readonly	| [`ZoneTransport.Repeat`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/transport.py#L19)
 | `is_shuffle`   			| Is shuffle enabled       |	`bool` readonly
 | `has_next`   			| Is the next button enabled       |	`bool` readonly
 | `has_prev`   			| Is the prev button enabled       |	`bool` readonly
@@ -373,7 +359,7 @@ zone1.transport.state = ZoneTransport.States.PAUSE
 | `duration`     		| Length in miliseconds (ms) | `int` readonly	| 
 | `progress`     		| Current position in miliseconds (ms) | `int` readonly	|
 | `cover_art_url`     	| URL to cover art | `str` readonly	| 
-| `source`     			| Track source e.g Spotify |	`int` readonly	| `TrackMetadata.Sources`
+| `source`     			| Track source e.g Spotify |	`int` readonly	| [`TrackMetadata.Sources`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/track.py#L28)
 | `url`     	| URL of file or track | `str` readonly	| 
 
 
@@ -381,12 +367,12 @@ zone1.transport.state = ZoneTransport.States.PAUSE
 
 | Property      	| Description | Type		| Values 		| 
 | ---------------------- 	| ----------- | ----------- |----------- |
-| `source`     			 	| Change input source.<br/>Source to be played out the zones speakers |	`int`	| `InputRouter.Sources`
-| `priority`     			| Change input priority.<br/>Stream or local to have precedence  |	`int`	| `InputRouter.Priorities`
+| `source`     			 	| Change input source.<br/>Source to be played out the zones speakers |	`int`	| [`InputRouter.Sources`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/io.py#L35)
+| `priority`     			| Change input priority.<br/>Stream or local to have precedence  |	`int`	| [`InputRouter.Priorities`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/io.py#L23)
 
 
-### A.1(x) Source Routing Order
-A.1 and A.1x don't support manually changing the input source. Instead a fixed source routing order is used:
+### `A.1(x)` Source Routing Order
+`A.1` and `A.1x` don't support manually changing the input source. Instead a fixed source routing order is used:
   
   1. Optical Input
   2. Coaxial Input
@@ -412,14 +398,12 @@ zone1.input.priority = InputRouter.Priorities.LOCAL
 
 ## `Zone.group`
 
-Unsupported on X series amplifiers.
-
 | Property      	| Description | Type		| Values 		| 
 | ---------------------- 	| ----------- | ----------- |----------- |
-| `source`     			 	| Zone ID of group master / source |	`int` readonly	| `ZoneIDs`
+| `source`     			 	| Zone ID of group master / source |	`int` readonly	| [`ZoneIDs`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/data_structure.py#L75)
 | `is_master`   			| This zone is the group master        |	`bool` readonly
-| `add_member()`   			| Add zone to group / create group |	`func`  | `ZoneIDs`
-| `remove_member()`   		| Remove zone from group      |	`func`  | `ZoneIDs`
+| `add_member()`   			| Add zone to group / create group |	`func`  | [`ZoneIDs`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/data_structure.py#L75)
+| `remove_member()`   		| Remove zone from group      |	`func`  | [`ZoneIDs`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/data_structure.py#L75)
 | `dissolve()`   			| Dissolve group / remove all members       |	`func`  |
 | `leave()`   				| Leave the group if a member       |	`func`  |
 | `is_party_zone_member`  | Member of Party Zone |  `bool`  |
@@ -443,7 +427,7 @@ zone1.group.is_party_zone_member_toggle()
 
 | Property      	| Description | Type		| Values 		| Default |
 | ---------------------- 	| ----------- | ----------- |----------- |----------- |
-| `source`     			 	| Where the AO is routed from. i.e stream, optical input or off |	`int`	| `AnalogOutput.Sources` | `Off`
+| `source`     			 	| Where the AO is routed from. i.e stream, optical input or off |	`int`	| [`AnalogOutput.Sources`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/io.py#L150) | `Off`
 | `is_fixed_volume`   			| Fix the output volume. Output wont respond to volume control        |	`bool` | |`False`
 | `is_fixed_volume_toggle()`   			| Toggle fixed volume      |	`func`  |
 
@@ -466,7 +450,7 @@ zone1.analog_output.is_fixed_volume = True
 | `name`     			 	| Name |	`str`	| 
 | `disabled`   			| Disable the zone        |	`bool` || `False`
 | `disabled_toggle()`   			| disable / enable        |	`func`  |
-| `mono`   			| Set output to mono or stereo        |	`int`  | `ZoneSettings.StereoMono` | `Stereo`
+| `mono`   			| Set output to mono or stereo        |	`int`  | [`ZoneSettings.StereoMono`](https://github.com/vsslctrl/vsslctrl/blob/644586fa183def1f23f0bfd239454fa8422e3dbe/vsslctrl/settings.py#L310) | `STEREO`
 | `mono_toggle()`   			| Toggle mono or stereo        |	`func`  |
 
 ```python
@@ -474,9 +458,9 @@ zone1.analog_output.is_fixed_volume = True
 # Set name
 zone1.settings.name = 'Living Room'
 # Disable Zone
-zone1.disabled = True
+zone1.settings.disabled = True
 # Toggle mono output
-zone1.mono_toggle()
+zone1.settings.mono_toggle()
 ```
 
 ## `Zone.settings.analog_input`
@@ -509,7 +493,7 @@ zone1.settings.analog_input.fixed_gain = 50
 # Set default on volume to 50%
 zone1.settings.volume.default_on = 50
 # Set maximum volume for left channel to 75%
-zone1.settings.volume.default_on = 75
+zone1.settings.volume.max_left = 75
 ```
 
 ## `Zone.settings.eq`
@@ -538,7 +522,7 @@ zone1.settings.eq.khz1_db = -2
 
 ## `Zone.settings.subwoofer`
 
-* **A.1 and A.1x only**
+* **`A.1` and `A.1x` only**
 * Set `0` for full frequency range
 
 | Property        | Description | Type    | Values    | Default |
@@ -561,12 +545,9 @@ Motivation for this project was to integrate VSSLs amplifiers into [Home Assista
 
 ## Known Issues & Limitiations
 
-* Not tested on A.1x or original A series range of amplifiers (testers welcome)
 * VSSL can not start a stream except for playing a URL directly. This is a limitation of the hardware itself.
 * Not all sources set the volume to 0 when the zone is muted
 * Airplay `Zone.track.progress` is not available.
-* Cant stop a URL playback, feedback is worng at least
 * VSSL likes to cache old track metadata. For example when playing a URL after Spotify, often the device will respond with the previous (Spotify) tracks metadata
 * `stop()` is intended to disconnect the client and pause the stream. Doesn’t always function this way, depending on stream source
-* Occasionally a zones might stop responding to certain commands, issuing the `reboot` command generally corrects