跳到主要内容

机器人移动与控制器接口

本页记录 Roban2 的移动速度、姿态高度、停止、控制器管理和 runtime 生命周期接口。当前 SDK 没有对外提供“步态名称”或“步态切换”的独立公开 API，本文不沿用旧 SDK 的相关说明。

VR 输入速度​

1. 功能描述​

publishVrVelocityCmd() 向控制链路发布 VR 遥操速度输入；subscribeVrVelocityCmd() 订阅同一输入数据流。这是 Quest/VR 遥操场景的常用速度接口。

2. 所属 SDK 和头文件​

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

3. 请求或消息类型​

bool publishVrVelocityCmd(const leju::vr::VrVelocityCmd& cmd);
void subscribeVrVelocityCmd(leju::vr::VrVelocityCmdCallback callback);

4. 字段说明​

字段单位方向定义
linear_xm/s正值向前
linear_ym/s正值向左
angular_zrad/s正值绕 Z 轴逆时针
timestamps时间戳

5. 返回值​

  • publishVrVelocityCmd()：发布成功返回 true，失败返回 false。
  • subscribeVrVelocityCmd()：无返回值。

6. 使用前提​

  • RobanVRAPI 已初始化，runtime 和当前控制器已进入可接收速度输入的状态。
  • 发布频率和速度范围应符合当前控制器配置；公开数据类型没有定义统一限幅值，文档不额外假设。
  • 停止移动时发布全零速度，不以“停止发布”代替零速度指令。

7. C++ 示例​

leju::vr::VrVelocityCmd cmd;
cmd.linear_x = 0.10;
cmd.linear_y = 0.0;
cmd.angular_z = 0.0;
if (!vr.publishVrVelocityCmd(cmd)) return 1;

// 停止移动
cmd = {};
vr.publishVrVelocityCmd(cmd);

8. 对应仓库示例​

  • SDK 示例：src/lejusdk/examples/src/lejusdk-vr/03_velocity_cmd.cpp
  • VR 遥操使用：src/leju-vr-control/src/quest_vr_abs_control_node.cpp

SDK 示例使用 KuavoVRAPI 演示通用流程；Roban2 中替换为 RobanVRAPI。

控制器最终速度​

1. 功能描述​

publishVelocityCmd() 发布控制器最终速度指令，subscribeVelocityCmd() 订阅该数据流。它与 VrVelocityCmd 的数值字段相同，但属于不同 DDS 话题和输入阶段。

2. 所属 SDK 和头文件​

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

3. 请求或消息类型​

bool publishVelocityCmd(const leju::vr::VelocityCmd& cmd);
void subscribeVelocityCmd(leju::vr::VelocityCmdCallback callback);

4. 字段说明​

VelocityCmd 包含 linear_x、linear_y、angular_z、timestamp，单位和坐标方向与 VrVelocityCmd 相同。对应 DDS 话题是 /rt/cmd_vel；VR 输入对应 /rt/vr/cmd_vel。

5. 返回值​

发布方法返回 bool；订阅方法无返回值。

6. 使用前提​

  • 只有在业务明确需要向 /rt/cmd_vel 发布最终速度时使用此接口。
  • VR 遥操二次开发使用 publishVrVelocityCmd()，不将两种速度流同时作为控制输入。

7. C++ 示例​

leju::vr::VelocityCmd cmd;
cmd.linear_x = 0.0;
cmd.linear_y = 0.0;
cmd.angular_z = 0.0;
const bool sent = vr.publishVelocityCmd(cmd);

8. 对应仓库示例​

当前 src/lejusdk/examples/ 没有独立的 publishVelocityCmd() 用户示例。公开接口以 installed/include/lejusdk-vr/vr_api/vr_base.h 和 installed/include/lejusdk-vr/data_types.h 为准。

姿态高度控制​

1. 功能描述​

publishPostureHeightCmd() 向 ExternalInterface 的 posture controller 发布站立高度目标，用于身体高度调整。

2. 所属 SDK 和头文件​

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

3. 请求或消息类型​

bool publishPostureHeightCmd(double height_m);

4. 字段说明​

height_m 为目标站立高度，单位 m。公开头文件中的说明例子为 0.77 全站立、0.56 深蹲；实际可用范围必须以当前 Roban2 配置为准。

5. 返回值​

发布成功返回 true，失败返回 false。

6. 使用前提​

  • runtime 和当前控制器正在运行，posture controller 能处理该输入。
  • 使用当前机型配置许可的高度范围，逐步改变目标。

7. C++ 示例​

// 数值仅演示公开接口的单位，使用前核对当前机型限制。
const bool sent = robot.publishPostureHeightCmd(0.77);

8. 对应仓库示例​

  • src/leju-vr-control/src/quest_vr_abs_control_node.cpp
  • 公开声明：installed/include/lejusdk-lowlevel/robot_api/robot_base.h

停止机器人​

1. 功能描述​

publishStopRobot() 发布底层停止指令。该操作与移动速度置零不是同一语义：前者用于停止机器人程序/硬件链路，后者用于保持控制程序运行但停止行走。

2. 所属 SDK 和头文件​

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

3. 请求或消息类型​

bool publishStopRobot();

4. 字段说明​

无请求字段。SDK 在内部向 /rt/hardware/stop 发布停止消息。

5. 返回值​

发布成功返回 true，失败返回 false。

6. 使用前提​

  • 调用者已确认需要停止整个机器人控制链路，而不只是停止移动。
  • 程序不应把该 DDS 指令当作物理急停的唯一替代品。

7. C++ 示例​

if (!robot.publishStopRobot()) {
  std::cerr << "停止指令发布失败\n";
}

8. 对应仓库示例​

  • src/leju-controllers/leju-keyboard-controller/motor_keyboard_ctrl.cpp
  • src/leju-vr-control/src/quest_vr_abs_control_node.cpp

控制器状态查询​

1. 功能描述​

getControllerState() 同步查询当前控制器、各部位模式、切换过渡状态和服务端实际提供的控制器列表。

2. 所属 SDK 和头文件​

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

3. 请求或消息类型​

bool getControllerState(leju::vr::ControllerState& state,
                        int timeout_ms = 3000);

4. 字段说明​

字段类型说明
current_controllerstd::string当前控制器名称
arm_mode, head_mode, waist_modeControlMode各部位控制模式
controller_transitioningbool是否正在切换过渡
available_controllersstd::vector<std::string>当前服务端可用控制器名称

5. 返回值​

查询成功返回 true 并填充 state；超时或服务失败返回 false。

6. 使用前提​

  • RobanVRAPI 已初始化，控制器状态 DDS-RPC 服务已启动。
  • 应以 available_controllers 返回值为准，不在应用中猜测或硬编码控制器名称。

7. C++ 示例​

leju::vr::ControllerState state;
if (!vr.getControllerState(state)) return 1;
std::cout << "current: " << state.current_controller << '\n';
for (const auto& name : state.available_controllers) {
  std::cout << "available: " << name << '\n';
}

8. 对应仓库示例​

  • src/lejusdk/examples/src/lejusdk-vr/04_get_state.cpp
  • src/lejusdk/examples/src/lejusdk-vr/08_controller_cli.cpp

两个示例均是通用 VR API 流程，Roban2 使用时替换为 RobanVRAPI。

切换控制器​

1. 功能描述​

switchController() 请求控制器管理器切换到指定控制器。

2. 所属 SDK 和头文件​

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

3. 请求或消息类型​

bool switchController(const std::string& controller_name,
                      std::string* message = nullptr,
                      int timeout_ms = 3000);

4. 字段说明​

  • controller_name：目标控制器名称，应来自 getControllerState().available_controllers。
  • message：可选输出参数，接收成功信息或失败原因。
  • timeout_ms：RPC 超时，默认 3000 ms。

5. 返回值​

切换请求成功返回 true，失败或超时返回 false。

6. 使用前提​

  • 目标名称在当前 available_controllers 中。
  • 机器人位于允许切换的安全状态，controller_transitioning 为 false。
  • 切换后重新查询状态，不只依赖单次 RPC 返回值判断后续能力。

7. C++ 示例​

leju::vr::ControllerState state;
if (!vr.getControllerState(state) || state.available_controllers.empty()) return 1;

std::string message;
if (!vr.switchController(state.available_controllers.front(), &message)) {
  std::cerr << message << '\n';
  return 2;
}

8. 对应仓库示例​

  • src/lejusdk/examples/src/lejusdk-vr/08_controller_cli.cpp
  • src/leju-controllers/leju-rl-controller/tools/controller_switch_cli.cpp

Runtime 状态与启停​

1. 功能描述​

getRuntimeState() 查询数据、硬件和生命周期原始状态；startRuntime() 和 stopRuntime() 请求启动或停止 runtime。

2. 所属 SDK 和头文件​

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

3. 请求或消息类型​

bool getRuntimeState(leju::vr::RuntimeState& state,
                     int timeout_ms = 3000);
bool startRuntime(std::string* message = nullptr, int timeout_ms = 3000);
bool stopRuntime(std::string* message = nullptr, int timeout_ms = 3000);

4. 字段说明​

RuntimeState 字段：

字段类型说明
data_readybool输入数据流是否就绪
hardware_stateleju::vr::HardwareStatekUnknown、kInitializing、kReadyOk、kError、kStopped
lifecycle_stateleju::vr::LifecycleStatekWaitingForReady、kWaitingForStart、kRunning、kExiting

message 接收启停服务返回的文本说明，timeout_ms 默认 3000 ms。

5. 返回值​

三个方法成功返回 true，服务不可用、超时或请求被拒绝返回 false。

6. 使用前提​

  • runtime DDS-RPC 服务已由控制程序注册。
  • 只在 data_ready=true、hardware_state=kReadyOk 且 lifecycle_state=kWaitingForStart 时请求启动。
  • stopRuntime() 会改变整个控制 runtime 状态，不用于普通零速停步。

7. C++ 示例​

leju::vr::RuntimeState state;
if (!vr.getRuntimeState(state)) return 1;

if (state.data_ready &&
    state.hardware_state == leju::vr::HardwareState::kReadyOk &&
    state.lifecycle_state == leju::vr::LifecycleState::kWaitingForStart) {
  std::string message;
  if (!vr.startRuntime(&message)) std::cerr << message << '\n';
}

8. 对应仓库示例​

  • src/leju-joystick/src/leju_joy_autostart_manager.cpp
  • 公开接口：installed/include/lejusdk-vr/vr_api/vr_base.h

当前 SDK 示例目录未提供独立的 runtime 用户程序，上述自启动管理器是仓库内的实际调用位置。

配置热重载通知​

1. 功能描述​

订阅遥控器绑定配置和控制器列表配置的热重载通知，或向运行中的控制器发布遥控器绑定配置重载通知。

2. 所属 SDK 和头文件​

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

3. 请求或消息类型​

void subscribeReloadTeleopConfig(const leju::StringDataCallback& callback);
void subscribeReloadControllerConfig(const leju::StringDataCallback& callback);
bool publishReloadTeleopConfig(const std::string& config_path = "");

4. 字段说明​

StringData 包含 timestamp 和 data。data 可携带配置文件路径；为空时，订阅端重新读取已加载的路径。publishReloadTeleopConfig() 只发布 teleop 绑定配置重载；当前公开用户端 API 没有对应的 publishReloadControllerConfig()。

5. 返回值​

  • 两个订阅方法无返回值。
  • publishReloadTeleopConfig() 发布成功返回 true，失败返回 false。

6. 使用前提​

  • 低层 SDK 已初始化，相关配置消费端正在运行。
  • 传入路径时，该路径必须是消费端所在设备可访问的路径；网页文档不固定某台开发机的绝对路径。
  • 发布前已完成 YAML 内容校验，避免运行中加载无效配置。

7. C++ 示例​

robot.subscribeReloadTeleopConfig(
    [](const leju::StringDataConstPtr& msg) {
      std::cout << "reload teleop: " << msg->data << '\n';
    });

// 空字符串表示请求重读当前已加载的路径。
if (!robot.publishReloadTeleopConfig()) return 1;

8. 对应仓库示例​

  • 实际订阅端：src/leju-controllers/leju-rl-controller/src/main.cpp
  • 重载冒烟测试：src/leju-controllers/leju-rl-controller/tests/tools/reload_smoketest.cpp