在机器人自主移动技术中，SLAM（同步定位与地图构建）是核心支撑能力，而清晰、规范的接口设计则是开发者高效调用该能力的关键。Unitree针对G1机器人推出的SLAM导航服务接口，基于Unitree SDK2构建，为教育科研场景提供了完整的建图、定位、导航解决方案。本文将从接口基础、环境配置、核心功能、数据解析、实战测试等维度，全方位拆解该接口的技术细节与使用要点，助力开发者快速上手。

一、接口概述：核心定位与适用场景

1. 接口基础架构

Unitree G1的SLAM导航服务接口以SDK2为底层支撑，通过API调用与话题订阅的组合方式，实现SLAM相关功能的灵活控制。其核心设计逻辑是：通过指定API-ID发起特定操作（如建图、导航），通过订阅话题获取实时数据（如点云、位姿、设备状态），二者协同完成完整的SLAM导航工作流。

接口的坐标系定义是开发的基础前提：

• 原点：Mid360-IMU坐标系原点
• 坐标轴方向：X轴正方向为机器人正前方，Z轴正方向为竖直向上
• 原始数据话题：雷达点云数据话题为rt/utlidar/cloud_livox_mid360，IMU数据话题为rt/utlidar/imu_livox_mid360

2. 适用范围与核心限制

该接口专为教育科研场景设计，不建议用于行业应用（行业场景需联系Unitree销售获取定制方案），其适用环境与使用限制需重点关注：

• 适用场景：X轴/Y轴范围小于45m、特征丰富的静态室内平地（超出该范围会导致计算资源占用过高，影响基础运控服务）
• 使用禁忌：避免机器人剧烈运动（可能导致定位丢失）；禁止同时使用APP导航功能与接口调用
• 硬件要求：雷达需竖直向上固定无松动，静止状态下照射同一竖平面时无明显点云分层，IMU线速度与加速度值无异常（出现异常需联系售后维修）

二、环境准备：网络配置与前置检查

1. 核心网络参数配置

SLAM导航服务的正常运行依赖机器人与开发设备的局域网通信，核心IP地址与配置步骤如下：

• 关键IP清单：
  • NX开发板默认IP：192.168.123.164
  • 雷达默认IP：192.168.123.120
  • 运控PC默认IP：192.168.123.161
• 配置步骤：
  1. 用网线将用户PC直连G1内部交换机，将PC IPv4地址手动修改为192.168.123.XXX（XXX需避免与已有IP冲突，子网掩码255.255.255.0）
  2. 打开终端执行通信测试指令：

     # 登录NX开发板（初始密码：123）
     ssh unitree@192.168.123.164
     # 测试雷达通信
     ping 192.168.123.120
     # 测试运控PC通信
     ping 192.168.123.161
     

  3. 确认所有ping指令均能正常响应，无丢包现象。

2. 前置检查项

• 服务状态：通过G1配套APP确认unitree_slam与lidar_driver服务已开启
• 硬件状态：检查雷达安装牢固性，验证原始点云与IMU数据无异常
• 环境清理：确保操作环境为静态室内场景，无遮挡雷达视角的障碍物

三、核心功能：API接口详解

SLAM导航服务当前开放7个核心API接口，所有接口的请求参数与反馈数据均采用JSON格式，服务名称为slam_operate，版本号1.0.0.1。以下是各接口的详细说明：

1. 建图相关接口

（1）开始建图（API-ID：1801）

• 功能：启动室内SLAM建图流程
• 输入参数（固定格式）：

  {
    "data": {
      "slam_type": "indoor"  // 仅支持室内场景，不可修改
    }
  }
  

• 反馈响应：

  {
    "succeed": true,  // 执行结果：true为成功
    "errorCode": 0,   // 错误码：0为正常，非0需排查异常
    "info": "",       // 状态描述信息
    "data": {}        // 无额外返回数据
  }
  

（2）结束建图（API-ID：1802）

• 功能：停止建图并保存点云地图（PCD格式）
• 输入参数：

  {
    "data": {
      "address": "/home/unitree/test.pcd"  // 地图保存路径
    }
  }
  

• 关键注意事项：
  • 为避免磁盘空间占用过多，建议采用test1.pcd~test10.pcd的命名规则，实现覆盖式保存
  • 保存路径需确保NX开发板有写入权限，默认路径/home/unitree/可直接使用

2. 定位相关接口

（1）初始化位姿（API-ID：1804）

• 功能：加载已保存的PCD地图，并初始化机器人初始位姿
• 输入参数：

  {
    "data": {
      "x": 0.0,    // 初始平移X坐标
      "y": 0.0,    // 初始平移Y坐标
      "z": 0.0,    // 初始平移Z坐标
      "q_x": 0.0,  // 初始旋转四元数X分量
      "q_y": 0.0,  // 初始旋转四元数Y分量
      "q_z": 0.0,  // 初始旋转四元数Z分量
      "q_w": 1.0,  // 初始旋转四元数W分量
      "address": "/home/unitree/test.pcd"  // 已保存的地图路径
    }
  }
  

• 应用场景：建图完成后，再次启动定位功能时需先执行该接口，完成地图加载与位姿初始化

3. 导航相关接口

（1）位姿导航（API-ID：1102）

• 功能：根据目标位姿执行自主导航
• 输入参数：

  {
    "data": {
      "targetPose": {  // 目标位姿信息
        "x": 2.0,      // 目标X坐标
        "y": 0.0,      // 目标Y坐标
        "z": 0.0,      // 目标Z坐标
        "q_x": 0.0,    // 目标旋转四元数X分量
        "q_y": 0.0,    // 目标旋转四元数Y分量
        "q_z": 0.0,    // 目标旋转四元数Z分量
        "q_w": 1.0     // 目标旋转四元数W分量
      },
      "mode": 1        // 导航模式固定值，不可修改
    }
  }
  

• 关键限制：
  • 目标点与当前机器人位置的距离不可超过10m
  • 障碍物高度需不低于50cm（受雷达视角限制，过低障碍物可能无法识别）
  • 导航路径为直线，需确保路径上无动态障碍物

（2）暂停导航（API-ID：1201）

• 功能：暂停当前正在执行的导航任务
• 输入参数：无额外参数，空JSON即可

  { "data": {} }
  

（3）恢复导航（API-ID：1202）

• 功能：恢复被暂停的导航任务，从暂停点继续向目标位姿移动
• 输入参数：同暂停导航，无额外参数

4. 系统控制接口

（1）关闭SLAM（API-ID：1901）

• 功能：停止SLAM服务，释放相关计算资源
• 输入参数：无额外参数
• 适用场景：建图、导航任务完成后，或需要切换工作模式时调用

四、数据交互：话题数据解析

除API接口外，SLAM导航服务通过多个ROS话题实时发布数据，开发者可通过订阅这些话题获取建图、定位、设备状态等信息。所有话题数据类型均基于DDS协议，确保传输稳定性。

1. 核心话题清单

话题名称	数据类型	功能描述
rt/unitree/slam_mapping/points	sensor_msgs::msg::dds_::PointCloud2_	建图过程实时点云数据
rt/unitree/slam_mapping/odom	nav_msgs::msg::dds_::Odometry_	建图过程实时里程计数据
rt/unitree/slam_relocation/points	sensor_msgs::msg::dds_::PointCloud2_	定位过程实时点云数据
rt/unitree/slam_relocation/odom	nav_msgs::msg::dds_::Odometry_	定位过程实时里程计数据
rt/slam_info	std_msgs::msg::dds_::String_	实时广播信息（设备状态、定位信息等）
rt/slam_key_info	std_msgs::msg::dds_::String_	任务执行结果反馈
rt/unitree/slam_relocation/global_map	sensor_msgs::msg::dds_::PointCloud2_	全局地图点云（定位启动后发送一次）

2. 关键话题数据格式解析

（1）实时广播信息（rt/slam_info）

该话题包含三类核心数据，通过type字段区分：

• 设备状态数据（type: “robot_data”）：包含电机温度、电池状态、CPU负载等硬件信息

  {
    "type": "robot_data",
    "errorCode": 0,
    "sec": 123456789,    // 秒级时间戳
    "nanosec": 987654321, // 纳秒级时间戳
    "info": "",
    "data": {
      "motorTemp": [30.5, 30.5],  // 各电机温度（°C）
      "batteryPower": 10.0,       // 电池剩余电量（%）
      "cpuUsage": 30.5,           // CPU占用率（%）
      // 其他硬件状态字段...
    }
  }
  

• 定位信息（type: “pos_info”）：当前位姿与使用的地图信息
• 控制信息（type: “ctrl_info”）：导航状态机、目标位姿、障碍物检测结果等

（2）任务执行反馈（rt/slam_key_info）

• 功能：反馈单次API任务的执行结果（如导航是否到达目标点）
• 数据格式：

  {
    "type": "task_result",
    "errorCode": 0,
    "sec": 123456789,
    "nanosec": 987654321,
    "info": "",
    "data": {
      "targetNodeName": 9999,  // 任务目标点标识
      "is_arrived": false      // 任务完成状态：true为到达目标点
    }
  }
  

五、实战测试：按键例程Demo使用指南

为方便开发者快速验证功能，Unitree提供了按键控制例程，支持通过键盘快捷操作测试所有核心功能。

1. 前置准备

• 安装Unitree SDK2：下载地址（文档提供：unitree_sdk2）
• 下载例程源码：下载地址（文档提供：unitree_slam_example）
• 环境要求：NX开发板或支持ROS的PC（需与G1处于同一局域网）

2. 编译与运行步骤

# 进入例程目录
cd /yourFileAddress/unitree_slam_example
# 创建编译目录
mkdir build && cd build
# 编译工程
cmake .. && make
# 运行Demo（指定网卡名称，如eth0）
./keyDemo eth0

3. 按键功能映射

• q：启动建图（对应API 1801）
• w：结束建图（对应API 1802）
• a：启动定位（需先执行初始化位姿）
• s：添加目标位姿到任务列表
• d：执行任务列表（对应API 1102）
• f：清空任务列表
• z：暂停导航（对应API 1201）
• x：恢复导航（对应API 1202）
• Ctrl+C：退出Demo程序

六、注意事项与常见问题排查

1. 关键注意事项

• 行业应用限制：该接口仅面向教育科研，商业场景需联系销售获取授权
• 数据存储管理：PCD地图文件建议定期清理，避免占用过多存储空间
• 环境适配：仅支持静态室内平地，动态环境或室外场景会导致定位失效
• 硬件维护：雷达为核心传感器，避免碰撞或松动，出现数据异常及时联系售后

2. 常见问题排查

• 网络通信失败：检查IP配置是否正确，确保无IP冲突，网线连接正常
• 建图失败（errorCode非0）：确认lidar_driver服务已开启，雷达无遮挡
• 导航无法启动：检查是否已执行初始化位姿接口，目标点距离是否超过10m
• 定位丢失：排查是否存在剧烈运动，环境特征是否不足，或超出45m范围限制

总结

Unitree G1的SLAM导航服务接口基于SDK2构建，提供了从建图、定位到导航的完整解决方案，接口设计简洁规范，适配教育科研场景的开发需求。通过本文的详细解析，开发者可快速掌握网络配置、API调用、话题订阅、Demo测试等核心操作，顺利实现机器人自主移动功能开发。