接入新硬件
为一套机器人实现机械臂、夹爪和腕部相机适配，接入 RoboAPI 本地控制台。
接入一套新的机器人，需要将机械臂、平行夹爪和腕部相机接入 RoboAPI 的统一接口。完成后，这套硬件便可使用共享的标定、模型调用、任务执行和本地控制台。
本页以开发一套完整的适配器为主线：生成工程，实现三个组件的驱动，安装并选择组件，再完成标定和运行。已有组件可以复用，单独扩展某个组件的方法见文末的可选说明。
本页面向需要对接厂商 SDK 的开发者。准备好 Python 环境、厂商 SDK 和设备连接信息。在运行 RoboAPI 的环境中安装 0.4.5，并确认生成命令可用：
uv pip install 'roboapi==0.4.5'
roboapi new-embodiment --help1. 生成适配器工程
在 RoboAPI 所在的 Python 环境中执行：
roboapi new-embodiment acme生成的 roboapi-acme/ 是独立 Python 项目：
roboapi-acme/
├── pyproject.toml
├── README.md
└── src/roboapi_acme/
├── __init__.py
├── arm.py
├── gripper.py
└── camera.py将 acme 换为你的适配器名称，使用小写字母开头的字母、数字、连字符或下划线。名称不能与所选组件的内置名称冲突。命令会新建目录，已有同名目录时停止，不覆盖文件。
工程已经包含注册入口、配置类和驱动接口。生成的驱动方法会抛出 NotImplementedError；完成 SDK 实现后再连接设备。
2. 实现设备驱动
在 pyproject.toml 中添加 SDK 依赖，并在对应文件中实现：
| 文件 | 需要实现的行为 |
|---|---|
arm.py | 控制连接、测量位姿、关节状态、目标更新、故障恢复，以及独立的只读反馈 |
gripper.py | 读取开度、非阻塞设置开度、可取消的阻塞移动、恢复与资源释放 |
camera.py | 采集原始视角的 RGB 图像、报告帧龄、等待新帧与取消读取 |
导入适配器、构造配置和创建驱动对象时，保持设备未连接。将可选 SDK 导入与设备访问放到 connect() 等显式连接步骤中。
机械臂反馈和控制都以法兰中心为控制点，使用相同的原生基坐标和法兰轴。驱动提供原生测量值，由 RoboAPI 完成标定坐标转换。方法签名、单位和四元数顺序见硬件适配接口。
如果机械臂和夹爪共用一个 CAN 连接或 SDK 会话，由适配器包统一管理连接、目标与反馈；分别注册组件仍可复用同一个物理连接。
3. 安装到 RoboAPI 环境
完成驱动后，在运行 RoboAPI 的同一 Python 环境中安装：
uv pip install -e ./roboapi-acme开发期间使用可编辑安装，便于调整驱动。安装完成后重新启动 RoboAPI，使程序重新发现组件入口。
生成器已在 pyproject.toml 中写入 roboapi.arms、roboapi.grippers 和 roboapi.cameras 注册项；无需另外添加设备列表或修改 RoboAPI 主程序。
4. 选择组件与配置设备
为新硬件建立独立配置，填写地址、设备路径、模型连接和凭据：
roboapi init -c ~/.config/roboapi-acme/config.yaml
roboapi http -c ~/.config/roboapi-acme/config.yaml向导依次选择机械臂、夹爪和相机。可以选择三种 acme 组件，也可以搭配已安装的其他组件。模型 Base URL 默认为 https://api.pokebot.com/v1；填写 Key 并连接后，从返回的模型列表中选择。使用兼容服务时填写对应的地址，初始化过程中保持模型服务可访问。
组件有自己的地址、路径或凭据时，由适配器的 configure() 提供对应问题。密码与 Key 使用向导提供的凭据文件机制保存。
需要外部负载数据的机械臂，可以在注册时提供 configure_tool()，让向导填写整套法兰附件的质量、质心和惯量。已有内置动力学模型的控制器可按驱动要求处理负载。数据含义与回调约定见工具负载。
5. 标定并运行
在控制电脑打开 http://127.0.0.1:8080/：
- 检查相机持续更新，机械臂的只读反馈与实际位置一致。
- 进入 设置 → 设备 → 坐标标定，采集初始位置与 A/B/C。
- 支持原生手动引导时按界面选择轴；其他设备使用自身示教控制。采 C 后，网页返回初始位置、保存标定并初始化设备。
- 完成方向试动，确认显示坐标、夹爪开度和实际运动一致，再从本地控制台发送任务。
- 使用 Robot Stop 检查停止与保持行为；发生设备故障时，修复条件后使用恢复操作。
更换装配、初始位置或任务坐标轴后重新标定。机械臂应在等待推理时保持位置；目标更新、停止和恢复的职责见连接与运行行为。
可选：只扩展一个组件
已有可复用组件时，可以只生成需要开发的部分：
| 组件 | 生成命令 |
|---|---|
| 机械臂 | roboapi new-embodiment acme-arm --components arm --directory ./adapters |
| 夹爪 | roboapi new-embodiment acme-gripper --components gripper --directory ./adapters |
| 相机 | roboapi new-embodiment acme-camera --components camera --directory ./adapters |
完成所选驱动后，按命令输出的安装路径将工程安装到同一 RoboAPI 环境。在初始化向导中选择新组件，搭配已有的其他组件，再按上面的流程标定并运行。每个组件均需满足硬件适配接口的约定。
分发适配器
适配器可以打包为独立 wheel，供其他用户安装到 RoboAPI 环境。发布时在 pyproject.toml 声明厂商 SDK 依赖和支持的 RoboAPI 版本范围，以实际包含所用接口的版本作为下限。
同时说明设备型号、控制器系统要求、连接方式、负载配置和标定方法。完整注册与设备约定见硬件适配接口。