vsslctrl 0.1.0.dev1__py3-none-any.whl

vsslctrl/discovery.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+
+""" Scan for apple devices. """
+
+import json
+import asyncio
+from typing import Any, Optional, cast
+
+from zeroconf import IPVersion, ServiceStateChange, Zeroconf
+from zeroconf.asyncio import (
+    AsyncServiceBrowser,
+    AsyncServiceInfo,
+    AsyncZeroconf,
+    InterfaceChoice,
+)
+
+from .utils import group_list_by_property
+from .api_alpha import APIAlpha
+from .decorators import logging_helpers
+from .exceptions import ZeroConfNotInstalled, ZoneConnectionError, ZoneError
+
+from .data_structure import ZoneStatusExtKeys
+
+
+#
+# Check to see if Zeroconf is available on the system
+#
+def check_zeroconf_availability():
+    try:
+        import zeroconf
+        import zeroconf.asyncio
+
+        return True
+    except ImportError:
+        raise ZeroConfNotInstalled(
+            "Error: 'zeroconf' package is not installed. Install using 'pip install zeroconf'."
+        )
+        return False
+
+
+#
+# Attempt to connect to zone and return id and serial from a given host IP
+#
+async def fetch_zone_id_serial(host):
+    try:
+        # Open a connection to the server
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(host, APIAlpha.TCP_PORT), APIAlpha.TIMEOUT
+        )
+
+        # Request zones status
+        writer.write(APIAlpha.ZONE_STATUS)
+
+        # Wait until the data is flushed
+        await writer.drain()
+
+        # Receive response
+        response = await reader.read(1024)
+        string = response[APIAlpha.JSON_HEADER_LENGTH :].decode("ascii")
+        metadata = json.loads(string)
+
+        writer.close()
+        await writer.wait_closed()
+
+        if (
+            ZoneStatusExtKeys.ID not in metadata
+            or ZoneStatusExtKeys.SERIAL_NUMBER not in metadata
+        ):
+            raise ZoneError(
+                f"Host {host}:{APIAlpha.TCP_PORT} didnt return ID or serial number"
+            )
+
+    except (asyncio.TimeoutError, asyncio.CancelledError):
+        raise ZoneConnectionError(f"Connection to {host}:{APIAlpha.TCP_PORT} timed out")
+
+    # Return the ID and serial
+    return (
+        metadata[ZoneStatusExtKeys.ID],
+        metadata[ZoneStatusExtKeys.SERIAL_NUMBER],
+    )
+
+
+@logging_helpers()
+class VsslDiscovery:
+    SERVICE_STRING: str = "_airplay._tcp.local."
+
+    def __init__(self, aiozc: AsyncZeroconf = None, discovery_time: int = 5):
+        self.discovery_time = discovery_time
+        self.discovered_zones = []
+        self.zeroconf_available = check_zeroconf_availability()
+
+        self.aiozc = aiozc
+        self.aiobrowser = None
+
+    #
+    # Discover
+    #
+    async def discover(self):
+        if not self.zeroconf_available:
+            return
+
+        self.discovered_zones = []
+
+        if not isinstance(self.aiozc, AsyncZeroconf):
+            self.aiozc = AsyncZeroconf(
+                ip_version=IPVersion.V4Only, interfaces=InterfaceChoice.All
+            )
+
+        task = asyncio.create_task(self._run())
+
+        await asyncio.sleep(self.discovery_time)
+        await self._close()
+        task.cancel()
+
+        hosts = []
+        for zone in self.discovered_zones:
+            try:
+                zone_id, serial = await fetch_zone_id_serial(zone["host"])
+                if zone_id and serial:
+                    zone["zone_id"] = zone_id
+                    zone["serial"] = serial
+                    hosts.append(zone)
+
+            except Exception:
+                self._log_error(
+                    f'Error fetching zone info for discovered host {zone["host"]}'
+                )
+
+        return group_list_by_property(hosts, "serial")
+
+    #
+    # Run
+    #
+    async def _run(self) -> None:
+        await self.aiozc.zeroconf.async_wait_for_start()
+        self._log_debug(f"Browsing for {self.SERVICE_STRING} services")
+
+        self.aiobrowser = AsyncServiceBrowser(
+            self.aiozc.zeroconf,
+            self.SERVICE_STRING,
+            handlers=[self._on_service_state_change],
+        )
+
+        while True:
+            await asyncio.sleep(1)
+
+    #
+    # Close
+    #
+    async def _close(self) -> None:
+        assert self.aiozc is not None
+        assert self.aiobrowser is not None
+        await self.aiobrowser.async_cancel()
+        await self.aiozc.async_close()
+
+    #
+    # on_service_state_change
+    #
+    def _on_service_state_change(
+        self,
+        zeroconf: Zeroconf,
+        service_type: str,
+        name: str,
+        state_change: ServiceStateChange,
+    ) -> None:
+        asyncio.ensure_future(self._fetch_service_info(zeroconf, service_type, name))
+
+    #
+    # show_service_info
+    #
+    async def _fetch_service_info(
+        self, zeroconf: Zeroconf, service_type: str, name: str
+    ) -> None:
+        info = AsyncServiceInfo(service_type, name)
+        await info.async_request(zeroconf, 3000)
+
+        if info:
+            manufacturer = info.properties.get(b"manufacturer", None)
+            if manufacturer and manufacturer.startswith(b"VSSL"):
+                self.discovered_zones.append(
+                    {
+                        # Convert byte representation of IP address to string
+                        "host": info.parsed_addresses()[0],
+                        "name": name.rstrip(f".{self.SERVICE_STRING}"),
+                        "model": info.properties.get(b"model", b"")
+                        .decode("utf-8")
+                        .lstrip(f"VSSL")
+                        .strip(),
+                        "mac_addr": info.properties.get(b"deviceid", b"").decode(
+                            "utf-8"
+                        ),
+                    }
+                )

vsslctrl/event_bus.py

@@ -0,0 +1,159 @@
+import asyncio
+import traceback
+from enum import IntEnum
+from typing import Callable
+from .exceptions import VsslCtrlException
+from .decorators import logging_helpers
+
+#
+# Event Bus
+#
+
+
+@logging_helpers("EventBus:")
+class EventBus:
+    WILDCARD = "*"
+    FUTURE_TIMEOUT = 5
+
+    def __init__(self):
+        self.subscribers = {}
+        self.event_queue = asyncio.Queue()
+
+        self.running = False
+
+        self.process = asyncio.create_task(self.process_events())
+
+    #
+    # Stop
+    #
+    def stop(self):
+        self.running = False
+        self.process.cancel()
+        self._log_debug(f"stopped event processing")
+
+    #
+    # Subscribe
+    #
+    def subscribe(self, event_type, callback: Callable, entity="*", once=False):
+        # Make sure we are using async callbacks
+        if callback is not None and asyncio.iscoroutinefunction(callback):
+            event_type = event_type.lower()
+            if event_type not in self.subscribers:
+                self.subscribers[event_type] = []
+            self._log_debug(
+                f"subscription for event: {event_type} | entity: {entity} | cb: {callback.__name__}"
+            )
+            self.subscribers[event_type].append((callback, entity, once))
+        else:
+            message = f"{callback.__name__} must be a coroutine. Event: {event_type} | Entity: {entity}"
+            self._log_error(message)
+            raise VsslCtrlException(message)
+
+    #
+    # Unsubscribe
+    #
+    def unsubscribe(self, event_type, callback):
+        event_type = event_type.lower()
+        if event_type in self.subscribers:
+            self.subscribers[event_type] = [
+                cb for cb in self.subscribers[event_type] if cb[0] != callback
+            ]
+
+    #
+    # Get a future value from the event bus
+    #
+    def future(self, event_type, entity=None) -> asyncio.Future:
+        future = asyncio.Future()
+
+        async def future_callback(data, *args):
+            nonlocal future
+            future.set_result(data)
+
+        self.subscribe(event_type, future_callback, entity, once=True)
+
+        return future
+
+    #
+    # Helper to await a future with a timeout
+    #
+    async def wait_future(self, future, timeout: int = FUTURE_TIMEOUT):
+        if timeout != 0:
+            try:
+                return await asyncio.wait_for(future, timeout)
+            except asyncio.TimeoutError as error:
+                self._log_error(f"timeout waiting for future")
+                raise error
+        else:
+            return await future
+
+    #
+    # wait_for, will wait for an event to be fired and return the result
+    #
+    async def wait_for(
+        self,
+        event_type,
+        entity=None,
+        timeout: int = FUTURE_TIMEOUT,
+        timeout_result=None,
+    ):
+        future = self.future(event_type, entity)
+        try:
+            return await self.wait_future(future, timeout=timeout)
+        except asyncio.TimeoutError as error:
+            return timeout_result
+
+    #
+    # Publish
+    #
+    def publish(self, event_type, entity=None, data=None):
+        asyncio.create_task(self.publish_async(event_type, entity, data))
+
+    #
+    # Publish Async (Use when inside events loop)
+    #
+    async def publish_async(self, event_type, entity=None, data=None):
+        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:
+                event_type, entity, data = await self.event_queue.get()
+
+                if self._is_log_level("debug"):
+                    message = (
+                        f"processing event: {event_type} | entity: {entity} | data: "
+                    )
+                    if isinstance(data, IntEnum):
+                        message += f"{data.name} ({data.value})"
+                    else:
+                        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)
+
+            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/exceptions.py

@@ -0,0 +1,21 @@
+import traceback
+
+
+class VsslCtrlException(Exception):
+    """VSSL Exception"""
+
+    def __init__(self, message):
+        super().__init__(message)
+        self.traceback = traceback.format_exc()
+
+
+class ZoneError(VsslCtrlException):
+    """Zone Exception"""
+
+
+class ZoneConnectionError(ZoneError):
+    """Zone Connection Exception Exception"""
+
+
+class ZeroConfNotInstalled(VsslCtrlException):
+    """Zone Exception"""

vsslctrl/group.py

@@ -0,0 +1,187 @@
+import logging
+from . import zone
+from typing import Dict, Union
+from .data_structure import ZoneDataClass
+
+
+"""
+    Note from VSSSL API, here for archive purpose
+
+    AddZoneToGroup: If z1 is currently playing then you can create a new group by adding z2 by ~SetGroup(vsslSerial, 1, 2).  Z1 and z2
+    will now be playing the z1 stream.  If the z1 stream is stopped then the group will automatically dissolve.  If a stream is
+    started on z2 while z2 is in the group then the z2 content will not output on the z2 speaker until z2 is removed from the group.
+
+    RemoveZoneFromGroup: If a group exists with z1 as the parent and (z2, z3) as children then you can remove z2 from the group by
+    setting its parent to 255 ~SetGroup(vsslSerial, 255, 2).
+
+    DissolveGroup: If a group exists with z1 as the parent and (z2, z3) as children then you can remove z2 from the group by
+    setting the child group to 255 ~SetGroup(vsslSerial, 1, 255).
+
+    Ref: https://vssl.gitbook.io/vssl-rest-api/zone-control/set-group
+
+"""
+
+
+class ZoneGroup(ZoneDataClass):
+    #
+    # Group Events
+    #
+    class Events:
+        PREFIX = "zone.group."
+        INDEX_CHANGE = PREFIX + "index_change"
+        SOURCE_CHANGE = PREFIX + "source_change"
+        IS_MASTER_CHANGE = PREFIX + "is_master_change"
+
+    DEFAULTS = {"index": 0, "source": None, "is_master": False}
+
+    def __init__(self, zone: "zone.Zone"):
+        self.zone = zone
+
+        """ On a A.3x the group index are, Im not sure if this is consistant with A1.x or A6.x:
+
+            Zone 1: 9
+            Zone 2: 10
+            Zone 3: 11
+
+            This can be assigned to other group members when this zone is the source.
+
+            I have not idea if this is how it was intended, but its working on the A3.x
+
+        """
+        self._index_id = zone.id + 8
+
+        # index is assigned when a stream is started (see action_32)
+        self._index = 0
+        self._source = None
+        self._is_master = False
+
+    #
+    # Group Add Zone
+    #
+    def add_member(self, zone_id: "zone.Zone.IDs"):
+        if self.zone.id == zone_id:
+            self.zone._log_error(f"Zone {zone_id} cant be parent and member")
+            return False
+
+        if zone.Zone.IDs.is_not_valid(zone_id):
+            self.zone._log_error(f"Zone {zone_id} doesnt exist")
+            return False
+
+        if self.is_member:
+            self.zone._log_error(
+                f"Zone {self.zone.id} already a member of Zone {self.source} group"
+            )
+            return False
+
+        if self.zone.transport.is_stopped:
+            self.zone._log_error(
+                f"Zone {self.zone.id} cant be a group master when not playing a source"
+            )
+            return False
+
+        self.zone.api_alpha.request_action_4B_add(zone_id)
+
+    #
+    # Group Remove Child
+    #
+    def remove_member(self, zone_id: "zone.Zone.IDs"):
+        self.zone.api_alpha.request_action_4B_remove(zone_id)
+
+    #
+    # Group Dissolve
+    #
+    def dissolve(self):
+        self.zone.api_alpha.request_action_4B_dissolve()
+
+    #
+    # Leave any groups if is a member
+    #
+    def leave(self) -> None:
+        self.zone.api_alpha.request_action_4B_remove(self.zone.id)
+
+    @property
+    def index_id(self):
+        return self._index_id
+
+    @index_id.setter
+    def index_id(self, index_id: int):
+        pass  # read-only
+
+    #
+    # Group Index
+    #
+    # The index is assigned when the zone starts a stream.
+    #
+    @property
+    def index(self):
+        return self._index
+
+    @index.setter
+    def index(self, index: int):
+        pass  # read-only
+
+    #
+    # Group Source
+    #
+    @property
+    def source(self):
+        return self._source
+
+    @source.setter
+    def source(self, grs: int):
+        pass  # read-only
+
+    def _set_source(self, grs: int):
+        new_source = (
+            zone.Zone.IDs(grs) if grs != 255 and zone.Zone.IDs.is_valid(grs) else None
+        )
+
+        if self.source != new_source:
+            self._source = new_source
+            return True
+
+    @property
+    def is_member(self):
+        return self.source is not None
+
+    #
+    # Group: This zone is a master for a group
+    #
+    # TODO: propogate track meta to member zones.
+    # Only play state is propgated by the VSSL device
+    #
+    @property
+    def is_master(self):
+        return self._is_master
+
+    @is_master.setter
+    def is_master(self, grm: int):
+        pass  # read-only
+
+    def _set_is_master(self, grm: int):
+        if self.is_master != bool(grm):
+            self._is_master = grm != 0
+            return True
+
+    #
+    # Get groups master zone
+    #
+    @property
+    def master(self):
+        if self.is_master:
+            return self
+        if self.source is not None:
+            return self.zone.vssl.get_zone(self.source)
+
+    #
+    # Get group member zones
+    #
+    @property
+    def members(self):
+        if not self.is_master:
+            return []
+        return [
+            zone
+            for zone in self.zone.vssl.zones.values()
+            if zone.group.index == self.index and zone.group.is_member
+        ]