机器人信息与状态接口

本页记录 Roban2 当前可用的基本信息、硬件状态、关节状态、IMU、普通手柄和 Quest 输入接口。

通用初始化

lejusdk-lowlevel 的订阅接口使用全局机器人实例：

const auto version = leju::RobotVersion::from_env();
if (!leju::GlobalRobot::init_env(version)) return 1;
auto& robot = leju::GlobalRobot::getInstance();

GlobalRobot::init_env() 在同一进程中只调用一次。下文低层 SDK 代码片段默认 robot 已按上述方式初始化。

机器人基本信息

1. 功能描述

查询机器人版本、电机数量、全部关节名称，以及手臂、腰部、头部和腿部关节名称。后续解析关节数组时应以 SDK 返回的名称顺序为准。

2. 所属 SDK 和头文件

SDK：lejusdk-lowlevel
头文件：<lejusdk-lowlevel/leju_sdk.h>
对象：leju::RobotBaseAPI

3. 请求或消息类型

uint8_t getMotorNumber() const;
std::vector<std::string> getMotorNames() const;
std::vector<std::string> getArmJointNames() const;
std::vector<std::string> getWaistJointNames() const;
std::vector<std::string> getHeadJointNames() const;
std::vector<std::string> getLegJointNames() const;
const leju::RobotVersion& getRobotVersion() const;

4. 字段说明

无请求字段。关节名称接口返回有序字符串数组，其下标与 RobotState 和 RobotCmd 中的关节下标对应。

5. 返回值

getMotorNumber()：电机数量。
get...JointNames()：对应部位的关节名称数组。
getRobotVersion()：当前实例使用的 RobotVersion 引用。

6. 使用前提

ROBOT_VERSION 已设置为实际机型版本；Roban2.2 使用 17。
已成功调用 GlobalRobot::init_env()。
该查询来自 SDK 的机型定义，不需要等待 DDS 状态消息。

7. C++ 示例

#include <iostream>
#include <lejusdk-lowlevel/leju_sdk.h>

int main() {
  const auto version = leju::RobotVersion::from_env();
  if (!leju::GlobalRobot::init_env(version)) return 1;
  auto& robot = leju::GlobalRobot::getInstance();

  std::cout << "motor count: "
            << static_cast<int>(robot.getMotorNumber()) << '\n';
  for (const auto& name : robot.getMotorNames()) {
    std::cout << name << '\n';
  }
  robot.shutdown();
  return 0;
}

8. 对应仓库示例

src/lejusdk/examples/src/joint_cmd_publisher.cpp
src/lejusdk/examples/src/kuavo_control_example.cpp

两个示例均通过 getMotorNames() 建立关节顺序；其中文件名保留了通用历史命名，不代表本页使用 Kuavo 机型。

硬件状态

1. 功能描述

subscribeHardwareState() 持续接收底层硬件阶段。使用底层关节指令的程序应等待 READY_OK 后再发布。

2. 所属 SDK 和头文件

SDK：lejusdk-lowlevel
头文件：<lejusdk-lowlevel/leju_sdk.h>

3. 请求或消息类型

void subscribeHardwareState(const leju::HwStateCallback& callback);
using HwStateCallback =
    std::function<void(const leju::StringDataConstPtr&)>;

4. 字段说明

字段	类型	说明
`timestamp`	`double`	时间戳，单位 s
`data`	`std::string`	硬件状态字符串，包括 `unknown`、`initializing`、`ready_ok`、`error`

String2HwState() 可将字符串转为 HardwareState：UNKNOWN、STOPPED、ERROR、INITIALIZING、READY_OK。

5. 返回值

订阅方法无返回值；新状态到达时在 DDS 接收线程调用回调函数。

6. 使用前提

低层 SDK 已初始化，机器人硬件或仿真节点正在发布 /rt/hardware/state。
回调内避免长时间阻塞；跨线程共享状态时自行做同步。

7. C++ 示例

robot.subscribeHardwareState([](const leju::StringDataConstPtr& msg) {
  const auto state = leju::String2HwState(msg->data);
  std::cout << leju::HardwareState2String(state) << '\n';
});

8. 对应仓库示例

源码：src/lejusdk/examples/src/hw_state_subscriber.cpp
已编译程序：hw_state_subscriber

关节状态

1. 功能描述

subscribeRobotState() 订阅机器人关节位置、速度、加速度和力矩。

2. 所属 SDK 和头文件

SDK：lejusdk-lowlevel
头文件：<lejusdk-lowlevel/leju_sdk.h>

3. 请求或消息类型

void subscribeRobotState(const leju::RobotStateCallback& callback);
using RobotStateCallback =
    std::function<void(const leju::RobotStateConstPtr&)>;

4. 字段说明

字段	类型	单位	说明
`q`	`std::vector<double>`	rad	关节位置
`v`	`std::vector<double>`	rad/s	关节速度
`vd`	`std::vector<double>`	rad/s²	关节加速度
`tau`	`std::vector<double>`	N·m	关节力矩
`timestamp`	`double`	s	时间戳

数组顺序与 getMotorNames() 返回的关节顺序一致。isValid() 可检查四个数组的维度是否一致。

5. 返回值

订阅方法无返回值；回调参数是只读共享指针。

6. 使用前提

状态发布端正在发布 /rt/joint_state。
保存数据到回调外部时，复制所需字段或安全地保存共享指针。

7. C++ 示例

const auto names = robot.getMotorNames();
robot.subscribeRobotState([names](const leju::RobotStateConstPtr& state) {
  if (state->isValid() && !state->q.empty()) {
    std::cout << names.front() << ": " << state->q.front() << " rad\n";
  }
});

8. 对应仓库示例

源码：src/lejusdk/examples/src/joint_state_subscriber.cpp
已编译程序：joint_state_subscriber

IMU 数据

1. 功能描述

subscribeImuData() 订阅惯性测量数据，包括角速度、含重力加速度、去重力加速度和姿态四元数。

2. 所属 SDK 和头文件

SDK：lejusdk-lowlevel
头文件：<lejusdk-lowlevel/leju_sdk.h>

3. 请求或消息类型

void subscribeImuData(const leju::ImuDataCallback& callback);
using ImuDataCallback =
    std::function<void(const leju::ImuDataConstPtr&)>;

4. 字段说明

字段	类型	单位/顺序
`gyro`	`std::array<double, 3>`	rad/s，`[x, y, z]`
`acc`	`std::array<double, 3>`	m/s²，含重力
`free_acc`	`std::array<double, 3>`	m/s²，已去重力
`quat`	`std::array<double, 4>`	四元数 `[w, x, y, z]`
`timestamp`	`double`	s

5. 返回值

订阅方法无返回值；新数据到达时调用回调。

6. 使用前提

IMU 发布端正在发布 /rt/imu_state。
姿态计算时按 [w, x, y, z] 顺序解析，不要按 [x, y, z, w] 使用。

7. C++ 示例

robot.subscribeImuData([](const leju::ImuDataConstPtr& imu) {
  std::cout << "gyro_z=" << imu->gyro[2]
            << ", qw=" << imu->quat[0] << '\n';
});

8. 对应仓库示例

源码：src/lejusdk/examples/src/imu_data_subscriber.cpp
已编译程序：imu_data_subscriber

普通游戏手柄数据

1. 功能描述

subscribeJoyData() 订阅 Xbox 或 PlayStation 风格游戏手柄。该接口与后文 Quest 手柄接口不同。

2. 所属 SDK 和头文件

SDK：lejusdk-lowlevel
头文件：<lejusdk-lowlevel/leju_sdk.h>

3. 请求或消息类型

void subscribeJoyData(const leju::JoyDataCallback& callback);
using JoyDataCallback = std::function<void(const leju::JoyDataConstPtr&)>;

4. 字段说明

timestamp：时间戳，单位 s。
axes.left_x、left_y、right_x、right_y：摇杆轴，范围 [-1, 1]。
axes.left_trigger、right_trigger：扳机，范围 [0, 1]。
buttons：south、east、west、north、back、guide、start、左右摇杆键、肩键、方向键和 misc1/misc2；0 为未按下，非 0 为按下。

5. 返回值

订阅方法无返回值；回调参数为 JoyDataConstPtr。

6. 使用前提

leju-joystick 或其他驱动程序正在发布 /rt/joy。
具体按键功能由当前 teleop_bindings.yaml 决定；SDK 数据类型只表示原始输入。

7. C++ 示例

robot.subscribeJoyData([](const leju::JoyDataConstPtr& joy) {
  std::cout << "left=(" << joy->axes.left_x << ", "
            << joy->axes.left_y << ") start="
            << joy->buttons.start << '\n';
});

8. 对应仓库示例

src/leju-joystick/src/leju_joy_autostart_manager.cpp
src/leju-controllers/leju-rl-controller/src/runtime/input/teleop/joy_teleop_adapter.cpp

Quest 手柄数据

1. 功能描述

subscribeQuestJoystickData() 订阅 Quest 左右手柄的摇杆、扳机、握把、按键按下和触摸状态。publishQuestJoystickData() 用于 Quest UDP 桥接程序等数据源，普通业务应用以订阅为主。

2. 所属 SDK 和头文件

SDK：lejusdk-vr
头文件：<lejusdk-vr/lejusdk_vr.h>

3. 请求或消息类型

void subscribeQuestJoystickData(leju::vr::QuestJoystickDataCallback callback);
bool publishQuestJoystickData(const leju::vr::QuestJoystickData& data);

4. 字段说明

字段	类型	说明
`header_sec`, `header_nanosec`	`int32_t`, `uint32_t`	DDS 帧时间戳
`left_x`, `left_y`, `right_x`, `right_y`	`float`	左右手摇杆轴
`left_trigger`, `right_trigger`	`float`	左右手扳机值
`left_grip`, `right_grip`	`float`	左右手握把值
`left_first_button_pressed`, `left_second_button_pressed`	`bool`	左手主/次按键按下状态
`right_first_button_pressed`, `right_second_button_pressed`	`bool`	右手主/次按键按下状态
`_first_button_touched`, `_second_button_touched`	`bool`	对应按键触摸状态

5. 返回值

subscribeQuestJoystickData()：无返回值。
publishQuestJoystickData()：发布成功返回 true，失败返回 false。

6. 使用前提

RobanVRAPI 已成功初始化。
订阅时，Quest 桥接程序正在发布 /rt/quest/joysticks。
按键与控制功能的绑定属于遥操配置，不是 QuestJoystickData 固定语义。

7. C++ 示例

leju::vr::RobanVRAPI vr(leju::RobotVersion::from_env());
if (!vr.initialize()) return 1;

vr.subscribeQuestJoystickData(
    [](const leju::vr::QuestJoystickData& joy) {
      std::cout << "left stick: " << joy.left_x << ", "
                << joy.left_y << "  left grip: "
                << joy.left_grip << '\n';
    });

8. 对应仓库示例

数据发布：src/leju-remote/src/quest_udp_to_dds_node.cpp
数据订阅：src/leju-vr-control/src/quest_vr_abs_control_node.cpp
遥操适配：src/leju-controllers/leju-rl-controller/src/runtime/input/teleop/quest_teleop_adapter.cpp

Quest 骨骼位姿数据

1. 功能描述

subscribeQuestBonePoses() 订阅 Quest 骨骼节点的位置和四元数姿态。publishQuestBonePoses() 用于 Quest 数据桥接端发布整帧数据。

2. 所属 SDK 和头文件

SDK：lejusdk-vr
头文件：<lejusdk-vr/lejusdk_vr.h>

3. 请求或消息类型

void subscribeQuestBonePoses(leju::vr::QuestBonePosesCallback callback);
bool publishQuestBonePoses(const leju::vr::QuestBonePosesData& data);

4. 字段说明

QuestBonePosesData 字段：

字段	类型	说明
`header_sec`, `header_nanosec`	`int32_t`, `uint32_t`	DDS 帧时间戳
`timestamp_ms`	`int64_t`	Quest 原始毫秒时间戳
`is_high_confidence`	`bool`	本帧是否为高置信度
`is_hand_tracking`	`bool`	是否来自手势跟踪模式
`poses`	`std::vector<Pose>`	骨骼节点位姿数组

Pose 包含位置 x/y/z 和四元数 qx/qy/qz/qw，均为 float。具体节点下标由上游 Quest 协议和仓库转换逻辑决定，不应根据数组长度自行猜测。

5. 返回值

subscribeQuestBonePoses()：无返回值。
publishQuestBonePoses()：发布成功返回 true，失败返回 false。

6. 使用前提

RobanVRAPI 已成功初始化。
Quest 桥接程序正在发布 /rt/quest/bone_poses。
使用位姿前检查 is_high_confidence、poses 长度和实际节点定义。

7. C++ 示例

vr.subscribeQuestBonePoses(
    [](const leju::vr::QuestBonePosesData& frame) {
      if (!frame.is_high_confidence || frame.poses.empty()) return;
      const auto& pose = frame.poses.front();
      std::cout << "first pose: " << pose.x << ", "
                << pose.y << ", " << pose.z << '\n';
    });

8. 对应仓库示例

数据发布：src/leju-remote/src/quest_udp_to_dds_node.cpp
数据订阅：src/leju-vr-control/src/quest_vr_abs_control_node.cpp
位姿转换：src/leju-vr-control/src/quest_to_ik_converter.cpp

机器人信息与状态接口

通用初始化​

机器人基本信息​

1. 功能描述​

2. 所属 SDK 和头文件​

3. 请求或消息类型​

4. 字段说明​

5. 返回值​

6. 使用前提​

7. C++ 示例​

8. 对应仓库示例​

硬件状态​

1. 功能描述​

2. 所属 SDK 和头文件​

3. 请求或消息类型​

4. 字段说明​

5. 返回值​

6. 使用前提​

7. C++ 示例​

8. 对应仓库示例​

关节状态​

1. 功能描述​

2. 所属 SDK 和头文件​

3. 请求或消息类型​

4. 字段说明​

5. 返回值​

6. 使用前提​

7. C++ 示例​

8. 对应仓库示例​

IMU 数据​

1. 功能描述​

2. 所属 SDK 和头文件​

3. 请求或消息类型​

4. 字段说明​

5. 返回值​

6. 使用前提​

7. C++ 示例​

8. 对应仓库示例​

普通游戏手柄数据​

1. 功能描述​

2. 所属 SDK 和头文件​

3. 请求或消息类型​

4. 字段说明​

5. 返回值​

6. 使用前提​

7. C++ 示例​

8. 对应仓库示例​

Quest 手柄数据​

1. 功能描述​

2. 所属 SDK 和头文件​

3. 请求或消息类型​

4. 字段说明​

5. 返回值​

6. 使用前提​

7. C++ 示例​

8. 对应仓库示例​

Quest 骨骼位姿数据​

1. 功能描述​

2. 所属 SDK 和头文件​

3. 请求或消息类型​

4. 字段说明​

5. 返回值​

6. 使用前提​

7. C++ 示例​

8. 对应仓库示例​

通用初始化

机器人基本信息

1. 功能描述

2. 所属 SDK 和头文件

3. 请求或消息类型

4. 字段说明

5. 返回值

6. 使用前提

7. C++ 示例

8. 对应仓库示例

硬件状态

1. 功能描述

2. 所属 SDK 和头文件

3. 请求或消息类型

4. 字段说明

5. 返回值

6. 使用前提

7. C++ 示例

8. 对应仓库示例

关节状态

1. 功能描述

2. 所属 SDK 和头文件

3. 请求或消息类型

4. 字段说明

5. 返回值

6. 使用前提

7. C++ 示例

8. 对应仓库示例

IMU 数据

1. 功能描述

2. 所属 SDK 和头文件

3. 请求或消息类型

4. 字段说明

5. 返回值

6. 使用前提

7. C++ 示例

8. 对应仓库示例

普通游戏手柄数据

1. 功能描述

2. 所属 SDK 和头文件

3. 请求或消息类型

4. 字段说明

5. 返回值

6. 使用前提

7. C++ 示例

8. 对应仓库示例

Quest 手柄数据

1. 功能描述

2. 所属 SDK 和头文件

3. 请求或消息类型

4. 字段说明

5. 返回值

6. 使用前提

7. C++ 示例

8. 对应仓库示例

Quest 骨骼位姿数据

1. 功能描述

2. 所属 SDK 和头文件

3. 请求或消息类型

4. 字段说明

5. 返回值

6. 使用前提

7. C++ 示例

8. 对应仓库示例