phystack-hub-client 0.2.0__py3-none-any.whl

phystack/hub_client/instances/base_instance.py

@@ -0,0 +1,225 @@
+"""Base instance class with common functionality for all twin types."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from phystack.hub_client.types.twin_types import (
+    TwinMessageResult,
+    TwinProperties,
+    TwinResponse,
+)
+from phystack.hub_client.twin_messaging import (
+    TwinMessaging,
+    TargetedEmitter,
+)
+
+if TYPE_CHECKING:
+    from phystack.hub_client.client import PhyHubClient
+    from phystack.hub_client.services.webrtc.data_channel import (
+        PhygridDataChannel,
+        DataChannelOptions,
+    )
+    from phystack.hub_client.services.webrtc.media_stream import (
+        PhygridMediaStream,
+        MediaStreamOptions,
+    )
+
+
+class BaseInstance:
+    """Base class for all twin instances with common messaging and WebRTC."""
+
+    def __init__(
+        self,
+        twin_id: str,
+        device_id: str,
+        client: "PhyHubClient",
+        messaging: TwinMessaging,
+        twin_data: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize base instance.
+
+        Args:
+            twin_id: ID of this twin.
+            device_id: ID of the parent device.
+            client: PhyHubClient for API calls.
+            messaging: TwinMessaging instance for emit/on/to.
+            twin_data: Optional cached twin data.
+        """
+        self.id = twin_id
+        self.device_id = device_id
+        self._client = client
+        self._messaging = messaging
+        self._twin_data = twin_data or {}
+
+    @property
+    def properties(self) -> TwinProperties:
+        """Access twin properties (desired/reported)."""
+        props = self._twin_data.get("properties", {})
+        return TwinProperties.from_dict(props)
+
+    @property
+    def tenant_id(self) -> str:
+        """Get tenant ID."""
+        return self._twin_data.get("tenantId", "")
+
+    @property
+    def type(self) -> str:
+        """Get twin type."""
+        return self._twin_data.get("type", "")
+
+    @property
+    def status(self) -> str:
+        """Get twin status."""
+        return self._twin_data.get("status", "")
+
+    @property
+    def descriptors(self) -> dict[str, str]:
+        """Get twin descriptors."""
+        return self._twin_data.get("descriptors", {})
+
+    def _update_twin_data(self, data: dict[str, Any]) -> None:
+        """Update cached twin data."""
+        self._twin_data = {**self._twin_data, **data}
+
+    # =========================================================================
+    # Messaging API (delegated to TwinMessaging)
+    # =========================================================================
+
+    def emit(self, event_type: str, payload: Any = None) -> None:
+        """Fire-and-forget broadcast to subscribers.
+
+        Args:
+            event_type: Type of event to emit.
+            payload: Data to send.
+        """
+        self._messaging.emit(event_type, payload)
+
+    def on(
+        self,
+        event_type: str,
+        callback: Callable[[Any, Optional[Callable[[TwinMessageResult], None]]], None],
+    ) -> None:
+        """Listen for events, with optional respond callback for request-response.
+
+        Args:
+            event_type: Type of event to listen for.
+            callback: Handler function (data, respond?) => None
+        """
+        self._messaging.on(event_type, callback)
+
+    def to(self, target_twin_id: str) -> TargetedEmitter:
+        """Target a specific twin for messaging.
+
+        Args:
+            target_twin_id: ID of twin to target.
+
+        Returns:
+            TargetedEmitter for the specified twin.
+        """
+        return self._messaging.to(target_twin_id)
+
+    # =========================================================================
+    # WebRTC API (delegated to client)
+    # =========================================================================
+
+    async def get_data_channel(
+        self,
+        target_twin_id: str,
+        channel_name: str = "default",
+        options: Optional["DataChannelOptions"] = None,
+    ) -> "PhygridDataChannel":
+        """Create a WebRTC DataChannel to another twin.
+
+        Args:
+            target_twin_id: ID of the target twin.
+            channel_name: Name for the data channel.
+            options: Optional DataChannel configuration.
+
+        Returns:
+            PhygridDataChannel for sending/receiving data.
+        """
+        return await self._client.create_data_channel(
+            target_twin_id=target_twin_id,
+            is_initiator=True,
+            options=options,
+            channel_name=channel_name,
+        )
+
+    async def on_data_channel(
+        self,
+        target_twin_id: str,
+        callback: Callable[["PhygridDataChannel"], None],
+        channel_name: str = "default",
+    ) -> None:
+        """Listen for incoming DataChannel from a twin.
+
+        Args:
+            target_twin_id: ID of the twin to listen from.
+            callback: Handler for incoming channel.
+            channel_name: Name of the channel to listen for.
+        """
+        channel = await self._client.create_data_channel(
+            target_twin_id=target_twin_id,
+            is_initiator=False,
+            channel_name=channel_name,
+            blocking=False,
+        )
+        # Call callback when channel is opened
+        if channel.is_open():
+            callback(channel)
+        else:
+            original_on_open = None
+
+            def on_open() -> None:
+                callback(channel)
+
+            channel._handler._on_connected = on_open
+
+    async def get_media_stream(
+        self,
+        target_twin_id: str,
+        stream_name: str = "default",
+        options: Optional["MediaStreamOptions"] = None,
+    ) -> "PhygridMediaStream":
+        """Create a WebRTC MediaStream to another twin.
+
+        Args:
+            target_twin_id: ID of the target twin.
+            stream_name: Name for the media stream.
+            options: Optional MediaStream configuration.
+
+        Returns:
+            PhygridMediaStream for video/audio streaming.
+        """
+        return await self._client.create_media_stream(
+            target_twin_id=target_twin_id,
+            is_initiator=True,
+            options=options,
+            stream_name=stream_name,
+        )
+
+    async def on_media_stream(
+        self,
+        target_twin_id: str,
+        callback: Callable[["PhygridMediaStream"], None],
+        stream_name: str = "default",
+    ) -> None:
+        """Listen for incoming MediaStream from a twin.
+
+        Args:
+            target_twin_id: ID of the twin to listen from.
+            callback: Handler for incoming stream.
+            stream_name: Name of the stream to listen for.
+        """
+        stream = await self._client.create_media_stream(
+            target_twin_id=target_twin_id,
+            is_initiator=False,
+            stream_name=stream_name,
+            blocking=False,
+        )
+        # Call callback when stream is opened
+        if stream.is_open():
+            callback(stream)
+        else:
+            stream._handler._on_connected = lambda: callback(stream)

phystack/hub_client/instances/edge_instance.py

@@ -0,0 +1,212 @@
+"""EdgeInstance class for edge twin management."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Callable, Optional, Set
+
+from phystack.hub_client.instances.base_instance import BaseInstance
+from phystack.hub_client.types.twin_types import (
+    TwinResponse,
+    TwinTypeEnum,
+)
+
+if TYPE_CHECKING:
+    from phystack.hub_client.client import PhyHubClient
+    from phystack.hub_client.twin_messaging import TwinMessaging
+
+
+class EdgeInstance(BaseInstance):
+    """Edge twin instance with peripheral and settings management."""
+
+    def __init__(
+        self,
+        twin_id: str,
+        device_id: str,
+        client: "PhyHubClient",
+        messaging: "TwinMessaging",
+        twin_data: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize edge instance.
+
+        Args:
+            twin_id: ID of this edge twin.
+            device_id: ID of the parent device.
+            client: PhyHubClient for API calls.
+            messaging: TwinMessaging instance for emit/on/to.
+            twin_data: Optional cached twin data.
+        """
+        super().__init__(twin_id, device_id, client, messaging, twin_data)
+        self._update_reported_listeners: Set[Callable[[dict[str, Any]], None]] = set()
+        self._update_desired_listeners: Set[Callable[[dict[str, Any]], None]] = set()
+        self._previous_reported: Optional[str] = None
+        self._previous_desired: Optional[str] = None
+
+    # =========================================================================
+    # Properties API
+    # =========================================================================
+
+    async def update_reported(self, properties: dict[str, Any]) -> dict[str, Any]:
+        """Update reported properties for this edge twin.
+
+        Args:
+            properties: Properties to update.
+
+        Returns:
+            Updated twin data.
+        """
+        result = await self._client.update_reported_properties(self.id, properties)
+        if result:
+            self._update_twin_data(result)
+        return result or {}
+
+    def on_update_reported(
+        self, callback: Callable[[dict[str, Any]], None]
+    ) -> None:
+        """Subscribe to reported property changes.
+
+        Args:
+            callback: Handler called with new reported properties when they change.
+        """
+        self._update_reported_listeners.add(callback)
+
+        # Set up twin update listener if not already set
+        self._setup_property_listeners()
+
+    def on_update_desired(
+        self, callback: Callable[[dict[str, Any]], None]
+    ) -> None:
+        """Subscribe to desired property changes.
+
+        Args:
+            callback: Handler called with new desired properties when they change.
+        """
+        self._update_desired_listeners.add(callback)
+
+        # Set up twin update listener if not already set
+        self._setup_property_listeners()
+
+    def _setup_property_listeners(self) -> None:
+        """Set up twin update listener for property change detection."""
+
+        def on_twin_update(twin_data: dict[str, Any]) -> None:
+            if twin_data.get("id") != self.id:
+                return
+
+            props = twin_data.get("properties", {})
+
+            # Check reported changes
+            reported = props.get("reported", {})
+            reported_str = json.dumps(reported, sort_keys=True)
+            if self._previous_reported is None:
+                self._previous_reported = reported_str
+                for listener in self._update_reported_listeners:
+                    try:
+                        listener(reported)
+                    except Exception as e:
+                        print(f"[EdgeInstance] Error in reported listener: {e}")
+            elif reported_str != self._previous_reported:
+                self._previous_reported = reported_str
+                for listener in self._update_reported_listeners:
+                    try:
+                        listener(reported)
+                    except Exception as e:
+                        print(f"[EdgeInstance] Error in reported listener: {e}")
+
+            # Check desired changes
+            desired = props.get("desired", {})
+            desired_str = json.dumps(desired, sort_keys=True)
+            if self._previous_desired is None:
+                self._previous_desired = desired_str
+                for listener in self._update_desired_listeners:
+                    try:
+                        listener(desired)
+                    except Exception as e:
+                        print(f"[EdgeInstance] Error in desired listener: {e}")
+            elif desired_str != self._previous_desired:
+                self._previous_desired = desired_str
+                for listener in self._update_desired_listeners:
+                    try:
+                        listener(desired)
+                    except Exception as e:
+                        print(f"[EdgeInstance] Error in desired listener: {e}")
+
+            # Update cached twin data
+            self._update_twin_data(twin_data)
+
+        self._client.on_twin_update(self.id, on_twin_update)
+
+    # =========================================================================
+    # Peripheral Twin Management
+    # =========================================================================
+
+    async def create_peripheral_twin(
+        self,
+        name: str,
+        hardware_id: str,
+        desired_properties: Optional[dict[str, Any]] = None,
+        descriptors: Optional[dict[str, str]] = None,
+    ) -> dict[str, Any]:
+        """Create a new peripheral twin associated with this edge.
+
+        Args:
+            name: Name for the peripheral.
+            hardware_id: Unique hardware identifier.
+            desired_properties: Optional initial desired properties.
+            descriptors: Optional descriptors for the peripheral.
+
+        Returns:
+            Created peripheral twin data.
+
+        Raises:
+            ValueError: If peripheral with same hardware_id already exists.
+        """
+        # Check for existing peripheral with same hardware_id
+        existing = await self.get_peripheral_twins()
+        for twin in existing:
+            props = twin.get("properties", {}).get("desired", {})
+            if props.get("hardwareId") == hardware_id:
+                raise ValueError(
+                    f"Peripheral with hardwareId {hardware_id} already exists"
+                )
+
+        payload = {
+            "data": {
+                "deviceId": self.device_id,
+                "tenantId": self.tenant_id,
+                "instanceId": self.id,
+                "peripheralName": name,
+                "hardwareId": hardware_id,
+                "desiredProperties": desired_properties,
+                "descriptors": descriptors,
+            }
+        }
+
+        result = await self._client._connection.emit(
+            "createPeripheralTwin", payload, callback=True
+        )
+        return result.get("twin", {}) if result else {}
+
+    async def get_peripheral_twins(self) -> list[dict[str, Any]]:
+        """Get all peripheral twins for this edge instance.
+
+        Returns:
+            List of peripheral twin data.
+        """
+        payload = {"data": {"instanceId": self.id}}
+        result = await self._client._connection.emit(
+            "getPeripheralTwins", payload, callback=True
+        )
+        return result.get("twins", []) if result else []
+
+    # =========================================================================
+    # Settings API
+    # =========================================================================
+
+    def get_settings(self) -> dict[str, Any]:
+        """Get settings from desired properties.
+
+        Returns:
+            Settings dictionary.
+        """
+        return self.properties.desired.get("settings", {})

phystack/hub_client/instances/peripheral_instance.py

@@ -0,0 +1,186 @@
+"""PeripheralInstance class for peripheral twin management."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Callable, Optional, Set
+
+from phystack.hub_client.instances.base_instance import BaseInstance
+from phystack.hub_client.types.twin_types import TwinResponse
+
+if TYPE_CHECKING:
+    from phystack.hub_client.client import PhyHubClient
+    from phystack.hub_client.instances.edge_instance import EdgeInstance
+    from phystack.hub_client.twin_messaging import TwinMessaging
+
+
+class PeripheralInstance(BaseInstance):
+    """Peripheral twin instance with full property management."""
+
+    def __init__(
+        self,
+        twin_id: str,
+        device_id: str,
+        client: "PhyHubClient",
+        messaging: "TwinMessaging",
+        edge_instance: "EdgeInstance",
+        twin_data: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize peripheral instance.
+
+        Args:
+            twin_id: ID of this peripheral twin.
+            device_id: ID of the parent device.
+            client: PhyHubClient for API calls.
+            messaging: TwinMessaging instance for emit/on/to.
+            edge_instance: Parent edge instance.
+            twin_data: Optional cached twin data.
+        """
+        super().__init__(twin_id, device_id, client, messaging, twin_data)
+        self._edge_instance = edge_instance
+        self._update_reported_listeners: Set[Callable[[dict[str, Any]], None]] = set()
+        self._update_desired_listeners: Set[Callable[[dict[str, Any]], None]] = set()
+        self._previous_reported: Optional[str] = None
+        self._previous_desired: Optional[str] = None
+        self._listener_setup = False
+
+    # =========================================================================
+    # Properties API
+    # =========================================================================
+
+    async def update_reported(self, properties: dict[str, Any]) -> dict[str, Any]:
+        """Update reported properties for this peripheral twin.
+
+        Args:
+            properties: Properties to update.
+
+        Returns:
+            Updated twin data.
+        """
+        result = await self._client.update_reported_properties(self.id, properties)
+        if result:
+            self._update_twin_data(result)
+        return result or {}
+
+    async def update_desired(self, properties: dict[str, Any]) -> dict[str, Any]:
+        """Update desired properties for this peripheral twin.
+
+        Peripherals can update their own desired properties unlike edge twins.
+
+        Args:
+            properties: Properties to update.
+
+        Returns:
+            Updated twin data.
+        """
+        payload = {
+            "twinId": self.id,
+            "data": properties,
+        }
+
+        result = await self._client._connection.emit(
+            "updatePeripheralTwinDesired", payload, callback=True
+        )
+        twin_data = result.get("twin", {}) if result else {}
+        if twin_data:
+            self._update_twin_data(twin_data)
+        return twin_data
+
+    def on_update_reported(
+        self, callback: Callable[[dict[str, Any]], None]
+    ) -> None:
+        """Subscribe to reported property changes.
+
+        Args:
+            callback: Handler called with new reported properties when they change.
+        """
+        self._update_reported_listeners.add(callback)
+        self._setup_property_listeners()
+
+    def on_update_desired(
+        self, callback: Callable[[dict[str, Any]], None]
+    ) -> None:
+        """Subscribe to desired property changes.
+
+        Args:
+            callback: Handler called with new desired properties when they change.
+        """
+        self._update_desired_listeners.add(callback)
+        self._setup_property_listeners()
+
+    def _setup_property_listeners(self) -> None:
+        """Set up twin update listener for property change detection."""
+        if self._listener_setup:
+            return
+        self._listener_setup = True
+
+        def on_twin_update(twin_data: dict[str, Any]) -> None:
+            # Only process updates for this specific peripheral
+            if twin_data.get("id") != self.id:
+                return
+
+            props = twin_data.get("properties", {})
+
+            # Check reported changes
+            reported = props.get("reported", {})
+            if reported:
+                reported_str = json.dumps(reported, sort_keys=True)
+                if self._previous_reported is None:
+                    # First update - always trigger
+                    self._previous_reported = reported_str
+                    for listener in self._update_reported_listeners:
+                        try:
+                            listener(reported)
+                        except Exception as e:
+                            print(f"[PeripheralInstance] Error in reported listener: {e}")
+                elif reported_str != self._previous_reported:
+                    self._previous_reported = reported_str
+                    for listener in self._update_reported_listeners:
+                        try:
+                            listener(reported)
+                        except Exception as e:
+                            print(f"[PeripheralInstance] Error in reported listener: {e}")
+
+            # Check desired changes
+            desired = props.get("desired", {})
+            if desired:
+                desired_str = json.dumps(desired, sort_keys=True)
+                if self._previous_desired is None:
+                    # First update - always trigger
+                    self._previous_desired = desired_str
+                    for listener in self._update_desired_listeners:
+                        try:
+                            listener(desired)
+                        except Exception as e:
+                            print(f"[PeripheralInstance] Error in desired listener: {e}")
+                elif desired_str != self._previous_desired:
+                    self._previous_desired = desired_str
+                    for listener in self._update_desired_listeners:
+                        try:
+                            listener(desired)
+                        except Exception as e:
+                            print(f"[PeripheralInstance] Error in desired listener: {e}")
+
+            # Update cached twin data
+            self._update_twin_data(twin_data)
+
+        self._client.on_twin_update(self.id, on_twin_update)
+
+    # =========================================================================
+    # Lifecycle
+    # =========================================================================
+
+    async def remove(self) -> Optional[dict[str, Any]]:
+        """Delete this peripheral twin.
+
+        Returns:
+            Deleted twin data or None.
+        """
+        payload = {
+            "data": {"twinId": self.id}
+        }
+
+        result = await self._client._connection.emit(
+            "deletePeripheralTwin", payload, callback=True
+        )
+        return result.get("twin") if result else None

phystack/hub_client/services/__init__.py

@@ -0,0 +1,5 @@
+"""Services for PhyHub client."""
+
+from phystack.hub_client.services.phyhub_connection import PhyHubConnection
+
+__all__ = ["PhyHubConnection"]