rcp-sdk 0.1.0__py3-none-any.whl

rcp_sdk/__init__.py

@@ -0,0 +1,34 @@
+"""RCP SDK — Robot Context Protocol adapter interface."""
+
+from rcp_sdk.models import (
+    JointState, TCPPosition, IOSignal, IOState, ProgramInfo, ToolData,
+    AdapterCapabilities, RobotIdentity, RobotContext, RCPEvent,
+    UploadResult, DiffResult, AuditEntry, RiskLevel,
+)
+from rcp_sdk.adapter import RCPAdapter
+from rcp_sdk.safety import ACTION_RISK, PROHIBITED_ACTIONS, RiskLevels
+from rcp_sdk.jsonrpc import (
+    JsonRpcRequest, JsonRpcResponse, JsonRpcError, JsonRpcErrorResponse,
+    JsonRpcNotification, RCPErrorCodes, RCPMethods,
+    parse_message, serialize_response, serialize_notification,
+)
+from rcp_sdk.server import serve, run
+
+__all__ = [
+    # Models
+    "JointState", "TCPPosition", "IOSignal", "IOState", "ProgramInfo", "ToolData",
+    "AdapterCapabilities", "RobotIdentity", "RobotContext", "RCPEvent",
+    "UploadResult", "DiffResult", "AuditEntry", "RiskLevel",
+    # Adapter
+    "RCPAdapter",
+    # Safety
+    "ACTION_RISK", "PROHIBITED_ACTIONS", "RiskLevels",
+    # JSON-RPC wire format
+    "JsonRpcRequest", "JsonRpcResponse", "JsonRpcError", "JsonRpcErrorResponse",
+    "JsonRpcNotification", "RCPErrorCodes", "RCPMethods",
+    "parse_message", "serialize_response", "serialize_notification",
+    # Server
+    "serve", "run",
+]
+
+__version__ = "0.1.0"

rcp_sdk/adapter.py

@@ -0,0 +1,175 @@
+"""
+RCP Adapter base class — all OEM adapters implement this interface.
+"""
+
+from abc import ABC, abstractmethod
+from typing import AsyncIterator, Optional
+from rcp_sdk.models import (
+    RobotIdentity, AdapterCapabilities, JointState, TCPPosition,
+    IOState, ProgramInfo, ToolData, RobotContext, RCPEvent, UploadResult,
+)
+
+
+class RCPAdapter(ABC):
+    """Abstract base for RCP OEM adapters."""
+
+    @abstractmethod
+    async def connect(self, config: dict) -> None:
+        """Connect to the controller. Config has host, port, etc."""
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Disconnect from the controller."""
+
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """Return True if currently connected."""
+
+    @abstractmethod
+    async def discover(self) -> RobotIdentity:
+        """Discover the connected robot's identity."""
+
+    @abstractmethod
+    def capabilities(self) -> AdapterCapabilities:
+        """Return what this adapter supports."""
+
+    @abstractmethod
+    async def get_joints(self) -> list[JointState]:
+        """Get current joint positions."""
+
+    @abstractmethod
+    async def get_tcp(self) -> TCPPosition:
+        """Get current TCP position."""
+
+    @abstractmethod
+    async def get_io(self) -> IOState:
+        """Get all I/O states."""
+
+    @abstractmethod
+    async def get_programs(self) -> list[ProgramInfo]:
+        """Get loaded programs."""
+
+    @abstractmethod
+    async def get_tools(self) -> list[ToolData]:
+        """Get configured tools."""
+
+    async def get_program_code(self, module: str) -> str:
+        """Get the source code of a program module from the controller.
+        Returns empty string if not supported or module not found."""
+        return ""
+
+    async def upload_program(self, module: str, code: str) -> UploadResult:
+        """Upload a program module to the controller. GUARDED action."""
+        return UploadResult(success=False, message="Upload not supported by this adapter")
+
+    async def capture_position(self) -> tuple["TCPPosition", list["JointState"]]:
+        """Capture current position. Default: use get_tcp + get_joints."""
+        return await self.get_tcp(), await self.get_joints()
+
+    async def set_io(self, signal: str, value: float) -> None:
+        """Set an I/O output signal value. GUARDED action."""
+        raise NotImplementedError("This adapter does not support I/O control")
+
+    async def verify_interlocks(self) -> tuple[bool, str]:
+        """Check safety interlocks before RESTRICTED actions.
+        Default: always passes. OEM adapters override with real checks.
+        Returns (ok, reason) — reason is empty string if ok."""
+        return (True, "")
+
+    async def move_to(self, position: TCPPosition) -> dict:
+        """Move TCP to specified position. RESTRICTED action.
+        Returns dict with 'success', 'message', and optionally 'actual_tcp', 'drift_mm'."""
+        raise NotImplementedError("This adapter does not support motion commands")
+
+    async def stop(self) -> None:
+        """Immediately stop robot motion. SAFE action."""
+        raise NotImplementedError("This adapter does not support stop commands")
+
+    # ── Optional RESTRICTED actions (adapters opt in) ──
+
+    async def start_program(self, module: str) -> dict:
+        """Start a program on the controller. RESTRICTED action.
+        Returns dict with 'success', 'message'."""
+        raise NotImplementedError("This adapter does not support program start")
+
+    async def jog(self, axis: str, direction: int, speed: float) -> dict:
+        """Jog a single axis. RESTRICTED action.
+        axis: 'J1'..'J6' or 'X'|'Y'|'Z'|'RX'|'RY'|'RZ'. direction: +1 or -1."""
+        raise NotImplementedError("This adapter does not support jog commands")
+
+    async def home(self) -> dict:
+        """Move robot to home pose. RESTRICTED action."""
+        raise NotImplementedError("This adapter does not support homing")
+
+    # ── Optional SAFE actions ──
+
+    async def validate_program(self, code: str) -> dict:
+        """Validate a program against adapter-specific syntax/semantics. SAFE action.
+        Returns dict with 'valid', 'errors', 'warnings'."""
+        return {"valid": True, "errors": [], "warnings": []}
+
+    async def diff_program(self, module: str, local_code: str) -> dict:
+        """Diff local code against controller-resident code. SAFE action.
+        Default implementation fetches via get_program_code + unified diff.
+        Returns dict with 'controller_code', 'added', 'removed', 'changed'."""
+        import difflib
+        controller_code = await self.get_program_code(module)
+        local_lines = local_code.splitlines()
+        controller_lines = controller_code.splitlines()
+        diff = list(difflib.unified_diff(controller_lines, local_lines, lineterm=""))
+        added = sum(1 for line in diff if line.startswith("+") and not line.startswith("+++"))
+        removed = sum(1 for line in diff if line.startswith("-") and not line.startswith("---"))
+        changed = min(added, removed)
+        return {
+            "controller_code": controller_code,
+            "added": added - changed,
+            "removed": removed - changed,
+            "changed": changed,
+        }
+
+    async def modify_tool_data(self, tool: ToolData) -> dict:
+        """Overwrite a tool definition on the controller. GUARDED action."""
+        raise NotImplementedError("This adapter does not support tool-data modification")
+
+    # ── Optional event streaming ──
+
+    def subscribe(self, channels: list[str]) -> Optional[AsyncIterator[RCPEvent]]:
+        """
+        Open an event stream for the given channels.
+
+        Return an async iterator that yields RCPEvent items. Return None if this
+        adapter doesn't stream events — the server then skips wiring forwarders.
+
+        Canonical channels: 'position', 'io', 'program', 'safety', 'error'.
+        Adapters may define their own OEM-specific channels as well.
+        """
+        return None
+
+    async def get_context(self) -> RobotContext:
+        """Aggregate all state into a context block for AI injection."""
+        ctx = RobotContext()
+        try:
+            ctx.identity = await self.discover()
+        except Exception:
+            pass
+        try:
+            ctx.joints = await self.get_joints()
+        except Exception:
+            pass
+        try:
+            ctx.tcp = await self.get_tcp()
+        except Exception:
+            pass
+        try:
+            ctx.io = await self.get_io()
+        except Exception:
+            pass
+        try:
+            ctx.programs = await self.get_programs()
+        except Exception:
+            pass
+        try:
+            ctx.tools = await self.get_tools()
+        except Exception:
+            pass
+        return ctx

rcp_sdk/jsonrpc.py

@@ -0,0 +1,208 @@
+"""RCP JSON-RPC 2.0 wire format implementation.
+
+Zero-dependency module implementing the JSON-RPC 2.0 message format
+for RCP protocol communication. Used by the server module and can be
+used by any transport layer.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Any, Union
+import json
+
+
+@dataclass
+class JsonRpcRequest:
+    """A JSON-RPC 2.0 request (expects a response)."""
+    method: str
+    params: dict
+    id: Union[str, int]
+    jsonrpc: str = "2.0"
+
+
+@dataclass
+class JsonRpcResponse:
+    """A JSON-RPC 2.0 success response."""
+    result: Any
+    id: Union[str, int]
+    jsonrpc: str = "2.0"
+
+
+@dataclass
+class JsonRpcError:
+    """JSON-RPC 2.0 error object."""
+    code: int
+    message: str
+    data: Any = None
+
+
+@dataclass
+class JsonRpcErrorResponse:
+    """A JSON-RPC 2.0 error response."""
+    error: JsonRpcError
+    id: Union[str, int, None]
+    jsonrpc: str = "2.0"
+
+
+@dataclass
+class JsonRpcNotification:
+    """A JSON-RPC 2.0 notification (no response expected, no id)."""
+    method: str
+    params: dict
+    jsonrpc: str = "2.0"
+
+
+class RCPErrorCodes:
+    """Standard error codes for the RCP protocol.
+
+    Ranges:
+        -32700 to -32600: JSON-RPC standard errors
+        1000-1999: RCP transport errors
+        2000-2999: RCP protocol errors
+        3000-3999: RCP safety errors
+        4000-4999: RCP adapter errors
+    """
+
+    # JSON-RPC standard
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+
+    # RCP transport (1000-1999)
+    CONNECTION_FAILED = 1000
+    CONNECTION_TIMEOUT = 1001
+    CONNECTION_LOST = 1002
+
+    # RCP protocol (2000-2999)
+    RESOURCE_NOT_FOUND = 2000
+    ACTION_NOT_SUPPORTED = 2001
+    INVALID_RESOURCE_URI = 2002
+    SUBSCRIPTION_FAILED = 2003
+
+    # RCP safety (3000-3999)
+    APPROVAL_REQUIRED = 3000
+    APPROVAL_EXPIRED = 3001
+    APPROVAL_REJECTED = 3002
+    INTERLOCKS_FAILED = 3003
+    ACTION_PROHIBITED = 3004
+    SAFETY_VIOLATION = 3005
+
+    # RCP adapter (4000-4999)
+    ADAPTER_ERROR = 4000
+    ADAPTER_DISCONNECTED = 4001
+    ADAPTER_BUSY = 4002
+    HARDWARE_ERROR = 4003
+
+
+class RCPMethods:
+    """Method name constants for RCP operations.
+
+    These are the JSON-RPC method strings used in the wire protocol.
+    """
+
+    # Resources
+    READ = "rcp.read"
+    SUBSCRIBE = "rcp.subscribe"
+    UNSUBSCRIBE = "rcp.unsubscribe"
+
+    # Actions
+    REQUEST_ACTION = "rcp.action.request"
+    APPROVE_ACTION = "rcp.action.approve"
+    CANCEL_ACTION = "rcp.action.cancel"
+
+    # Context
+    DISCOVER = "rcp.discover"
+    GET_CONTEXT = "rcp.context"
+    GET_CAPABILITIES = "rcp.capabilities"
+
+    # Events (notifications — no response expected)
+    EVENT = "rcp.event"
+    APPROVAL_REQUIRED = "rcp.approval_required"
+    ACTION_RESULT = "rcp.action_result"
+
+
+def parse_message(raw: Union[str, bytes]) -> Union[JsonRpcRequest, JsonRpcNotification]:
+    """Parse a JSON-RPC 2.0 message from raw string or bytes.
+
+    Returns a JsonRpcRequest if the message has an 'id' field,
+    otherwise returns a JsonRpcNotification.
+
+    Raises:
+        ValueError: If the message is not valid JSON-RPC 2.0.
+    """
+    if isinstance(raw, bytes):
+        raw = raw.decode("utf-8")
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON: {e}") from e
+
+    if not isinstance(data, dict):
+        raise ValueError("JSON-RPC message must be a JSON object")
+
+    if data.get("jsonrpc") != "2.0":
+        raise ValueError("Missing or invalid 'jsonrpc' field (must be '2.0')")
+
+    method = data.get("method")
+    if not isinstance(method, str):
+        raise ValueError("Missing or invalid 'method' field")
+
+    params = data.get("params", {})
+    if not isinstance(params, dict):
+        raise ValueError("'params' must be a JSON object")
+
+    msg_id = data.get("id")
+    if msg_id is not None:
+        return JsonRpcRequest(method=method, params=params, id=msg_id)
+    else:
+        return JsonRpcNotification(method=method, params=params)
+
+
+def _serialize_value(obj: Any) -> Any:
+    """Recursively convert dataclasses and special types for JSON serialization."""
+    if hasattr(obj, "__dataclass_fields__"):
+        return {k: _serialize_value(v) for k, v in asdict(obj).items()}
+    if isinstance(obj, dict):
+        return {k: _serialize_value(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_serialize_value(v) for v in obj]
+    return obj
+
+
+def serialize_response(response: Union[JsonRpcResponse, JsonRpcErrorResponse]) -> str:
+    """Serialize a JSON-RPC response to a JSON string.
+
+    Handles both success responses (JsonRpcResponse) and error
+    responses (JsonRpcErrorResponse).
+    """
+    if isinstance(response, JsonRpcErrorResponse):
+        error_dict: dict[str, Any] = {
+            "code": response.error.code,
+            "message": response.error.message,
+        }
+        if response.error.data is not None:
+            error_dict["data"] = _serialize_value(response.error.data)
+        payload: dict[str, Any] = {
+            "jsonrpc": response.jsonrpc,
+            "error": error_dict,
+            "id": response.id,
+        }
+    else:
+        payload = {
+            "jsonrpc": response.jsonrpc,
+            "result": _serialize_value(response.result),
+            "id": response.id,
+        }
+    return json.dumps(payload, separators=(",", ":"))
+
+
+def serialize_notification(notification: JsonRpcNotification) -> str:
+    """Serialize a JSON-RPC notification to a JSON string."""
+    payload = {
+        "jsonrpc": notification.jsonrpc,
+        "method": notification.method,
+        "params": _serialize_value(notification.params),
+    }
+    return json.dumps(payload, separators=(",", ":"))

rcp_sdk/models.py

@@ -0,0 +1,190 @@
+"""
+RCP data models — shared across all adapters.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal
+
+
+@dataclass
+class JointState:
+    name: str          # "J1", "J2", etc.
+    position_deg: float
+    min_deg: float = -360.0
+    max_deg: float = 360.0
+    max_speed_deg_s: float = 180.0
+
+
+@dataclass
+class TCPPosition:
+    x: float  # mm
+    y: float
+    z: float
+    rx: float  # degrees or radians depending on OEM
+    ry: float
+    rz: float
+
+
+@dataclass
+class IOSignal:
+    name: str
+    signal_type: Literal["digital_input", "digital_output", "analog_input", "analog_output"]
+    value: float  # 0/1 for digital, 0.0-1.0 for analog
+    # Optional channel mode for analog signals: "voltage" (0–10 V) or
+    # "current" (4–20 mA). Adapters that can resolve the per-channel domain
+    # (e.g. UR's standard_analog_*_domain) populate this so the IODashboard
+    # renders the correct unit (V vs mA). None = unknown / not applicable.
+    mode: Literal["voltage", "current"] | None = None
+
+
+@dataclass
+class IOState:
+    signals: list[IOSignal] = field(default_factory=list)
+
+
+@dataclass
+class ProgramInfo:
+    name: str
+    loaded: bool = False
+    running: bool = False
+    paused: bool = False
+
+
+@dataclass
+class ToolData:
+    name: str
+    tcp_x: float = 0.0
+    tcp_y: float = 0.0
+    tcp_z: float = 0.0
+    mass_kg: float = 0.0
+
+
+@dataclass
+class AdapterCapabilities:
+    read: bool = True
+    validate: bool = False
+    deploy: bool = False
+    execute: bool = False
+    events: list[str] = field(default_factory=list)
+    streaming: bool = False
+
+
+@dataclass
+class RobotIdentity:
+    manufacturer: str
+    model: str
+    controller: str
+    firmware: str
+    serial: str
+    joint_count: int = 6
+    joint_limits: list[JointState] = field(default_factory=list)
+    payload_kg: float = 0.0
+    reach_mm: float = 0.0
+
+
+@dataclass
+class RobotContext:
+    """Pre-formatted context block for LLM injection."""
+    identity: RobotIdentity | None = None
+    tcp: TCPPosition | None = None
+    joints: list[JointState] = field(default_factory=list)
+    io: IOState = field(default_factory=IOState)
+    programs: list[ProgramInfo] = field(default_factory=list)
+    tools: list[ToolData] = field(default_factory=list)
+
+    def to_prompt_block(self) -> str:
+        """Format as a text block for LLM system prompt injection."""
+        if not self.identity:
+            return ""
+        lines = [
+            "CONNECTED ROBOT (live data via RCP):",
+            f"  Model: {self.identity.manufacturer} {self.identity.model}",
+            f"  Controller: {self.identity.controller}",
+            f"  Firmware: {self.identity.firmware}",
+            f"  Serial: {self.identity.serial}",
+            f"  Payload: {self.identity.payload_kg} kg | Reach: {self.identity.reach_mm} mm",
+        ]
+        if self.tcp:
+            lines.append(f"  Current TCP: X={self.tcp.x:.1f} Y={self.tcp.y:.1f} Z={self.tcp.z:.1f} Rx={self.tcp.rx:.2f} Ry={self.tcp.ry:.2f} Rz={self.tcp.rz:.2f}")
+        if self.joints:
+            jstr = ", ".join(f"{j.name}={j.position_deg:.1f}" for j in self.joints)
+            lines.append(f"  Current joints: {jstr}")
+            limits = ", ".join(f"{j.name}: {j.min_deg:.0f} to {j.max_deg:.0f}" for j in self.joints)
+            lines.append(f"  Joint limits: {limits}")
+        if self.io.signals:
+            di = [s for s in self.io.signals if s.signal_type == "digital_input"]
+            do = [s for s in self.io.signals if s.signal_type == "digital_output"]
+            if di:
+                lines.append(f"  Digital inputs ({len(di)}): " + ", ".join(f"{s.name}={'HIGH' if s.value else 'LOW'}" for s in di[:8]))
+            if do:
+                lines.append(f"  Digital outputs ({len(do)}): " + ", ".join(f"{s.name}={'HIGH' if s.value else 'LOW'}" for s in do[:8]))
+        if self.programs:
+            loaded = [p for p in self.programs if p.loaded]
+            if loaded:
+                lines.append(f"  Loaded program: {loaded[0].name}" + (" (RUNNING)" if loaded[0].running else ""))
+        if self.tools:
+            for t in self.tools:
+                lines.append(f"  Tool: {t.name} TCP=({t.tcp_x:.1f},{t.tcp_y:.1f},{t.tcp_z:.1f}) mass={t.mass_kg:.1f}kg")
+        return "\n".join(lines)
+
+
+RiskLevel = Literal["SAFE", "GUARDED", "RESTRICTED", "PROHIBITED"]
+
+
+@dataclass
+class DiffResult:
+    """Result of diffing local code vs controller code."""
+    local_code: str
+    controller_code: str
+    added: int = 0
+    removed: int = 0
+    changed: int = 0
+
+    def summary(self) -> str:
+        return f"+{self.added} -{self.removed} ~{self.changed} lines"
+
+
+@dataclass
+class UploadResult:
+    success: bool
+    message: str = ""
+    audit_id: str = ""
+
+
+@dataclass
+class AuditEntry:
+    """Append-only audit log entry for GUARDED/RESTRICTED actions."""
+    id: str
+    timestamp: str  # ISO 8601
+    action: str
+    risk_level: RiskLevel
+    approved_by: str
+    robot: str  # "Manufacturer Model (SN: serial)"
+    params: dict = field(default_factory=dict)
+    result: str = ""  # "success", "failed", "rejected"
+    diff_summary: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "timestamp": self.timestamp,
+            "action": self.action,
+            "risk_level": self.risk_level,
+            "approved_by": self.approved_by,
+            "robot": self.robot,
+            "params": self.params,
+            "result": self.result,
+            "diff_summary": self.diff_summary,
+        }
+
+
+@dataclass
+class RCPEvent:
+    """A real-time event from the controller."""
+    channel: str  # "io_changed", "position_changed", "program_state", "error", "cycle", "safety"
+    data: dict = field(default_factory=dict)
+    timestamp: float = 0.0  # unix timestamp ms
+
+    def to_dict(self) -> dict:
+        return {"channel": self.channel, "data": self.data, "timestamp": self.timestamp}

rcp_sdk/safety.py

@@ -0,0 +1,54 @@
+"""RCP Safety — risk classifications for adapter actions.
+
+These are protocol-level constants. Adapters CANNOT override them.
+The ApprovalManager (host-specific) is NOT part of the SDK.
+"""
+
+from rcp_sdk.models import RiskLevel
+
+
+class RiskLevels:
+    """Named constants for the 4 safety tiers.
+
+    Use these instead of raw string literals to avoid typos and enable
+    static analysis. ``ACTION_RISK`` values are still strings for JSON
+    compatibility, but downstream code should compare against these.
+    """
+    SAFE: RiskLevel = "SAFE"
+    GUARDED: RiskLevel = "GUARDED"
+    RESTRICTED: RiskLevel = "RESTRICTED"
+    PROHIBITED: RiskLevel = "PROHIBITED"
+
+
+# Canonical mapping of action name → risk level.
+# Every action the protocol admits is listed here; unknown actions default
+# to GUARDED at the server dispatch site.
+ACTION_RISK: dict[str, RiskLevel] = {
+    # SAFE — no approval
+    "stop": "SAFE",
+    "capture_position": "SAFE",
+    "diff_program": "SAFE",
+    "validate": "SAFE",
+    "disable_freedrive": "SAFE",
+
+    # GUARDED — one-tap user approval
+    "upload_program": "GUARDED",
+    "set_io": "GUARDED",
+    "modify_tool_data": "GUARDED",
+    "enable_freedrive": "GUARDED",
+    # W2.48 — pulse DO for N ms with optional DI readback. No motion.
+    # Single approval covers the full pulse-and-readback sequence as one operation.
+    "test_device": "GUARDED",
+
+    # RESTRICTED — approval + safety-interlock verification
+    "move_to": "RESTRICTED",
+    "start_program": "RESTRICTED",
+    "jog": "RESTRICTED",
+    "home": "RESTRICTED",
+}
+
+PROHIBITED_ACTIONS = frozenset({
+    "override_safety",
+    "disable_estop",
+    "modify_safety_config",
+})