接口使用文档

本页是 Roban2 二次开发接口总览，用于选择 SDK、查找功能入口和完成首次运行。每个接口的完整字段、前提、C++ 代码和仓库示例放在 Roban2 C++ SDK 分页教程中，避免同一份接口说明在两处重复维护。

SDK 范围

SDK/工具	公开入口	功能范围
`lejusdk-lowlevel`	`<lejusdk-lowlevel/leju_sdk.h>`	机器人信息、关节状态、IMU、普通手柄、硬件状态；底层关节、双手、姿态高度和停止指令
`lejusdk-vr`	`<lejusdk-vr/lejusdk_vr.h>`	手臂、头部、腰部、速度、Quest 数据、控制模式、控制器、runtime、motion 和 tact
随包音频工具	`play_audio_cli`	请求 `audio_player_node` 播放本地音频；当前不是公开 C++ SDK

当前开发包不提供雷达、相机、旧版语音合成、手臂 FK/IK 等公开二次开发接口。本组文档不保留旧 Python SDK、ROS1、rosbridge 和 WebSocket 用法。

开发环境

Lejulab_ARM 已在 installed/ 中提供编译好的头文件、动态库、节点和示例，不需要重新编译 SDK。下文的 <Lejulab_ARM> 是开发包根目录占位符，请替换为开发者自己的实际目录。

Roban2.2 使用版本号 17：

cd <Lejulab_ARM>
export ROBOT_VERSION=17
source installed/setup.bash

必须先设置 ROBOT_VERSION，再加载 setup.bash。它会将 installed/bin 和 SDK 动态库加入当前终端环境。

启动基础控制链路

真机启动：

cd <Lejulab_ARM>
export ROBOT_VERSION=17
source installed/setup.bash
sudo -E bash src/leju_launch/scripts/launch_real.sh

launch_real.sh 启动硬件、游戏手柄、RL 控制器和记录器，并把麦克风、音频播放和系统监控作为可选节点启动。可选节点退出不会终止基础控制链路。

仿真启动和架构匹配说明参见仿真环境使用。

快速验证

在基础链路启动后，可直接运行随包的已编译示例：

hw_state_subscriber
joint_state_subscriber
imu_data_subscriber
vr_01_basic_init

vr_01_basic_init 是通用 VR SDK 初始化示例；其源码使用 KuavoVRAPI。Roban2 自己的程序应使用 leju::vr::RobanVRAPI，Roban 手臂可直接参考 vr_07_roban_arm。

功能入口

开发任务	主要 API	详细教程
SDK 初始化、目录和基本环境	`GlobalRobot`、`RobanVRAPI`	Roban2 C++ SDK 介绍
DDS 配置、共享内存和跨机排查	`CYCLONEDDS_URI`、Cyclone DDS、RouDi	DDS 通信与远程开发
基本信息、硬件、关节和 IMU	`getMotorNames()`、`subscribeHardwareState()`、`subscribeRobotState()`、`subscribeImuData()`	机器人信息与状态
普通手柄、Quest 手柄与骨骼位姿	`subscribeJoyData()`、`subscribeQuestJoystickData()`、`subscribeQuestBonePoses()`	机器人信息与状态
手臂、头部、腰部和双手	`publishArmJointCmd()`、`publishHeadJointCmd()`、`publishWaistJointCmd()`、`publishHandCmd()`	部位控制
高级全关节控制	`publishRobotCmd()`	部位控制
行走速度和姿态高度	`publishVrVelocityCmd()`、`publishVelocityCmd()`、`publishPostureHeightCmd()`	机器人移动与控制器
控制器、部位模式和 runtime	`getControllerState()`、`switchController()`、`set...Mode()`、`getRuntimeState()`、`startRuntime()`、`stopRuntime()`	机器人移动与控制器
CSV motion 和 tact 动作	`getMotionState()`、`startMotion()`、`playTact()`	动作与音频工具
本地音频文件	`play_audio_cli`	动作与音频工具

DDS Topic 总览

功能	SDK 数据类型	Topic
硬件状态	`StringData`	`/rt/hardware/state`
IMU	`ImuData`	`/rt/imu_state`
关节状态/指令	`RobotState` / `RobotCmd`	`/rt/joint_state` / `/rt/joint_cmd`
普通手柄	`JoyData`	`/rt/joy`
双手指令	`HandCmd`	`/rt/hand_cmd`
姿态高度	`double` 参数封装	`/rt/posture_height_cmd`
停止	SDK 内部封装	`/rt/hardware/stop`
手臂/头部/腰部	`JointTrajectoryPoint`	`/rt/arm_trajectory`、`/rt/head_trajectory`、`/rt/waist_trajectory`
最终速度/VR 输入速度	`VelocityCmd` / `VrVelocityCmd`	`/rt/cmd_vel` / `/rt/vr/cmd_vel`
Quest 骨骼/手柄	`QuestBonePosesData` / `QuestJoystickData`	`/rt/quest/bone_poses` / `/rt/quest/joysticks`

控制器切换、模式设置、状态查询、runtime 启停和动作播放使用 SDK 内部封装的 DDS-RPC，不需要业务程序自行生成 RPC 消息。

VR 遥操启动入口

src/leju_launch/launch/vr_teleop.launch 本身不启动真机硬件和主控制器。它启动：

quest_udp_to_dds_node：接收 Quest UDP 数据并发布 Quest DDS 话题。
quest_vr_abs_control_node：默认的绝对 IK 控制。
quest_vr_control_node：use_incremental_ik:=true 时使用的增量 IK 控制。

已提供 roslaunch 的完整开发环境可在基础控制链路启动后运行：

cd <Lejulab_ARM>
export ROBOT_VERSION=17
source installed/setup.bash
roslaunch leju_launch vr_teleop.launch robot_version:=17

指定 Quest IP 或使用增量 IK：

roslaunch leju_launch vr_teleop.launch \
  robot_version:=17 \
  quest_ip:=<Quest-IP> \
  use_incremental_ik:=true

如果随包部署环境不包含 roslaunch，可在已加载 SDK 环境的两个终端中分别运行：

# 终端 1：Quest UDP -> DDS
export LEJU_ASSETS_PATH="$PWD/src/leju_assets"
quest_udp_to_dds_node

# 终端 2：默认绝对 IK
export LEJU_ASSETS_PATH="$PWD/src/leju_assets"
quest_vr_abs_control_node

二次开发最小骨架

#include <lejusdk-vr/lejusdk_vr.h>

int main() {
  const auto version = leju::RobotVersion::from_env();
  leju::vr::RobanVRAPI vr(version);
  if (!vr.initialize()) return 1;

  leju::vr::ControllerState state;
  if (vr.getControllerState(state)) {
    // 在这里根据服务端的实际状态选择后续功能。
  }

  vr.shutdown();
  return 0;
}

用户工程需使用 C++17，并链接对应 SDK 动态库。仓库中的 src/lejusdk/examples/CMakeLists.txt 是链接 lejusdk-lowlevel 和 lejusdk-vr 的实际参考；它用于开发者自己的程序，不表示需要重新编译 Lejulab_ARM SDK。

实机安全

读取状态不会驱动机器人。任何 publish*Cmd()、模式切换、startRuntime()、startMotion() 或 playTact() 都可能使机器人运动。实机测试前必须固定机器人、清空活动区域、确认急停可用，并由现场人员监护。

编写依据

本组文档的接口名、数据类型和示例以开发包中以下文件为准：

installed/include/lejusdk-lowlevel/robot_api/robot_base.h
installed/include/lejusdk-lowlevel/data_types.h
installed/include/lejusdk-vr/vr_api/vr_base.h
installed/include/lejusdk-vr/data_types.h
src/lejusdk/examples/
src/leju_launch/

接口使用文档

SDK 范围​

开发环境​

启动基础控制链路​

快速验证​

功能入口​

DDS Topic 总览​

VR 遥操启动入口​

二次开发最小骨架​

编写依据​