用途:在 PhysicalAI 运行时(openvinotoolkit/physicalai)中添加或修改 physicalai.robot 下的机器人硬件集成。
主要能力与约定:机器人只需满足 src/physicalai/robot/interface.py 中的结构化 Robot 协议,无需继承基类。可参考 src/physicalai/robot/so101/(串行舵机)与 src/physicalai/robot/trossen/(WidowX 机械臂)。连接辅助见 src/physicalai/robot/connect.py,验证见 src/physicalai/robot/verify.py。
工作流:先读 references/robot-protocol.md 及一个现有集成,列出所需方法与观测结构;实现连接生命周期 connect()(幂等)、disconnect()、is_connected();观测返回可访问 joint_positions、timestamp(time.monotonic())的类型,可选 sensor_data / images,当推理需要位置以外信息时实现 state 属性;动作通过 send_action(action, *, goal_time=...) 发送,形状与训练数据约定一致,并用 joint_names 记录关节顺序;可选在 pyproject.toml 中加 physicalai[so101]、physicalai[trossen] 等 extra,并惰性导入厂商 SDK;面向用户时从 physicalai.robot 导出公开类;在 tests/unit/robot/ 下用模拟硬件编写测试。
必要检查:运行时 isinstance(robot, Robot)(@runtime_checkable 协议);断开时不得发送动作;关节数量与 joint_names 在连接/断开间保持稳定;安全上校验用户提供的端口/路径字符串,禁止用未净化设备路径调用 shell。
完成标准:uv run pytest tests/unit/robot -k <name> 通过;若机器人支持自动化检查,接入 verify.py 模式。