SDK 二开接口开发示例
本文将介绍如何使用 RFrame SDK 开发并运行 C++ 应用，完成相机图像接收、关节状态订阅、运动指令发送和执行结果检查。示例通过一次头部俯仰运动演示接口调用的完整流程。
操作流程：准备工程 → 上传工程 → 通过 RobbyantGo 连接 → 编译与测试 → 预览 → 执行 → 查看结果与图像。
1. 前置条件
- R2 已提供可通过 SSH 访问的开发环境，并已安装 RFrame SDK、消息包及编译工具。
- 开发电脑已安装 RobbyantGo，可访问目标机器人，并已取得登录凭据。文件传输命令以 macOS 终端为例。
- 机器人构型与示例配置匹配，运动前已确认设备状态和现场条件。具体要求见“执行头部运动”和“适用环境与限制”。
示例工程随本文提供，目录为 rframe_cpp_quickstart。
文件上传与下载使用开发电脑终端；环境加载、编译和运行命令在 RobbyantGo 的 SSH 终端中执行。
第 1 步：准备示例工程
获取示例工程并保留以下目录结构：
rframe_cpp_quickstart/
├── CMakeLists.txt # 编译程序与两个纯数据测试
├── src/
│ ├── main.cpp # 相机取帧后串联运动业务流程
│ └── camera_capture.cpp # SDK 接收一帧压缩图像并保存
├── include/quickstart/
│ ├── sdk_client.hpp # SDK 生命周期和 Service 调用
│ ├── joint_feedback.hpp # SDK 订阅关节反馈
│ ├── motion_profile.hpp # 构型、目标计算与校验
│ ├── camera_capture.hpp # 相机取帧函数声明
│ └── image_file.hpp # 根据文件头识别图片格式
├── config/
│ ├── channels.json # 关节反馈及运动 Service 配置
│ └── camera.json # 头部彩色相机订阅配置
└── tests/
├── motion_profile_test.cpp # 运动目标与数据校验，不控制机器人
└── image_file_test.cpp # 图片格式识别与非法输入校验
示例已提供配套的 C++ 源码、JSON 配置和 CMake 构建文件，无需修改即可按本文运行。运动幅度和速度缩放通过命令行参数指定。
示例包含两份 SDK 通信配置：channels.json 配置关节反馈和运动接口，camera.json 配置相机接口。运行时需保留这两份文件。SDK 同时支持在 C++ 中构造配置；本文采用 JSON 加载方式。
第 2 步：上传工程
将完整工程上传至开发环境的 /tmp 目录。
在本地终端执行以下命令，输入解压后 rframe_cpp_quickstart 所在的父目录绝对路径：
printf '示例工程父目录的绝对路径：'
read -r SAMPLE_PARENT
cd "${SAMPLE_PARENT}"
然后执行，按提示填写机器人 IP 或主机名：
printf '机器人 IP 或主机名：'
read -r ROBOT_HOST
scp -P 2222 -r ./rframe_cpp_quickstart "robot@${ROBOT_HOST}:/tmp/"
ROBOT_HOST 应与 RobbyantGo 连接的目标机器人一致。
上传后的工程路径为 /tmp/rframe_cpp_quickstart。
第 3 步：通过 RobbyantGo 连接开发环境
在 RobbyantGo 中连接目标机器人，并打开其 SSH 功能。按连接提示完成身份认证后，直接进入机器人开发环境。
后续环境加载、编译和运行命令均在该终端中执行。
第 4 步：加载开发环境
加载 SDK 运行依赖并进入工程目录：
source /opt/ros/humble/setup.bash
source /opt/robby/r-types/setup.bash
cd /tmp/rframe_cpp_quickstart
每次新建 RobbyantGo SSH 会话后均需加载环境。应用通过 RFrame SDK 使用通信能力。
开发目录说明： 可直接在开发环境中编辑源码。 本例工程目录为
/tmp/rframe_cpp_quickstart，可以在这里编辑 C++ 和 JSON，再重新编译运行。/tmp用于临时验证，重要源码应在开发电脑上保留副本。若使用开发指南建议的/mnt/ssd/workspace，需同步调整后续源码、编译和配置路径。
第 5 步：编译程序
配置构建目录：
cmake -S /tmp/rframe_cpp_quickstart \
-B /tmp/rframe_cpp_quickstart-build \
-DCMAKE_BUILD_TYPE=Release
配置成功后执行构建：
cmake --build /tmp/rframe_cpp_quickstart-build -j2
预期结果： 看到 Built target head_movej_rframe。可执行程序是：
/tmp/rframe_cpp_quickstart-build/head_movej_rframe
第 6 步：运行代码校验测试
检查目标计算、关节数组、限位，以及图片格式识别和非法输入处理。这些测试不连接机器人，不会让机器人运动。
ctest --test-dir /tmp/rframe_cpp_quickstart-build --output-on-failure
预期结果： 当前工程包含 motion_profile 和 image_file 两项测试，应显示两项均 Passed、100% tests passed。图片测试检查文件头识别，不代替真实图片解码查看。
第 7 步：接收图像并预览运动目标
先通过 SDK 接收一帧头部彩色相机数据，保存到开发环境目录；然后接收真实关节反馈、查询系统状态并计算动作目标。本步会写图片文件，但不发送运动请求。
cd /tmp/rframe_cpp_quickstart
/tmp/rframe_cpp_quickstart-build/head_movej_rframe \
--config /tmp/rframe_cpp_quickstart/config/channels.json \
--camera-config /tmp/rframe_cpp_quickstart/config/camera.json \
--output-dir /tmp/rframe-camera \
--delta-deg 3 --scale 0.01
命令使用工程自带的两份 JSON 配置，无需调整。
| 参数 | 作用 |
|---|---|
| --config | 指定关节反馈和运动接口配置 |
| --camera-config | 指定相机接口配置 |
| --output-dir | 图片保存目录，程序会创建；本例在机器人开发环境 |
| --delta-deg 3 | 计划在当前头部位置基础上增加 3° |
| --scale 0.01 | MoveJ 的速度缩放，不是每秒转动角度 |
预期结果：
输出 CAMERA_RECEIVED、CAMERA_SAVED 和 CAMERA_OUTPUT，并记录图片绝对路径。取帧或保存失败会退出，不进入后面的运动流程。
SYSTEM_STATE显示mode=0 state=2 IDLE error=0。- 出现
FEEDBACK_READY，表示反馈新鲜、关节配置匹配、静止检查通过。 - 目标表中只有 J_NeckPitch 改变约 0.052360 rad（3°），其他 19 轴目标不变。
- 输出
PREVIEW_COMPLETE和no movement request sent。
没有 --execute 就不会发出 MoveJ。 如果反馈缺失、状态错误、构型不匹配或限位检查失败，先解决问题，不进入运动步骤。
第 8 步：执行头部运动
预览通过后，通过 SDK 调用 MoveJ，执行一次头部俯仰运动。
执行前确认：构型与限位已核对，机器人无人接触、活动范围清空，没有其他程序同时控制运动，物理急停可触达。
/tmp/rframe_cpp_quickstart-build/head_movej_rframe \
--config /tmp/rframe_cpp_quickstart/config/channels.json \
--camera-config /tmp/rframe_cpp_quickstart/config/camera.json \
--output-dir /tmp/rframe-camera \
--delta-deg 3 --scale 0.01 --execute --profile-reviewed
本次执行也会先保存一张新图片，再进入运动预览。无需单独运行另一个相机程序。
执行模式参数：
--execute：允许进入运动确认流程。--profile-reviewed：表示操作者已核对构型与限位，该参数不替代现场核对。
程序会再次显示预览，并等待输入。只有输入 MOVE 才会继续检查状态和位置，然后发送一次运动请求。 输入其他内容则取消。
运动完成后保持目标位置，不自动回位。每次执行均基于最新位置增加 3°，重复执行会累积位移。
MoveJ 是整机关节目标接口，本例仅修改头部目标；其他目标取发送前的位置。其他部位出现意外运动时，直接使用物理急停，不依赖终端或网络停止。
第 9 步：检查执行结果
结合服务响应、任务状态和关节反馈检查执行结果。请求被接受仅表示服务端接收成功，不能据此判定运动完成。
| 日志 | 说明 | 能否判定完成 |
|---|---|---|
| REQUEST_SENT | 开始调用 MoveJ | 不能 |
| REQUEST_ACCEPTED | 收到响应，请求被接受 | 不能 |
| HEAD_FEEDBACK | 来自持续订阅的头部反馈：当前角度、目标角度、相对发送前的位移（单位 °） | 用于观察变化，不单独判定完成 |
| TASK_STATUS status=2 | 任务正在执行 | 不能 |
| TASK_STATUS status=0 | 服务端报告任务成功 | 还需检查实际反馈 |
| RESULT_VERIFIED | 反馈误差、其他轴偏移、静止和系统状态检查通过 | 本例结果检查通过 |
| COMPLETED | 正常流程结束，没有自动回位 | 完成 |
运动期间，关节订阅持续更新。HEAD_FEEDBACK 复用检查中的最新快照，最多每 500 ms 输出一次：current_deg 为当前角度，target_deg 为目标角度，moved_deg 为相对发送前位置的变化。该日志来自关节反馈，TASK_STATUS 来自任务查询，两者来源不同。任务较短或 Service 等待较久时，中间输出可能较少，最终仍以 RESULT_VERIFIED 为准。
RESULT_VERIFIED 表示反馈误差满足本例的 0.003 rad 阈值，同时通过其他关节偏移、静止和系统状态检查。该阈值是示例的结果检查条件，不代表产品精度规格。
任务较短时可能无法观察到 status=2，应以任务成功状态及最终反馈校验为准。
程序退出时的 AppCore、ChannelManager 和 ROS2 runtime shutdown 日志表示应用正在释放资源。
第 10 步：下载并查看图像
从开发环境的 /tmp/rframe-camera 直接下载图片到电脑桌面。
程序结束时的 WORKFLOW_EXIT result=0 image=... 给出结果与图片路径。执行模式下还应看到 COMPLETED；只有预览时会看到 PREVIEW_COMPLETE。
printf '机器人 IP 或主机名：'
read -r ROBOT_HOST
scp -P 2222 -r "robot@${ROBOT_HOST}:/tmp/rframe-camera" "$HOME/Desktop/"
open "$HOME/Desktop/rframe-camera"
预览和正式执行各会保存一帧，因此可能有多张 head_color_... 图片；按本次日志中的文件名查找。
根据日志中的文件名，在桌面 rframe-camera 目录查看对应图像。
输出为运动前采集的单帧图像。程序直接保存接收到的压缩图像数据，按文件头识别为 .jpg、.png 或 .tiff，不需要安装 OpenCV。
下载已有图像无需重新运行示例。
2. 接口与验证方法
| 验证内容 | 接口或能力 | 验证方法 |
|---|---|---|
| 开发环境可用 | CMake、C++ 编译器、RFrame 和消息包 | 上传本地工程、加载开发环境，完成编译并运行 |
| SDK 初始化和配置 | AppCore、JSON 配置、Channel 创建 | 程序读取配套 JSON，成功打开通道并完成后续通信 |
| 接收相机数据 | Topic：/robby/sensors/camera/head/color/compressed | 通过 SDK 订阅一帧压缩图像，保存文件，导出到电脑并查看 |
| 接收关节数据 | Topic：/robotic/joint_states | 持续接收真实关节位置和速度，用于计算目标、检查状态及核对运动结果 |
| 查询机器人状态 | Service：/robotic/get_system_state_cmd | 运动前后查询，确认返回 IDLE、error=0 等状态 |
| 发送运动控制 | Service：/robotic/movej_cmd | 根据当前反馈构造目标，只修改头部俯仰目标，确认后发送一次请求 |
| 查询运动任务 | Service：/robotic/task_status_cmd | 根据任务 ID 查询执行状态，并确认任务成功 |
| 验证实际执行效果 | 任务结果＋关节反馈＋系统状态 | 核对头部到达目标、其他轴偏移在程序阈值内，并确认系统恢复空闲 |
示例通过 Topic 订阅接收相机和关节数据，通过 Service 请求发送运动指令。本流程不包含 Topic 发布、RPC 服务端开发或各通信后端的独立验证。/robotic/stop_cmd 用于异常处理，未纳入本流程的正常执行验证。
3. 适用环境与限制
本指南以 R2 已提供可通过 SSH 访问、已安装 SDK 及依赖的开发环境为前提。若设备尚未提供该环境，应先按对应交付流程准备。
本例仅适用于已核对的 20 本体轴构型，头部关节为 J_NeckPitch。构型顺序和限位在 motion_profile.hpp 中集中定义，换机须重新确认。
程序包含反馈新鲜度、静止、姿态漂移和目标误差检查，但不是安全认证。同步 RPC 有 3 秒等待预算，结果观察预算 15 秒；超时不代表服务端运动取消。异常时软件停止可能失败，不能替代现场物理急停。