rocket-welder-sdk 1.1.36.dev14__py3-none-any.whl

rocket_welder_sdk/external_controls/__init__.py

@@ -0,0 +1,30 @@
+"""External Controls module for RocketWelder SDK."""
+
+from rocket_welder_sdk.ui.value_types import ControlType
+
+from .contracts import (
+    ArrowDirection,
+    # Events (UI → Container)
+    ButtonDown,
+    ButtonUp,
+    ChangeControls,
+    # Commands (Container → UI)
+    DefineControl,
+    DeleteControl,  # Legacy alias - deprecated
+    DeleteControls,
+    KeyDown,
+    KeyUp,
+)
+
+__all__ = [
+    "ArrowDirection",
+    "ButtonDown",
+    "ButtonUp",
+    "ChangeControls",
+    "ControlType",  # Now using the single ControlType from ui.value_types
+    "DefineControl",
+    "DeleteControl",  # Legacy - deprecated
+    "DeleteControls",
+    "KeyDown",
+    "KeyUp",
+]

rocket_welder_sdk/external_controls/contracts.py

@@ -0,0 +1,100 @@
+"""External Controls contracts using Pydantic v2 for modern serialization.
+
+This module defines the contracts for external controls communication between
+containers and the RocketWelder UI via EventStore, using Pydantic v2 for
+proper serialization with PascalCase support.
+"""
+
+from enum import Enum
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+from pydantic.alias_generators import to_pascal
+
+from rocket_welder_sdk.ui.value_types import ControlType
+
+
+class ArrowDirection(str, Enum):
+    """Arrow directions for arrow grid control."""
+
+    UP = "Up"
+    DOWN = "Down"
+    LEFT = "Left"
+    RIGHT = "Right"
+
+
+class BaseContract(BaseModel):
+    """Base class for all contracts with PascalCase serialization."""
+
+    model_config = ConfigDict(
+        # Convert snake_case fields to PascalCase for serialization
+        alias_generator=to_pascal,
+        # Allow both snake_case and PascalCase when deserializing
+        populate_by_name=True,
+        # Use Enum values for serialization
+        use_enum_values=True,
+    )
+
+    id: UUID = Field(default_factory=uuid4)
+
+    @field_serializer("id")
+    def serialize_id(self, value: UUID) -> str:
+        """Serialize UUID as string for JSON compatibility."""
+        return str(value)
+
+
+# Container → UI Commands (Stream: ExternalCommands-{SessionId})
+
+
+class DefineControl(BaseContract):
+    """Command to define a new control in the UI."""
+
+    control_id: str
+    type: ControlType
+    properties: dict[str, str]
+    region_name: str
+
+
+class DeleteControls(BaseContract):
+    """Command to delete multiple controls from the UI."""
+
+    control_ids: list[str]
+
+
+# Legacy alias for backward compatibility (will be removed)
+DeleteControl = DeleteControls
+
+
+class ChangeControls(BaseContract):
+    """Command to update properties of multiple controls."""
+
+    updates: dict[str, dict[str, str]]  # ControlId -> {PropertyId -> Value}
+
+
+# UI → Container Events (Stream: ExternalEvents-{SessionId})
+
+
+class ButtonDown(BaseContract):
+    """Event when a button is pressed down."""
+
+    control_id: str
+
+
+class ButtonUp(BaseContract):
+    """Event when a button is released."""
+
+    control_id: str
+
+
+class KeyDown(BaseContract):
+    """Event when a key is pressed down."""
+
+    control_id: str
+    code: str  # KeyCode value like "ArrowUp", "Enter", etc.
+
+
+class KeyUp(BaseContract):
+    """Event when a key is released."""
+
+    control_id: str
+    code: str  # KeyCode value like "ArrowUp", "Enter", etc.

rocket_welder_sdk/external_controls/contracts_old.py

@@ -0,0 +1,105 @@
+"""External Controls event contracts for RocketWelder SDK (legacy - for backward compatibility)."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from uuid import UUID, uuid4
+
+from rocket_welder_sdk.ui.value_types import ControlType
+
+
+class ArrowDirection(Enum):
+    """Arrow directions for ArrowGrid control."""
+
+    UP = "Up"
+    DOWN = "Down"
+    LEFT = "Left"
+    RIGHT = "Right"
+
+
+# Container → UI Commands (Stream: ExternalCommands-{SessionId})
+
+
+@dataclass
+class DefineControl:
+    """Command to define a new control in the UI."""
+
+    control_id: str
+    type: ControlType
+    properties: dict[str, str]
+    region_name: str
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for EventStore."""
+        return {
+            "Id": str(self.id),
+            "ControlId": self.control_id,
+            "Type": self.type.value,
+            "Properties": self.properties,
+            "RegionName": self.region_name,
+        }
+
+
+@dataclass
+class DeleteControl:
+    """Command to delete a control from the UI."""
+
+    control_id: str
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert to dictionary for EventStore."""
+        return {"Id": str(self.id), "ControlId": self.control_id}
+
+
+@dataclass
+class ChangeControls:
+    """Command to update properties of multiple controls."""
+
+    updates: dict[str, dict[str, str]]  # ControlId -> { PropertyId -> Value }
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for EventStore."""
+        return {"Id": str(self.id), "Updates": self.updates}
+
+
+# UI → Container Events (Stream: ExternalEvents-{SessionId})
+
+
+@dataclass
+class ButtonDown:
+    """Event when button is pressed."""
+
+    control_id: str
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert to dictionary for EventStore."""
+        return {"Id": str(self.id), "ControlId": self.control_id}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "ButtonDown":
+        """Create from EventStore data."""
+        return cls(
+            control_id=str(data["ControlId"]), id=UUID(str(data["Id"])) if "Id" in data else uuid4()
+        )
+
+
+@dataclass
+class ButtonUp:
+    """Event when button is released."""
+
+    control_id: str
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert to dictionary for EventStore."""
+        return {"Id": str(self.id), "ControlId": self.control_id}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "ButtonUp":
+        """Create from EventStore data."""
+        return cls(
+            control_id=str(data["ControlId"]), id=UUID(str(data["Id"])) if "Id" in data else uuid4()
+        )

rocket_welder_sdk/frame_metadata.py

@@ -0,0 +1,138 @@
+"""
+Frame metadata structure prepended to each frame in zerobuffer shared memory.
+
+This module provides the FrameMetadata dataclass that matches the C++ struct
+defined in frame_metadata.h.
+
+Protocol Layout (16 bytes, 8-byte aligned):
+    [0-7]   frame_number    - Sequential frame index (0-based)
+    [8-15]  timestamp_ns    - GStreamer PTS in nanoseconds (UINT64_MAX if unavailable)
+
+Note: Width, height, and format are NOT included here because they are
+stream-level properties that never change per-frame. They are stored once
+in the ZeroBuffer metadata section as GstCaps (via GstMetadata).
+This avoids redundant data and follows single-source-of-truth principle.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import ClassVar, Dict, Optional
+
+# Size of the FrameMetadata structure in bytes
+FRAME_METADATA_SIZE = 16
+
+# Value indicating timestamp is unavailable
+TIMESTAMP_UNAVAILABLE = 0xFFFFFFFFFFFFFFFF  # UINT64_MAX
+
+# Struct format: little-endian, 2 uint64
+# Q = unsigned long long (8 bytes)
+_FRAME_METADATA_FORMAT = "<QQ"
+
+
+@dataclass(frozen=True)
+class FrameMetadata:
+    """
+    Frame metadata prepended to each frame in zerobuffer shared memory.
+
+    Attributes:
+        frame_number: Sequential frame index (0-based, increments per frame)
+        timestamp_ns: GStreamer PTS in nanoseconds (TIMESTAMP_UNAVAILABLE if not set)
+
+    Note: Width, height, and format come from GstCaps in ZeroBuffer metadata section,
+    not from per-frame metadata. This avoids redundant data.
+    """
+
+    frame_number: int
+    timestamp_ns: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes | memoryview) -> FrameMetadata:
+        """
+        Parse FrameMetadata from raw bytes.
+
+        Args:
+            data: At least 16 bytes of data
+
+        Returns:
+            FrameMetadata instance
+
+        Raises:
+            ValueError: If data is too short
+        """
+        if len(data) < FRAME_METADATA_SIZE:
+            raise ValueError(f"Data must be at least {FRAME_METADATA_SIZE} bytes, got {len(data)}")
+
+        # Unpack the struct
+        frame_number, timestamp_ns = struct.unpack(
+            _FRAME_METADATA_FORMAT, data[:FRAME_METADATA_SIZE]
+        )
+
+        return cls(
+            frame_number=frame_number,
+            timestamp_ns=timestamp_ns,
+        )
+
+    @property
+    def has_timestamp(self) -> bool:
+        """Check if timestamp is available."""
+        return self.timestamp_ns != TIMESTAMP_UNAVAILABLE
+
+    @property
+    def timestamp_ms(self) -> Optional[float]:
+        """Get timestamp in milliseconds, or None if unavailable."""
+        if self.has_timestamp:
+            return self.timestamp_ns / 1_000_000.0
+        return None
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        timestamp = f"{self.timestamp_ns / 1_000_000.0:.3f}ms" if self.has_timestamp else "N/A"
+        return f"Frame {self.frame_number} @ {timestamp}"
+
+
+# Common GstVideoFormat values - kept for reference when working with GstCaps
+class GstVideoFormat:
+    """Common GStreamer video format values (for use with GstCaps)."""
+
+    UNKNOWN = 0
+    I420 = 2
+    YV12 = 3
+    YUY2 = 4
+    UYVY = 5
+    RGBA = 11
+    BGRA = 12
+    ARGB = 13
+    ABGR = 14
+    RGB = 15
+    BGR = 16
+    NV12 = 23
+    NV21 = 24
+    GRAY8 = 25
+    GRAY16_BE = 26
+    GRAY16_LE = 27
+
+    _FORMAT_NAMES: ClassVar[Dict[int, str]] = {
+        0: "UNKNOWN",
+        2: "I420",
+        3: "YV12",
+        4: "YUY2",
+        5: "UYVY",
+        11: "RGBA",
+        12: "BGRA",
+        13: "ARGB",
+        14: "ABGR",
+        15: "RGB",
+        16: "BGR",
+        23: "NV12",
+        24: "NV21",
+        25: "GRAY8",
+        26: "GRAY16_BE",
+        27: "GRAY16_LE",
+    }
+
+    @classmethod
+    def to_string(cls, format_value: int) -> str:
+        """Convert format value to string name."""
+        return cls._FORMAT_NAMES.get(format_value, f"FORMAT_{format_value}")