physicalai-runtime-adding-a-robot-integration

# Adding a Robot Integration Robots satisfy the structural `Robot` protocol in `src/physicalai/robot/interface.py` — no base class inheritance required. References: `src/physicalai/robot/so101/`, `src/physicalai/robot/trossen/` (WidowX). Connection helpers: `src/physicalai/robot/connect.py`; validation: `src/physicalai/robot/verify.py`. ## Workflow 1. **Read `references/robot-protocol.md`** and an existing integration (SO-101 for serial servos, WidowX for arms). - Done when: required methods and observation shape are listed. 2. **Implement connect lifecycle**: idempotent `connect()`, `disconnect()`, `is_connected()`. 3. **Observations**: return a type exposing `joint_positions`, `timestamp` (`time.monotonic()`), optional `sensor_data` / `images`; implement `state` property when inference expects more than positions. 4. **Actions**: `send_action(action, *, goal_time=...)` with `action` shape matching training data conventions; document joint order via `joint_names`. 5. **Optional extra** in `pyproject.toml` (`physicalai[so101]`, `physicalai[trossen]`); lazy-import vendor SDKs. 6. **Export** public class from `physicalai.robot` when user-facing. 7. **Tests** under `tests/unit/robot/` with mocked hardware. - Done when: `uv run pytest tests/unit/robot -k <name>` passes. 8. **Verification CLI/docs** — wire `verify.py` patterns if the robot supports automated checks. ## Required checks - `isinstance(robot, Robot)` at runtime (`@runtime_checkable` protocol). - No action sent when disconnected. - Joint count and `joint_names` stay stable across connect/disconnect. - Security: validate user-supplied port/path strings; no shell invocation with unsanitized device paths. ## References - `references/robot-protocol.md` - `docs/explanation/robots.md`