vsslctrl 0.1.12.dev1__tar.gz → 0.1.14.dev1__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: vsslctrl
-Version: 0.1.12.dev1
+Version: 0.1.14.dev1
 Summary: Package for controlling VSSL's range of streaming amplifiers
 Author-email: vsslctrl <vsslcontrolled@proton.me>
 Classifier: Development Status :: 4 - Beta
@@ -76,7 +76,7 @@ async def main():
   vssl = Vssl(DeviceModels.A1)
   a1 = vssl.add_zone('192.168.1.10')
 
-  # Connect and initiate zones.
+  # Connect and initialise zone.
   await vssl.initialise()
 
   """Control Examples"""
@@ -112,7 +112,7 @@ async def main():
   zone3 = vssl.add_zone('192.168.1.12', ZoneIDs.ZONE_3)
   #... up to 6 zones for A.6(x)
 
-  # Connect and initiate zones.
+  # Connect and initialise zones.
   await vssl.initialise()
 
   """Control Examples"""
@@ -134,6 +134,77 @@ async def main():
 asyncio.run(main())
 ```
 
+### Device Discovery Helper
+
+You can discover VSSL devices on the network using [mDNS](https://wikipedia.org/wiki/Multicast_DNS) / Bonjour if you have the [`zeroconf`](https://pypi.org/project/zeroconf/) package installed.
+
+This uses airplay service string `_airplay._tcp.local.`, therefore airplay needs to available and will not work across VLANs without other provisions.
+
+**Note:** This is designed to be a helper and its not recommended to be used for the initialization of the VSSL class.
+
+```python
+import asyncio
+from vsslctrl import Vssl
+
+async def main():
+  
+  print(await Vssl.discover())
+
+  """
+    {
+        'XXXXXXXXXXXX': [
+            {
+                'host': '192.168.168.25',
+                'name': 'Living Room',
+                'model': 'A1x',
+                'mac_addr': 'AA:BB:CC:DD:EE:FF',
+                'zone_id': '7',
+                'serial': 'XXXXXXXXXXXX'
+            }
+        ]
+    }
+
+  """
+
+asyncio.run(main())
+```
+
+
+# API Functionality
+
+Most functionality is achieved via `getters` and `setters` of the two main classes `Vssl`, `Zone`. 
+
+The classes will update the physical VSSL device when setting a property and once feedback has been received, the classes internal state will be updated. For example:
+
+```python
+# Setting the zone name
+zone1.settings.name = 'Living Room'
+>>> 'Old Zone Name'
+
+# Printing zone name
+print(zone1.settings.name)
+>>> 'Living Room'
+```
+
+**Important** in the above example, `zone1.settings.name` won't be set to its new value until after the VSSL device has changed the name and the `Zone` class has received confirmation feedback. If you need to wait for the value change, you can await a `[property_name]_CHANGE` events as below:
+
+```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)
+zone1.settings.name = 'Bathroom' 
+# Helper to await a future with timeout
+new_name = await vssl.event_bus.wait_future(future_name)
+# Printing zone name
+print(new_name)
+>>> 'Bathroom'
+# or
+print(zone1.settings.name)
+>>> 'Bathroom'
+```
+
+# API Reference
+
 # `DeviceModels`
 
 A device model has to be passed to VSSL so it knows internally what features are supported by the device.
@@ -150,35 +221,20 @@ This might be removed in the future if we can differentiate different models fro
 
 # `ZoneIDs`
 
-| Property        | Description |
-| ------------|---------  | 
-| `A1`        | A.1(x) Only      | 
-| `ZONE_1`    | Zone 1 of A.3(x) and A.6(x)   | 
-| `ZONE_2`    | Zone 2 of A.3(x) and A.6(x)    | 
-| `ZONE_3`    | Zone 3 of A.3(x) and A.6(x)  | 
-| `ZONE_4`    | Zone 4 of A.6(x)     | 
-| `ZONE_5`    | Zone 5 of A.6(x)       | 
-| `ZONE_6`    | Zone 6 of A.6(x)       | 
+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.
 
-# API
-
-Most functionality is achieved via `getters` and `setters` of the two main classes `Vssl`, `Zone`. 
-
-The classes will update the physical VSSL device when setting a property and once feedback has been received, the classes internal state will be updated. For example:
-
-```python
-# Setting the zones name
-zone1.settings.name = 'Living Room'
->>> None
-
-# Printing zone name
-zone_name = zone1.settings.name
-print(zone_name)
->>> 'Living Room'
-```
+| 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       |  | | ✔️|
 
-**Important** in the above example, `zone1.settings.name` wont be set to its new value until after the VSSL device has changed the name and the `Zone` class has received confirmation feedback. If you need to wait for the value change, you can await a `[property_name]_CHANGE` events.
 
 # `Vssl`
 

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/README.md

@@ -55,7 +55,7 @@ async def main():
   vssl = Vssl(DeviceModels.A1)
   a1 = vssl.add_zone('192.168.1.10')
 
-  # Connect and initiate zones.
+  # Connect and initialise zone.
   await vssl.initialise()
 
   """Control Examples"""
@@ -91,7 +91,7 @@ async def main():
   zone3 = vssl.add_zone('192.168.1.12', ZoneIDs.ZONE_3)
   #... up to 6 zones for A.6(x)
 
-  # Connect and initiate zones.
+  # Connect and initialise zones.
   await vssl.initialise()
 
   """Control Examples"""
@@ -113,6 +113,77 @@ async def main():
 asyncio.run(main())
 ```
 
+### Device Discovery Helper
+
+You can discover VSSL devices on the network using [mDNS](https://wikipedia.org/wiki/Multicast_DNS) / Bonjour if you have the [`zeroconf`](https://pypi.org/project/zeroconf/) package installed.
+
+This uses airplay service string `_airplay._tcp.local.`, therefore airplay needs to available and will not work across VLANs without other provisions.
+
+**Note:** This is designed to be a helper and its not recommended to be used for the initialization of the VSSL class.
+
+```python
+import asyncio
+from vsslctrl import Vssl
+
+async def main():
+  
+  print(await Vssl.discover())
+
+  """
+    {
+        'XXXXXXXXXXXX': [
+            {
+                'host': '192.168.168.25',
+                'name': 'Living Room',
+                'model': 'A1x',
+                'mac_addr': 'AA:BB:CC:DD:EE:FF',
+                'zone_id': '7',
+                'serial': 'XXXXXXXXXXXX'
+            }
+        ]
+    }
+
+  """
+
+asyncio.run(main())
+```
+
+
+# API Functionality
+
+Most functionality is achieved via `getters` and `setters` of the two main classes `Vssl`, `Zone`. 
+
+The classes will update the physical VSSL device when setting a property and once feedback has been received, the classes internal state will be updated. For example:
+
+```python
+# Setting the zone name
+zone1.settings.name = 'Living Room'
+>>> 'Old Zone Name'
+
+# Printing zone name
+print(zone1.settings.name)
+>>> 'Living Room'
+```
+
+**Important** in the above example, `zone1.settings.name` won't be set to its new value until after the VSSL device has changed the name and the `Zone` class has received confirmation feedback. If you need to wait for the value change, you can await a `[property_name]_CHANGE` events as below:
+
+```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)
+zone1.settings.name = 'Bathroom' 
+# Helper to await a future with timeout
+new_name = await vssl.event_bus.wait_future(future_name)
+# Printing zone name
+print(new_name)
+>>> 'Bathroom'
+# or
+print(zone1.settings.name)
+>>> 'Bathroom'
+```
+
+# API Reference
+
 # `DeviceModels`
 
 A device model has to be passed to VSSL so it knows internally what features are supported by the device.
@@ -129,35 +200,20 @@ This might be removed in the future if we can differentiate different models fro
 
 # `ZoneIDs`
 
-| Property        | Description |
-| ------------|---------  | 
-| `A1`        | A.1(x) Only      | 
-| `ZONE_1`    | Zone 1 of A.3(x) and A.6(x)   | 
-| `ZONE_2`    | Zone 2 of A.3(x) and A.6(x)    | 
-| `ZONE_3`    | Zone 3 of A.3(x) and A.6(x)  | 
-| `ZONE_4`    | Zone 4 of A.6(x)     | 
-| `ZONE_5`    | Zone 5 of A.6(x)       | 
-| `ZONE_6`    | Zone 6 of A.6(x)       | 
+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.
 
-# API
-
-Most functionality is achieved via `getters` and `setters` of the two main classes `Vssl`, `Zone`. 
-
-The classes will update the physical VSSL device when setting a property and once feedback has been received, the classes internal state will be updated. For example:
-
-```python
-# Setting the zones name
-zone1.settings.name = 'Living Room'
->>> None
-
-# Printing zone name
-zone_name = zone1.settings.name
-print(zone_name)
->>> 'Living Room'
-```
+| 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       |  | | ✔️|
 
-**Important** in the above example, `zone1.settings.name` wont be set to its new value until after the VSSL device has changed the name and the `Zone` class has received confirmation feedback. If you need to wait for the value change, you can await a `[property_name]_CHANGE` events.
 
 # `Vssl`
 

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vsslctrl"
-version = "0.1.12.dev1"
+version = "0.1.14.dev1"
 description = "Package for controlling VSSL's range of streaming amplifiers"
 authors = [
   { name="vsslctrl", email="vsslcontrolled@proton.me" },

vsslctrl-0.1.14.dev1/tests/test_event_bus.py

@@ -0,0 +1,206 @@
+import asyncio
+import pytest
+import pytest_asyncio
+from vsslctrl.event_bus import EventBus
+
+
+class TestEventBus:
+    @pytest_asyncio.fixture(autouse=True)
+    async def event_bus(self):
+        bus = EventBus()
+        yield bus
+        bus.stop()  # Ensure the event bus is stopped after each test
+
+    @pytest.mark.asyncio
+    async def test_event_bus(self, event_bus):
+        # Instantiate the EventBus
+        # event_bus = EventBus()
+
+        async def publish_with_entity(self, entity=None):
+            # Define a callback function to be subscribed to the event
+            async def callback(data, *args, **kwargs):
+                callback.called = True
+                callback.data = data
+
+            # Subscribe the callback function to the event
+            event_type = "test_event"
+            event_bus.subscribe(event_type, callback, entity)
+            assert event_bus.subscribers.get(event_type) is not None
+            assert len(event_bus.subscribers.get(event_type)) == 1
+            assert event_bus.subscribers.get(event_type)[0][0] == callback
+
+            try:
+                # Publish the event
+                event_data = "test_data"
+                event_bus.publish(event_type, data=event_data, entity=entity)
+
+                # Wait for a short time to allow the event to be processed
+                await asyncio.sleep(0.1)
+
+                # Assert that the callback function has been called
+                assert hasattr(callback, "called") and callback.called is True
+                assert getattr(callback, "data") == event_data
+            finally:
+                # Unsubscribe the callback function
+                event_bus.unsubscribe(event_type, callback)
+                # Ensure the callback function was not called after unsubscribing
+                assert len(event_bus.subscribers.get(event_type)) == 0
+
+        await publish_with_entity(None)
+        await publish_with_entity(1)
+        await publish_with_entity("test")
+
+    @pytest.mark.asyncio
+    async def test_event_bus_wildcard_event_type(self, event_bus):
+        # Define a callback function to be subscribed to the event
+        async def callback(data: int = 0, *args, **kwargs):
+            callback.data = data + 1
+
+        event_bus.subscribe(event_bus.WILDCARD, callback, 1)
+        # Ensure the callback function is subscribed
+        assert len(event_bus.subscribers.get(event_bus.WILDCARD)) == 1
+
+        try:
+            # Publish an event
+            event_bus.publish("random_event_1", 1, 0)
+            # Wait for a short time to allow the event to be processed
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 1
+
+            # Publish an event
+            event_bus.publish("random_event_2.other", 1, 20)
+            # Wait for a short time to allow the event to be processed
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 21
+
+            # Publish an event with different ID
+            event_bus.publish("random_event_2", 2, 30)
+            # Wait for a short time to allow the event to be processed
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 21
+
+        finally:
+            # Unsubscribe the callback function
+            event_bus.unsubscribe(event_bus.WILDCARD, callback)
+            # Ensure the callback function was not called after unsubscribing
+            assert len(event_bus.subscribers.get(event_bus.WILDCARD)) == 0
+
+    @pytest.mark.asyncio
+    async def test_event_bus_scoped_wildcard_event_type(self, event_bus):
+        # Define a callback function to be subscribed to the event
+        async def callback(data: int = 0, *args, **kwargs):
+            callback.data = data + 1
+
+        event_type = "zone.api." + event_bus.WILDCARD
+
+        event_bus.subscribe(event_type, callback, 1)
+        # Ensure the callback function is subscribed
+        assert len(event_bus.subscribers.get(event_type)) == 1
+
+        try:
+            # Publish an event
+            event_bus.publish("zone.api.connected", 1, 0)
+            # Wait for a short time to allow the event to be processed
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 1
+
+            # Publish an event
+            event_bus.publish("zone.api.disconnected", 1, 20)
+            # Wait for a short time to allow the event to be processed
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 21
+
+            # Publish an different event
+            event_bus.publish("zone.api", 1, 30)
+            # Wait for a short time to allow the event to be processed
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 21  # should be unchanged
+
+            # Publish an different event
+            event_bus.publish("zone", 1, 40)
+            # Wait for a short time to allow the event to be processed
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 21  # should be unchanged
+
+        finally:
+            # Unsubscribe the callback function
+            event_bus.unsubscribe(event_type, callback)
+            # Ensure the callback function was not called after unsubscribing
+            assert len(event_bus.subscribers.get(event_type)) == 0
+
+    @pytest.mark.asyncio
+    async def test_event_bus_wildcard_entity(self, event_bus):
+        # Define a callback function to be subscribed to the event
+        async def callback(data: int = 0, *args, **kwargs):
+            callback.data = data + 1
+
+        test_event = "test_event"
+
+        event_bus.subscribe(test_event, callback, event_bus.WILDCARD)
+        # Ensure the callback function is subscribed
+        assert len(event_bus.subscribers.get(test_event)) == 1
+
+        try:
+            # Publish an event
+            event_bus.publish(test_event, 1, 0)
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 1
+
+            # Publish an event with different ID
+            event_bus.publish(test_event, 2, 20)
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 21
+
+            # Publish an event with different ID
+            event_bus.publish("different_event", 2, 20)
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 21
+
+        finally:
+            # Unsubscribe the callback function
+            event_bus.unsubscribe(test_event, callback)
+            # Ensure the callback function was not called after unsubscribing
+            assert len(event_bus.subscribers.get(test_event)) == 0
+
+    @pytest.mark.asyncio
+    async def test_event_bus_wildcard(self, event_bus):
+        # Define a callback function to be subscribed to the event
+        async def callback(data: int = 0, *args, **kwargs):
+            callback.data = data + 1
+
+        event_bus.subscribe(event_bus.WILDCARD, callback, event_bus.WILDCARD)
+        # Ensure the callback function is subscribed
+        assert len(event_bus.subscribers.get(event_bus.WILDCARD)) == 1
+
+        try:
+            # Publish an event
+            event_bus.publish("random_event_1", 1, 0)
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 1
+
+            # Publish an event with different ID
+            event_bus.publish("random_event_2", 2, 20)
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 21
+
+            # Publish an event with different ID
+            event_bus.publish("random_event_3", 3, 30)
+            await asyncio.sleep(0.1)
+            assert getattr(callback, "data") == 31
+        finally:
+            # Unsubscribe the callback function
+            event_bus.unsubscribe(event_bus.WILDCARD, callback)
+            # Ensure the callback function was not called after unsubscribing
+            assert len(event_bus.subscribers.get(event_bus.WILDCARD)) == 0
+
+    @pytest.mark.asyncio
+    async def test_event_bus_future(self, event_bus):
+        # Subscribe the callback function to the event
+        event_type = "test_future_event"
+        future = event_bus.future(event_type, 1)
+        # Publish event
+        event_data = "test_data"
+        event_bus.publish(event_type, 1, event_data)
+        assert await future == event_data
+        # Make sure future is unsubscribed
+        assert len(event_bus.subscribers.get(event_type)) == 0

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl/__init__.py

@@ -1,4 +1,4 @@
-VSSL_VERSION = "0.1.12.dev1"
+VSSL_VERSION = "0.1.14.dev1"
 VSSL_NAME = "VSSL"
 
 from .core import Vssl

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl/api_alpha.py

@@ -39,6 +39,12 @@ class APIAlpha(APIBase):
         self.vssl = vssl_host
         self.zone = zone
 
+    #
+    # Send event on event bus
+    #
+    def _event_publish(self, event_type, data=None):
+        self.zone._event_publish(event_type, (self.zone.host, self.TCP_PORT))
+
     #
     # Send keep alive
     #

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl/api_base.py

@@ -45,6 +45,17 @@ class APIBase(ABC):
 
     FRIST_BYTE = 1
 
+    #
+    # API Events
+    #
+    class Events:
+        PREFIX = "zone.api."
+        CONNECTING = PREFIX + "connecting"
+        CONNECTED = PREFIX + "connected"
+        DISCONNECTING = PREFIX + "disconnecting"
+        DISCONNECTED = PREFIX + "disconnected"
+        RECONNECTING = PREFIX + "reconnecting"
+
     def __init__(self, host, port):
         self.host = host
         self.port = port
@@ -89,6 +100,7 @@ class APIBase(ABC):
             return self.connected
 
         self._connecting = True
+        self._event_publish(self.Events.CONNECTING)
 
         try:
             self._log_debug(f"Attemping connection to {self.host}:{self.port}")
@@ -98,6 +110,7 @@ class APIBase(ABC):
 
             # Connected
             self.connection_event.set()
+            self._event_publish(self.Events.CONNECTED)
 
             # cancel any reconnecting loops
             self._cancel_keep_connected()
@@ -140,6 +153,7 @@ class APIBase(ABC):
     @final
     async def disconnect(self):
         self._disconnecting = True
+        self._event_publish(self.Events.DISCONNECTING)
 
         # cancel any reconnecting loops
         self._cancel_keep_connected()
@@ -152,9 +166,14 @@ class APIBase(ABC):
 
         if self._writer:
             try:
+                # If there's unsent data in the buffer, wait_closed() might hang.
+                # Fix: Call await self._writer.drain() before closing to ensure all data is sent
+                await self._writer.drain()
+
                 # Writer hangs on disconnect sometimes
-                self._writer.close()
-                await asyncio.wait_for(self._writer.wait_closed(), self.TIMEOUT)
+                if not self._writer.is_closing():
+                    self._writer.close()
+                    await asyncio.wait_for(self._writer.wait_closed(), self.TIMEOUT)
 
             except asyncio.CancelledError:
                 self._log_debug(f"writer close timeout")
@@ -168,6 +187,10 @@ class APIBase(ABC):
                 self._log_error(f"Unexpected error occurred while disconnecting: {e}")
                 # Handle unexpected errors
             finally:
+                # If nothing works, you may need to forcefully close the socket:
+                # if hasattr(self._writer, 'transport'):
+                # self._writer.transport.close()
+
                 self._writer = None
 
         self._reader = None
@@ -176,6 +199,8 @@ class APIBase(ABC):
 
         self._disconnecting = False
 
+        self._event_publish(self.Events.DISCONNECTED)
+
         return not self.connected
 
     #
@@ -184,7 +209,9 @@ class APIBase(ABC):
     @final
     async def reconnect(self):
         if not self._reconnecting and not self._is_keep_connected_running():
+            self._event_publish(self.Events.RECONNECTING)
             await self.disconnect()
+            await asyncio.sleep(1)
             self._keep_connected()
 
     #
@@ -306,6 +333,13 @@ class APIBase(ABC):
     async def _read_byte_stream(self):
         pass
 
+    #
+    # Send event on event bus
+    #
+    @abstractmethod
+    def _event_publish(self, event_type, data=None):
+        pass
+
     #
     # Send a keep alive
     #

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl/api_bravo.py

@@ -23,6 +23,12 @@ class APIBravo(APIBase):
         self.vssl = vssl_host
         self.zone = zone
 
+    #
+    # Send event on event bus
+    #
+    def _event_publish(self, event_type, data=None):
+        self.zone._event_publish(event_type, (self.zone.host, self.TCP_PORT))
+
     #
     # Send keep alive
     #

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl/core.py

@@ -28,7 +28,6 @@ class Vssl:
         MODEL_CHANGE = PREFIX + "model_changed"
         SW_VERSION_CHANGE = PREFIX + "sw_version_changed"
         SERIAL_CHANGE = PREFIX + "serial_changed"
-        ALL = EventBus.WILDCARD
 
     def __init__(self, model: Models):
         self.event_bus = EventBus()
@@ -50,7 +49,7 @@ class Vssl:
     #
     async def initialise(self, init_timeout: int = 10):
         if len(self.zones) < 1:
-            raise VsslCtrlException("Add atleast one zone before initializing")
+            raise VsslCtrlException("Add minimum one zone before initializing")
 
         zones_to_init = self.zones.copy()
 
@@ -64,9 +63,9 @@ class Vssl:
             await first_zone.initialise()
 
             # Wait until we have some basic infomation
-            await self.event_bus.wait_future(future_serial)
-            await self.event_bus.wait_future(future_sw_version)
-            await self.event_bus.wait_future(future_name)
+            await self.event_bus.wait_future(future_serial, init_timeout)
+            await self.event_bus.wait_future(future_sw_version, init_timeout)
+            await self.event_bus.wait_future(future_name, init_timeout)
 
             # Check we haven't added too many zones
             if len(self.zones) > self.model.zone_count:
@@ -92,7 +91,7 @@ class Vssl:
             raise
 
         except asyncio.TimeoutError:
-            message = f"Timeout during VSSL initialization. Are any zones avaiable?"
+            message = f"Timeout during VSSL initialization. Are any zones available?"
             self._log_critical(message)
             await first_zone.disconnect()
             raise VsslCtrlException(message)
@@ -114,17 +113,14 @@ class Vssl:
     #
     # Discover host on the network using zero_conf package
     #
-    async def discover(self, *args):
-        try:
-            check_zeroconf_availability()
+    @staticmethod
+    async def discover(*args):
+        check_zeroconf_availability()
 
-            from .discovery import VsslDiscovery
+        from .discovery import VsslDiscovery
 
-            service = VsslDiscovery(*args)
-            return await service.discover()
-        except ZeroConfNotInstalled as e:
-            self._log_error(e)
-            raise
+        service = VsslDiscovery(*args)
+        return await service.discover()
 
     #
     # Update a property and fire an event
@@ -257,7 +253,7 @@ class Vssl:
             return None
 
     #
-    # Get a Zone that is connected
+    # Get a zone that is connected
     #
     def get_connected_zone(self):
         if self.zones:
@@ -265,6 +261,14 @@ class Vssl:
                 zone = self.zones[zone_id]
                 if zone.connected:
                     return zone
+        self._log_error("There are no connected zones.")
+
+    #
+    # Has a connected zone
+    #
+    @property
+    def connected(self):
+        return True if self.get_connected_zone() else False
 
     #
     # Get the device name

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl/device.py

@@ -322,6 +322,10 @@ class Models(VsslEnum):
 
     @classmethod
     def get_model_by_name(cls, name):
+        # Return None immediately if input is None
+        if name is None:
+            return None
+
         # Preprocess input name: convert to lowercase and remove dots
         name_cleaned = name.lower().replace(".", "")
 

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl/event_bus.py

@@ -1,14 +1,11 @@
 import asyncio
 import traceback
+import fnmatch
 from enum import IntEnum
 from typing import Callable
 from .exceptions import VsslCtrlException
 from .decorators import logging_helpers
 
-#
-# Event Bus
-#
-
 
 @logging_helpers("EventBus:")
 class EventBus:
@@ -23,6 +20,10 @@ class EventBus:
 
         self.process = asyncio.create_task(self.process_events())
 
+    # Helper for wildcard matching, so we can use partial wildcards. e.g zone.api.connected
+    def _matches_pattern(self, event_type, pattern):
+        return fnmatch.fnmatch(event_type, pattern)
+
     #
     # Stop
     #
@@ -67,7 +68,8 @@ class EventBus:
 
         async def future_callback(data, *args):
             nonlocal future
-            future.set_result(data)
+            if not future.done():  # Ensure the future is not already resolved
+                future.set_result(data)
 
         self.subscribe(event_type, future_callback, entity, once=True)
 
@@ -115,12 +117,8 @@ class EventBus:
         event_type = event_type.lower()
         await self.event_queue.put((event_type, entity, data))
 
-    #
-    # Process Events
-    #
     async def process_events(self):
         self._log_debug(f"starting event processing")
-
         self.running = True
         while self.running:
             try:
@@ -136,23 +134,22 @@ class EventBus:
                         message += str(data)
                     self._log_debug(message)
 
-                for event in [event_type, self.WILDCARD]:
-                    if event in self.subscribers:
-                        for callback, subscribed_entity, once in self.subscribers[
-                            event
-                        ]:
-                            if entity is None or subscribed_entity in {
-                                entity,
-                                self.WILDCARD,
-                            }:
-                                await callback(data, entity, event_type)
-                                if once:
-                                    self.unsubscribe(event, callback)
+                # Check for matching subscribers, including wildcards.
+                # e.g "zone.*", "zone.api.*"
+                matched_subscribers = []
+                for pattern in self.subscribers:
+                    if self._matches_pattern(event_type, pattern):
+                        matched_subscribers.extend(self.subscribers[pattern])
+
+                for callback, subscribed_entity, once in matched_subscribers:
+                    if entity is None or subscribed_entity in {entity, self.WILDCARD}:
+                        await callback(data, entity, event_type)
+                        if once:
+                            self.unsubscribe(pattern, callback)
 
             except asyncio.CancelledError:
                 break
             except Exception as e:
-                # Capture the traceback as a string
                 traceback_str = traceback.format_exc()
                 self._log_error(
                     f"exception occurred processing event: {e}\n{traceback_str}"

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl/zone.py

@@ -29,7 +29,6 @@ class Zone:
     # Zone Events
     #
     class Events:
-        ALL = "*"
         PREFIX = "zone."
         INITIALISED = PREFIX + "initialised"
         ID_RECEIVED = PREFIX + "id_received"
@@ -79,7 +78,7 @@ class Zone:
         )
 
     # Initialise
-    async def initialise(self):
+    async def initialise(self, init_timeout: int = 10):
         # Data we require from the device
         future_id = self.vssl.event_bus.future(self.Events.ID_RECEIVED, self.id)
         future_serial = self.vssl.event_bus.future(self.Events.SERIAL_RECEIVED, self.id)
@@ -106,13 +105,15 @@ class Zone:
 
         try:
             # Wait for the ID, serial and name to be returned from the device
-            received_id = await self.vssl.event_bus.wait_future(future_id)
-            received_serial = await self.vssl.event_bus.wait_future(future_serial)
-            await self.vssl.event_bus.wait_future(future_name)
+            received_id = await self.vssl.event_bus.wait_future(future_id, init_timeout)
+            received_serial = await self.vssl.event_bus.wait_future(
+                future_serial, init_timeout
+            )
+            await self.vssl.event_bus.wait_future(future_name, init_timeout)
         except asyncio.TimeoutError:
-            message = f"Zone {self.id}: initialization timeout. Is the zone avaiable?"
+            message = f"Zone {self.id}: initialization timeout. Is the zone available?"
             self._log_critical(message)
-            await first_zone.disconnect()
+            await self.disconnect()
             raise ZoneError(message)
 
         # Confirm the zone id is matches the returned zone ID

{vsslctrl-0.1.12.dev1 → vsslctrl-0.1.14.dev1}/vsslctrl.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: vsslctrl
-Version: 0.1.12.dev1
+Version: 0.1.14.dev1
 Summary: Package for controlling VSSL's range of streaming amplifiers
 Author-email: vsslctrl <vsslcontrolled@proton.me>
 Classifier: Development Status :: 4 - Beta
@@ -76,7 +76,7 @@ async def main():
   vssl = Vssl(DeviceModels.A1)
   a1 = vssl.add_zone('192.168.1.10')
 
-  # Connect and initiate zones.
+  # Connect and initialise zone.
   await vssl.initialise()
 
   """Control Examples"""
@@ -112,7 +112,7 @@ async def main():
   zone3 = vssl.add_zone('192.168.1.12', ZoneIDs.ZONE_3)
   #... up to 6 zones for A.6(x)
 
-  # Connect and initiate zones.
+  # Connect and initialise zones.
   await vssl.initialise()
 
   """Control Examples"""
@@ -134,6 +134,77 @@ async def main():
 asyncio.run(main())
 ```
 
+### Device Discovery Helper
+
+You can discover VSSL devices on the network using [mDNS](https://wikipedia.org/wiki/Multicast_DNS) / Bonjour if you have the [`zeroconf`](https://pypi.org/project/zeroconf/) package installed.
+
+This uses airplay service string `_airplay._tcp.local.`, therefore airplay needs to available and will not work across VLANs without other provisions.
+
+**Note:** This is designed to be a helper and its not recommended to be used for the initialization of the VSSL class.
+
+```python
+import asyncio
+from vsslctrl import Vssl
+
+async def main():
+  
+  print(await Vssl.discover())
+
+  """
+    {
+        'XXXXXXXXXXXX': [
+            {
+                'host': '192.168.168.25',
+                'name': 'Living Room',
+                'model': 'A1x',
+                'mac_addr': 'AA:BB:CC:DD:EE:FF',
+                'zone_id': '7',
+                'serial': 'XXXXXXXXXXXX'
+            }
+        ]
+    }
+
+  """
+
+asyncio.run(main())
+```
+
+
+# API Functionality
+
+Most functionality is achieved via `getters` and `setters` of the two main classes `Vssl`, `Zone`. 
+
+The classes will update the physical VSSL device when setting a property and once feedback has been received, the classes internal state will be updated. For example:
+
+```python
+# Setting the zone name
+zone1.settings.name = 'Living Room'
+>>> 'Old Zone Name'
+
+# Printing zone name
+print(zone1.settings.name)
+>>> 'Living Room'
+```
+
+**Important** in the above example, `zone1.settings.name` won't be set to its new value until after the VSSL device has changed the name and the `Zone` class has received confirmation feedback. If you need to wait for the value change, you can await a `[property_name]_CHANGE` events as below:
+
+```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)
+zone1.settings.name = 'Bathroom' 
+# Helper to await a future with timeout
+new_name = await vssl.event_bus.wait_future(future_name)
+# Printing zone name
+print(new_name)
+>>> 'Bathroom'
+# or
+print(zone1.settings.name)
+>>> 'Bathroom'
+```
+
+# API Reference
+
 # `DeviceModels`
 
 A device model has to be passed to VSSL so it knows internally what features are supported by the device.
@@ -150,35 +221,20 @@ This might be removed in the future if we can differentiate different models fro
 
 # `ZoneIDs`
 
-| Property        | Description |
-| ------------|---------  | 
-| `A1`        | A.1(x) Only      | 
-| `ZONE_1`    | Zone 1 of A.3(x) and A.6(x)   | 
-| `ZONE_2`    | Zone 2 of A.3(x) and A.6(x)    | 
-| `ZONE_3`    | Zone 3 of A.3(x) and A.6(x)  | 
-| `ZONE_4`    | Zone 4 of A.6(x)     | 
-| `ZONE_5`    | Zone 5 of A.6(x)       | 
-| `ZONE_6`    | Zone 6 of A.6(x)       | 
+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.
 
-# API
-
-Most functionality is achieved via `getters` and `setters` of the two main classes `Vssl`, `Zone`. 
-
-The classes will update the physical VSSL device when setting a property and once feedback has been received, the classes internal state will be updated. For example:
-
-```python
-# Setting the zones name
-zone1.settings.name = 'Living Room'
->>> None
-
-# Printing zone name
-zone_name = zone1.settings.name
-print(zone_name)
->>> 'Living Room'
-```
+| 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       |  | | ✔️|
 
-**Important** in the above example, `zone1.settings.name` wont be set to its new value until after the VSSL device has changed the name and the `Zone` class has received confirmation feedback. If you need to wait for the value change, you can await a `[property_name]_CHANGE` events.
 
 # `Vssl`
 

vsslctrl-0.1.12.dev1/tests/test_event_bus.py

@@ -1,70 +0,0 @@
-import asyncio
-import pytest
-import pytest_asyncio
-from vsslctrl.event_bus import EventBus
-
-
-class TestEventBus:
-
-    @pytest_asyncio.fixture(autouse=True)
-    async def event_bus(self):
-        bus = EventBus()
-        yield bus
-        bus.stop()  # Ensure the event bus is stopped after each test
-
-
-    @pytest.mark.asyncio
-    async def test_event_bus(self, event_bus):
-        # Instantiate the EventBus
-        #event_bus = EventBus()
-
-        async def publish_with_entity(self, entity = None):
-
-            # Define a callback function to be subscribed to the event
-            async def callback(data, *args, **kwargs):
-                callback.called = True
-                callback.data = data
-
-            # Subscribe the callback function to the event
-            event_type = "test_event"
-            event_bus.subscribe(event_type, callback, entity)
-            assert event_bus.subscribers.get(event_type) is not None
-            assert len(event_bus.subscribers.get(event_type)) == 1
-            assert event_bus.subscribers.get(event_type)[0][0] == callback
-
-
-            try:
-                # Publish the event
-                event_data = "test_data"
-                event_bus.publish(event_type, data=event_data, entity=entity)
-
-                # Wait for a short time to allow the event to be processed
-                await asyncio.sleep(0.1)
-
-                # Assert that the callback function has been called
-                assert hasattr(callback, 'called') and callback.called is True
-                assert getattr(callback, 'data') == event_data
-            finally:
-                # Unsubscribe the callback function
-                event_bus.unsubscribe(event_type, callback)
-                # Ensure the callback function was not called after unsubscribing
-                assert len(event_bus.subscribers.get(event_type)) == 0
-
-
-        await publish_with_entity(None)
-        await publish_with_entity(1)
-        await publish_with_entity('tet')
-
-    @pytest.mark.asyncio
-    async def test_event_bus_future(self, event_bus):
-
-        # Subscribe the callback function to the event
-        event_type = "test_event"
-        future = event_bus.future(event_type, 1)
-        event_data = "test_data"
-        event_bus.publish(event_type, data=event_data, entity=1)
-        data = await future
-        assert data == event_data
-        assert len(event_bus.subscribers.get(event_type)) == 0
-
-