机器狗 ROS2 SDK 文档
约 3904 字大约 13 分钟
2025-05-29
机器狗 ROS2 SDK 文档（完整丰富版）
机器狗 ROS2 SDK 文档（完整版）
版本：1.0 | 日期：2025-05-25
版本历史与变更日志
| 版本 | 日期 | 说明 |
|---|---|---|
| 1.0 | 2025-05-25 | 初始发布版本。 |
| 1.1 | 待定 | 补充非 ROS2 接口与多语言支持。 |
文档概述
本手册面向机器人集成商和工程师，系统性地介绍机器狗 ROS2 SDK 的功能与接口，方便用户在 Ubuntu+ROS2 平台上进行二次开发和集成。文档不仅详细列举每项功能与接口，还穿插使用建议、常见问题与操作提示，帮助初学者快速理解和上手。
友情提示：本文档默认用户具备基本的 Linux/ROS2 操作知识。如果是首次使用 ROS2，建议先参考官方文档完成环境搭建与基础操作。
- 适用对象：机器人集成商、行业开发者、科研人员。
- 主要内容包括：系统结构、通讯协议、开发环境配置、接口说明、实用案例、常见问题。
- 覆盖场景：工厂巡检、教育科研、定制应用等。
系统架构
机器狗系统由底层硬件（主控、执行器、传感器）、嵌入式软件（固件）、中间件（ROS2 + DDS）、以及上层应用共同组成。各部分通过标准化接口协作，提升了开发效率与系统扩展性。
- 主控板：运算与调度核心，运行 ROS2
- 传感器：包含 TOF、超声、IMU、鱼眼相机、激光雷达等
- 执行器：用于运动与交互（如电机、舵机、显示等）
- 上位机/外部应用：通过有线或 Wi-Fi 与主控进行交互、远程调试与监控
如无真实机器，可在仿真平台（如 Gazebo）测试 ROS2 通信。
通信协议
SDK 所有通信基于 ROS2 的分布式架构，底层采用 DDS(Data Distribution Service) 中间件，实现高效可靠的消息发布/订阅与服务调用。ROS2 设计天然支持多进程、多主机分布式部署，适合机器人集群和远程运维场景。
- Topic：适用于传感器数据、状态信息等“发布-订阅”模式的数据流转。
- Service：用于参数配置、控制指令、触发操作等一对一请求-响应事务。
- Action：适合需要过程反馈和结果通知的复杂任务（如导航、动作执行）。
- QoS：可根据实际需求灵活设置，保障消息的实时性与可靠性。
QoS 配置对调试和大数据量场景尤其重要，如有高丢包建议提升 reliability 等参数。
开发环境说明
- 操作系统推荐： Ubuntu 20.04 LTS（长期支持版）
- ROS2 版本： Foxy/Galactic/Humble 等均兼容，建议使用 Foxy 及以上。
- 基础依赖： Python3、C++ 编译环境、colcon 等构建工具。
- 网络配置： 推荐有线直连，便于多播和大数据流。
首次开发建议：
- 优先在虚拟机或 Docker 中测试，避免影响本机环境。
- 使用 conda 或 venv 隔离 Python 依赖。
开发环境配置
SDK 安装与节点配置
- 将 SDK 源码/安装包上传至主控或开发 PC。
- 进入工作空间，使用
colcon build编译。 - source 工作空间环境脚本，如
source install/setup.bash。
如遇依赖包缺失，可用rosdep install -i --from-path src --rosdistro foxy -y自动补齐。
ROS2环境变量设置
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export ROS_DOMAIN_ID=25 # 如有多机器人并网，须区分 domain_idROS2 接口列表与示例
本节对所有主要接口分门别类，并结合开发实践给出调用代码、参数说明、典型应用场景和调试建议。
如需批量测试接口，建议编写自动化脚本并善用ros2 topic echo、ros2 service call等调试命令。
5.1 传感器接口
5.1.1 TOF 输出
飞行时间(TOF)传感器阵列，实时输出前方和腹部距离，常用于避障、地图构建等。
| 话题 | 消息类型 | index/顺序 | 位置说明 |
|---|---|---|---|
/tof | std_msgs/Float32MultiArray | 0 | 左前 |
/tof | std_msgs/Float32MultiArray | 1 | 右前 |
/tof | std_msgs/Float32MultiArray | 2 | 腹部 |
建议定期监测数据是否有大幅跳变，发现异常及时排查硬件或遮挡。
5.1.2 超声波输出
覆盖侧向与正前方低速避障场景。
| 话题 | 消息类型 | index/顺序 | 位置说明 |
|---|---|---|---|
/ultra | std_msgs/Float32MultiArray | 0 | 左侧 |
/ultra | std_msgs/Float32MultiArray | 1 | 前方 |
/ultra | std_msgs/Float32MultiArray | 2 | 右侧 |
如遇所有数据为0，需检查线缆与供电，或测试是否有强回声干扰。
5.1.3 头部触摸传感器
用于人机交互，可区分多种手势事件。
| 话题 | 消息类型 | 值 | 手势类型 |
|---|---|---|---|
/head_touch_state | std_msgs/Int8 | 0 | 未触发 |
/head_touch_state | std_msgs/Int8 | 1 | 单击 |
/head_touch_state | std_msgs/Int8 | 2 | 双击 |
/head_touch_state | std_msgs/Int8 | 3 | 上划 |
/head_touch_state | std_msgs/Int8 | 4 | 下划 |
/head_touch_state | std_msgs/Int8 | 5 | 长按 |
/head_touch_state | std_msgs/Int8 | 16 | 错误 |
与 UI/APP 联动时，可用此 topic 触发交互动画或语音提示。
5.1.4 电池信息
电池状态监控，包括电压、电流、温度、SOC 等，实时保障系统安全。
| 话题 | 消息类型 | 主要字段 |
|---|---|---|
/motion/bms_data | motion_msgs/BMSResponse | batt_volt（电压）batt_curr（电流）batt_temp（温度）batt_soc（剩余电量）status（电源状态）key（关机信号）batt_health（健康度）batt_loop_number（循环次数）power_board_status（电源板故障位） |
builtin_interfaces/Time timestamp
int16 batt_volt # 单位 mV
int16 batt_curr # 单位 mA
int16 batt_temp # 单位 ℃
int8 batt_soc # 剩余电量 %
int8 status # 电源状态 位字段
int8 key # 关机信号：1 关机；0 正常
int8 batt_health # 健康度 %
int16 batt_loop_number # 循环次数
int8 power_board_status # 电源板故障位建议在高功率动作或低温环境下特别关注batt_temp和batt_soc，以避免意外掉电。
5.1.5 鱼眼相机
支持通过服务动态开启/关闭鱼眼相机，便于节能或多机互斥场景。
# 开启左鱼眼
ros2 service call /fisheye_node/left_enable common_msgs/srv/SetInt8 "data: 1"
# 关闭左鱼眼
ros2 service call /fisheye_node/left_enable common_msgs/srv/SetInt8 "data: 0"
# 开启右鱼眼
ros2 service call /fisheye_node/right_enable common_msgs/srv/SetInt8 "data: 1"
# 关闭右鱼眼
ros2 service call /fisheye_node/right_enable common_msgs/srv/SetInt8 "data: 0"部分型号如长时间采集，建议适当关闭未用通道以减少发热。
5.1.6 双目相机
服务控制图像与深度流输出。
# 仅输出图像
ros2 service call /stereocam_node/enable common_msgs/srv/SetInt8 "data: 1"
# 输出图像+深度
ros2 service call /stereocam_node/enable common_msgs/srv/SetInt8 "data: 2"
# 调整曝光
ros2 service call /stereocam_node/stereocam_exposure common_msgs/srv/SetInt8 "data: 100" # 0~1005.2 语音接口
本章节介绍如何通过 ROS2 服务方式调用语音相关能力，包括音量查询、音量设置、语音识别、TTS 控制等，方便机器人具备人机语音交互能力。
实用建议：语音相关服务建议和 APP 或后台配置工具结合批量测试。部分接口支持多种参数、需注意权限与输入范围。
5.2.1 获取音量
获取机器人当前的音量等级，便于适配不同场景音量。
ros2 service call /voice/get_volume voice_msgs/srv/GetVolume "{}"返回结果通常为volume: int，取值范围建议在0~10之间，具体取决于硬件实现。
5.2.2 设置音量
可设置机器人音箱音量，建议在噪音环境或夜间模式下灵活调用。
ros2 service call /voice/set_volume voice_msgs/srv/SetVolume "{volume: 7}"不同硬件平台最大音量值可能不同，请在上电首次调用时做边界检查。
5.2.3 获取语音识别状态
查看语音识别（ASR）是否启用及相关状态，便于自动化调试脚本与运维巡检。
ros2 service call /voice_config_get voice_msgs/srv/GetConfig "{}"5.2.4 设置语音识别
可用于远程启用或关闭语音识别功能。例如需要后台远程静音或唤醒机器人时使用。
ros2 service call /voice_config voice_msgs/srv/Config "{enable_voice: true}"5.2.5 停止 TTS
中断当前 TTS 播报，适用于任务切换或紧急打断场景。
ros2 service call /voice/stop_tts std_srvs/srv/Trigger "{}"强烈建议在控制交互型机器人时妥善管理 TTS 队列，防止消息堆积或延迟。
5.2.6 播放 TTS
向机器人发送文本内容，并立即转为语音播报。
ros2 service call /voice/set_tts voice_msgs/srv/SetTTS "{tts_id: 'id_1', content: '你好', priority: 1, mode: 0}"建议使用唯一tts_id方便后续管理与打断。
5.3 相机接口
本章节介绍各种相机（如主摄像头、鱼眼、双目等）相关的开启、关闭、参数设置、数据流接入方式等接口。
摄像头资源较占带宽，建议仅在业务需要时打开对应流。
5.3.1 相机开关接口
通过服务启动或关闭摄像头节点（如 berxel_camera）。对于多摄/多传感场景，建议业务层做好互斥与带宽规划。
开启相机：
ros2 service call /berxel_camera_ros2/enable std_srvs/srv/SetBool "data: true"关闭相机：
ros2 service call /berxel_camera_ros2/enable std_srvs/srv/SetBool "data: false"频繁启动/关闭部分硬件可能损耗寿命，建议优先做软件 mute。
5.3.2 数据流话题与格式
图像数据通常以 topic 形式实时输出，建议下游处理节点根据 topic 名订阅获取。常用 topic 如下：
| 话题名 | 消息类型 | 说明 |
|---|---|---|
/sensor_msgs | sensor_msgs::msg::Image | 主摄原始图像 |
/depth | sensor_msgs::msg::Image + /depth/camera_info | 深度图像+相机内参 |
/color | sensor_msgs::msg::Image + /color/camera_info | 彩色图像+相机内参 |
如需保存、后处理或 AI 推理，建议另起节点订阅并异步处理。
5.4 导航接口
导航相关接口涉及多种服务与 topic，包括模式切换、目标点设置、速度指令、状态反馈等。适合多场景灵活调度和二次开发。
建议配合 RViz 或自研 Web 工具可视化调试导航效果。
5.4.1 切换导航模式
可根据业务需求切换“无地图”、“自主探索”、“有地图”等多种导航模式。
ros2 service call /switch_navigate_mode pp_msgs/srv/ChangeNavigateMode "{set_mode: 0}" # 关
ros2 service call /switch_navigate_mode pp_msgs/srv/ChangeNavigateMode "{set_mode: 1}" # 无地图
ros2 service call /switch_navigate_mode pp_msgs/srv/ChangeNavigateMode "{set_mode: 6}" # 自主探索
ros2 service call /switch_navigate_mode pp_msgs/srv/ChangeNavigateMode "{set_mode: 12}" # 有地图不同模式对应不同地图/路径算法，请参考下位机/算法团队具体定义。
5.4.2 深度点云转换
用于开启或关闭点云转换（如摄像头深度点云转激光等）。
ros2 service call /cloud_processor/switch_statue std_srvs/srv/SetBool "data: true" # 开启
ros2 service call /cloud_processor/switch_statue std_srvs/srv/SetBool "data: false" # 关闭5.4.3 速度输入
下发机器人期望速度，常用于高级自主控制、远程遥控。
ros2 topic pub -r 10 /vel_app motion_msgs/msg/VelCommand "{mode_stamped:{timestamp:{sec:0,nanosec:0},mode:2},x_vel_des:0.0,y_vel_des:0.0,yaw_vel_des:0.0}"建议调试阶段小步增减速度，确保安全。
5.4.4 全局目标点
设置机器人导航到某一全局点。
ros2 topic pub -1 /goal_pose geometry_msgs/msg/PoseStamped "{header:{stamp:{sec:0,nanosec:0},frame_id:'map'},pose:{position:{x:-4.3,y:2.5,z:0.8},orientation:{x:0.0,y:0.0,z:-0.9977,w:0.0669}}}"5.4.5 局部目标点
ros2 service call /intelligence_goal_pose pp_msgs/srv/IntelligencePose "{...}"5.4.6 任务状态与速度输出
任务执行结束、导航速度等均可通过 topic 订阅获得。
ros2 topic echo /ab_navigation_complete std_msgs/msg/Bool
ros2 topic echo /vel_nav motion_msgs/msg/VelCommand5.5 激光雷达接口
本节介绍如何通过 ROS2 节点启动/关闭激光雷达扫描、执行建图与定位。
不同厂牌雷达配置方式略有不同，下述接口以主流方案为例。
5.5.1 启动/关闭雷达节点
启动/关闭激光雷达话题。
ros2 service call /lds/enable std_srvs/srv/SetBool "data: true" # 开启
ros2 service call /lds/enable std_srvs/srv/SetBool "data: false" # 关闭5.5.2 激光建图/保存/定位
执行 SLAM 建图、保存当前地图、载入地图定位。具体命令如下：
# 启动建图
ros2 service call /set_slam_model cartographer_ros_msgs/srv/SetSlamModel "{slam_model:1,path:'/home/eame/cust_para/maps/123'}"
# 保存地图
ros2 service call /save_map cartographer_ros_msgs/srv/SaveMap "{path:'/home/eame/maps/test'}"
# 切换为定位模式
ros2 service call /set_slam_model cartographer_ros_msgs/srv/SetSlamModel "{slam_model:3,path:'/home/eame/cust_para/maps/test'}"
# 停止 SLAM
ros2 service call /set_slam_model cartographer_ros_msgs/srv/SetSlamModel "{slam_model:0,path:'/home/eame/cust_para/maps/123'}"SLAM 与定位均需保证 /scan、/odom、TF 关系正确。
常见问题与故障排查
- 接口无响应：请检查 topic/service 名称、参数格式，以及相关依赖节点是否已正常启动。
- 数据异常：可使用
ros2 topic echo调试原始输出，关注是否有异常值（如 nan、inf）。 - 网络丢包：建议优先采用有线连接，或调整 QoS 策略以提升可靠性。
- 权限/认证失败：请确认当前账户具备访问硬件和串口的足够权限。
如遇严重问题建议保存全部日志，并联系厂家技术支持。
© 2025 MagicLab Robotics