硬件适配接口
机械臂、反馈、夹爪和相机的注册方式、配置与运行约定。
硬件适配器是安装到 RoboAPI 环境中的独立 Python 包。它通过 entry points 注册组件，由初始化向导选择，并与本地控制台、HTTP 和 MCP 共用同一运行时。开发流程见接入新硬件。
职责与数据边界
| RoboAPI 提供 | 适配器实现 |
|---|---|
| 初始位置与 A/B/C 标定、训练坐标映射 | 设备原生基坐标和法兰中心的测量、控制 |
| 路径、动作时序、30 Hz 目标下发 | SDK 连接、原生控制频率、插值与保持 |
| 模型会话、本地控制台、HTTP/MCP | 设备故障、恢复、连接释放 |
| 组件选择与配置保存 | 组件配置字段、安装值校验与 SDK 依赖 |
驱动中的位姿为米与 wxyz 四元数：
[x, y, z, qw, qx, qy, qz]模型请求与动作的八维数组使用 xyzw，并附带夹爪开度：
[x, y, z, qx, qy, qz, qw, gripper]驱动读写原生法兰坐标，由共享运行时完成与模型任务坐标的转换。反馈与控制必须采用相同控制点、原生基坐标和法兰轴；TCP 不增加位置偏移。
注册组件
在包的 pyproject.toml 中声明需要提供的组件：
[project.entry-points."roboapi.arms"]
acme = "roboapi_acme.arm:arm_plugin"
[project.entry-points."roboapi.grippers"]
acme = "roboapi_acme.gripper:gripper_plugin"
[project.entry-points."roboapi.cameras"]
acme = "roboapi_acme.camera:camera_plugin"| 注册组 | 工厂返回值 | 创建设备 |
|---|---|---|
roboapi.arms | ArmPlugin | create(config, tool) |
roboapi.grippers | ComponentPlugin | create(config) |
roboapi.cameras | ComponentPlugin | create(config) |
同一注册组内名称唯一；不同组件组可使用相同名称。名称不能覆盖内置组件。安装失败或依赖缺失的外部适配器会在向导中提示并跳过；已有配置选中了该适配器时，会报告加载错误。
每个工厂提供以下内容：
| 字段 | 约定 |
|---|---|
options | 非空的 ComponentOption 元组，每项包含展示名称与配置类 |
create | 创建设备对象；构造时保持设备未连接 |
configure(option, setup) | 返回本次选择的组件配置 |
setup_notes | 可选的安装完成提示元组 |
ArmPlugin 还必须提供 create_feedback(config)，并可提供 create_guiding(config, tool) 和 configure_tool(setup)。
一个工厂支持多种型号时，用 ComponentOption.selectors 区分，例如 {"model": "a"}。对应字段也应在配置类中声明，并保留在 YAML 中，使配置能唯一选中一个选项。
配置与初始化向导
组件配置继承 ArmConfig、GripperConfig 或 CameraConfig。下面是生成工程中相机配置的结构：
from dataclasses import dataclass
from roboapi.hardware import CameraConfig
@dataclass
class AcmeCameraConfig(CameraConfig):
type: str = "acme"
address: str = ""
@property
def connection_id(self) -> str:
return self.address
def configure(option, setup):
return option.config_type(
address=setup.ask("Camera address or device path"),
)type 与 entry-point 名称一致。connection_id 是非空、稳定的设备连接标识；改变连接身份时应重新确认标定。配置应可用默认值构造，在 validate() 中校验安装值；覆盖校验时先调用 super().validate()。
向导提供的 setup：
| 成员 | 用法 |
|---|---|
ask(label, default="") | 读取字符串 |
choose(label, choices) | 展示选项并返回从 0 开始的索引 |
device(label, patterns, default) | 从设备路径候选中选择，或手工输入 |
secret(label, filename) | 返回独立凭据文件路径，向导保存配置时写入；文件名使用单个名称 |
config | 当前安装配置，可读取前面已经选择的组件 |
配置顺序为机械臂 → 夹爪 → 相机，再按机械臂需要收集工具负载。夹爪可以根据已选机械臂建议地址。凭据使用 secret()，配置中保存路径；SDK 导入和设备连接留到显式连接阶段。
机械臂与只读反馈
接口从 roboapi.hardware 导出。机械臂实现 Arm：
| 成员 | 行为 |
|---|---|
live、last_error | 当前是否可接受控制；不可用时提供错误原因 |
connect(*, calibration=False) | 建立控制连接，准备接收目标；临时标定返回期间保留力传感器零点 |
disconnect() | 停止并等待控制工作线程退出，释放设备与控制权 |
get_joints() | 返回弧度制关节位置；关节数量由设备决定 |
get_eef_pose() | 返回实际测量的原生法兰中心位姿，长度 7、wxyz |
servo_pose(pose7, twist=None, *, position_only=False) | 非阻塞更新目标；线速度为 m/s，角速度为 rad/s |
validate_calibration(device) | 核对控制连接与采样时的设备身份、法兰约定一致 |
recover(should_stop=None) | 恢复设备控制，响应取消；后续返回初始位置由运行时处理 |
position_only=True 要求跟踪目标时不叠加力驱动的偏移。驱动负责内部插值、控制周期和无新目标期间的保持。返回的是测量状态，不能用上一次下发的目标代替。
create_feedback(config) 返回独立的 FeedbackReader。示教或采集标定点时，只读反馈应可用，且不因读取状态而取得运动控制权。
| 成员 | 行为 |
|---|---|
live、last_error | 反馈连接状态与错误原因 |
connect()、disconnect() | 建立、释放只读连接 |
snapshot() | 返回包含 pose、timestamp、device 的字典，可附带 has_errors |
validate_device(device) | 核对已保存的设备身份和设置 |
pose 为测量的原生法兰位姿。timestamp 对应真实采样并递增；设备重复返回同一采样时，不得生成新时间戳。device 是稳定、可 JSON 序列化的身份与设置，用于复用标定前的核对。
可选的原生手动引导
create_guiding(config, tool) 返回 GuidingSession：
| 成员 | 行为 |
|---|---|
active | 当前是否处于原生引导状态 |
start(axis=None) | 开始引导；None 允许调整初始位置 |
set_axis(axis=None) | x、y、z 只允许对应平移，约束旋转及其他平移轴 |
check_stopped() | 确认引导已经停下，供采样与模式切换使用 |
close() | 结束引导并释放资源 |
未提供原生引导时，用户通过机器人自身的示教控制采集初始位置与 A/B/C，只读反馈仍需可用。
夹爪
夹爪实现 Gripper，使用单一的平行夹爪开度：0 为闭合，1 为张开。
| 成员 | 行为 |
|---|---|
live、last_error | 连接与故障状态 |
connect()、disconnect() | 连接设备并释放资源 |
get_ratio() | 返回测量的归一化开度 |
set_ratio(ratio) | 非阻塞更新开度目标 |
move_blocking(ratio, should_stop=None) | 等待移动完成，并响应取消 |
recover() | 恢复夹爪故障 |
在 GripperConfig.full_travel_s 中设置完整开合时间，单位为秒，必须是有限正数。共享运动调度使用这个值安排夹爪动作；设备通信放在驱动内部，避免阻塞 30 Hz 的目标下发。
相机
相机实现 Camera：
| 成员 | 行为 |
|---|---|
live、last_error | 连接、采集与帧过期状态 |
connect()、disconnect() | 开始采集并释放采集资源 |
read() | 返回 (image, age_s) |
read_after(after, timeout_s, should_stop=None) | 在时限内等待时间戳晚于 after 的帧；after=None 取最新帧，取消时返回 None |
image 为 uint8 RGB 数组，形状 (720, 1280, 3)，采集速率 30 FPS。age_s 为距离该帧采集的真实秒数。保留原始方向、视角与鱼眼畸变，不裁剪、补边或镜像；将 BGR 等传输格式转换为 RGB。
after 使用单调时钟的时间戳，驱动需正确关联设备采集时间。不能在读取旧缓存时把帧龄重置为零。在 CameraConfig.stale_after_s 中配置帧过期阈值，必须是有限正数。
工具负载
仅在机械臂需要外部惯性数据时注册 configure_tool(setup)。回调在组件选择后执行，返回 ToolLoad 或 None；未注册回调时不询问工具负载。负载传入机械臂的控制与引导工厂，由驱动应用或核对。
ToolLoad 字段 | 含义与单位 |
|---|---|
mass_kg | 整套法兰附件的质量，kg |
com_flange_m | 质心在法兰坐标中的三维位置，m |
inertia_kg_m2 | 关于质心、轴平行于法兰的 3×3 惯量矩阵，kg·m² |
质量非负；数值有限；惯量矩阵对称、半正定。数据应覆盖夹爪、相机和适配件等完整装配，避免重复计入控制器动力学模型中已有的部件。
Franka 使用本地 tool 负载配置；UR 在 PolyScope 中配置负载。标准装配数据仅用于与其匹配的硬件。工具负载、法兰 TCP 与空间标定分别配置，更新负载不能代替重新标定。
连接与运行行为
- 注册和对象构造保持无设备访问；将可选 SDK 导入延迟到连接时。
- 运行时以 30 Hz 下发目标；驱动保持自己的原生控制循环，并在等待下一次推理时维持保持。
- 可实现可选的
hold()供停止操作调用。机械臂未提供时，运行时发送当前测量位姿作为保持目标；夹爪需要立即中止运动时，应提供自己的hold()。 - 停止与恢复响应取消，清理允许重复调用，并处理仅部分连接成功的情况。
- 同一 CAN 或 SDK 会话服务多个组件时，由适配器包协调访问和生命周期，在所有使用者释放后关闭连接。
接入后依次检查：组件发现和配置保存、实际反馈与设备身份、标定与返回、连续动作、推理等待期间保持、停止和恢复。准备教程见接入新硬件。