LIMO · Product manual

产品用户使用和开发手册

本在线版按正文顺序保留章节、表格、代码块、提示框和图注。桌面端可使用左侧目录定位;移动端可展开页面顶部目录。

版本 1.1.32026.11Jetson Orin NanoROS 2 Humble
展开手册目录
Chapter 01

第1章 产品简介与快速上手

LIMO 是一款面向机器人教育、功能研发和产品验证的四模态移动机器人平台。本版把计算单元升级为 Jetson Orin Nano,并在 Ubuntu 22.04 上使用 ROS 2 Humble。四种底盘模态仍然通过机械切换与 APP/遥控模式配合完成。

计算平台 Jetson Orin Nano 6 核 Arm Cortex-A78AE / 1024 CUDA 核心开发环境 ROS 2 Humble Ubuntu 22.04 / 分布式通信
激光雷达 T-mini Pro 360 度二维扫描 / 0.02-12 m深度相机 ORBBEC Dabai RGB-D / USB 连接

1.1 产品定位

LIMO 使用四个轮毂电机和可快速转换的轮系结构,在单一车体上实现四轮差速、履带、阿克曼与麦克纳姆四种运动模态。Jetson Orin Nano 负责底盘通信、雷达与相机数据处理,ROS 2 Humble 提供节点、话题、服务、动作与参数机制,便于从基础遥控逐步进入 SLAM、Nav2 导航和视觉识别开发。

典型任务涉及能力建议章节
开箱检查与首次移动电池、电量表、模式灯、APP_Agilex1.7-1.11
底盘程序开发驱动节点、话题、消息、Twist 速度控制第 3-4 章
激光建图与导航T-mini Pro、GMapping、Cartographer、Nav2第 5-6 章
视觉建图与识别Dabai、RTAB-Map、视觉节点第 7-8 章
远程实验与调试WiFi、RDP共享桌面、SSH与RViz2第 9 章

1.2 随车物品与配置识别

标准配置包括 LIMO 高配版主体、电池、充电器和 APP_Agilex。开箱后先核对数量、接口和外观,再核对工控机与软件版本。不同批次的外壳、模块位置或可选附件可能存在差异,应以随车清单和实车丝印为准。

图 1-1 LIMO 高配版主体轮廓与越野轮配置示意
图 1-1 LIMO 高配版主体轮廓与越野轮配置示意
名称数量检查要点
LIMO 高配版主体(安装越野轮 x4)x1轮胎、插销、雷达、相机与前显示器无松动
电池x1输出与充电接口无破损,电量不低于提示阈值
充电器x1铭牌、插头与线缆完好,规格与电池匹配
APP_Agilexx1使用随车或官方渠道提供的版本完成蓝牙连接
确认本机的选配模块 不同配置的车安装的选配模块不同。执行第 8.5、10、11 章的命令前,先用下面几条确认本机有没有对应硬件;也可以直接看车身:机械臂在车头左侧,升降杆在车顶,麦克风与声卡在车体后部。没有对应硬件时,相关章节只做原理阅读,不要执行真实硬件启动命令。
ls /dev/ttyACM*                                   # 机械臂(USB 串口设备)
lsusb | grep -iE 'qinheng|ch34'                    # 机械臂的 USB 转串口芯片
arecord -l                                        # 语音:是否有 USB 声卡/麦克风
ros2 pkg list | grep -E 'detect_ros|mycobot'       # 对应软件包是否已安装
ls ~/limo_voice_test ~/limo_voice_env              # 语音:SenseVoice 脚本、模型与虚拟环境

1.3 核心性能参数

机械与运动

项目指标项目指标
外形尺寸322 x 220 x 251 mm轴距200 mm
轮距175 mm自重4.8 kg
负载4 kg最小离地间隙24 mm
驱动方式轮毂电机 4 x 14.4 W空载最高车速1 m/s
阿克曼最小转弯半径0.4 m最大爬坡角度20 度

计算、电气与传感器

项目配置项目配置
工控机Jetson Orin Nano操作系统Ubuntu 22.04
ROS 版本ROS 2 HumbleCPU6 核 Arm Cortex-A78AE
GPU1024 CUDA 核心IMUHI226
电池10 Ah / 12 V 系统工作时间约 2.5 h
待机时间约 4 h通讯WiFi、蓝牙
激光雷达EAI T-mini Pro深度相机ORBBEC Dabai
显示器前 1.54 英寸 OLED后屏7 英寸 1024 x 600 触控屏

电池标签上可能同时出现 12 V 系统电压与 11.1 V 标称电压。前者用于标识整车供电等级,后者是电池包的额定化学体系电压;充电截止电压为 12.6 V。不要混用不同电压或未经认证的电源。

1.4 计算平台与 Jetson Orin Nano

本机的核心计算单元为 NVIDIA Jetson Orin Nano,系统为 Ubuntu 22.04,机器人中间件为 ROS 2 Humble。底盘、雷达、相机与视觉功能采用统一的机器人任务逻辑,节点启动、话题检查与开发工作空间均使用 ROS 2 工具链。

项目本配置信息开发影响
计算平台NVIDIA Jetson Orin NanoARM64 Linux,支持 CUDA 与 TensorRT 加速
CPU6 核 Arm Cortex-A78AE适合同时运行 Nav2、相机和轻量视觉模型
GPU1024 CUDA 核心可用于 YOLO、RGB-D 点云与视觉加速
操作系统Ubuntu 22.04与 ROS 2 Humble 的官方目标平台匹配
中间件ROS 2 Humble节点、话题与参数由 ros2 命令和 DDS 统一管理
内存与存储以整机配置标签为准运行大模型或保存地图前检查剩余空间

MyCobot 280 M5 机械臂(选配)

项目指标项目指标
自由度6有效负载250 g
工作半径280 mm重复定位精度约 0.5 mm
自重约 800 g电源输入12 V / 5 A
工作温度-5 至 45 摄氏度通信接口USB Type-C

机械臂属于选配模块。若本机未安装机械臂,可保留对应章节作为扩展开发说明;若已安装,执行前必须确认 USB 设备号、机械臂电源、限位与工作空间,禁止在未确认姿态时快速拖动真实机械臂。

1.5 部件名称与外部接口

下图和清单用于快速定位调试接口、传感器、显示与控制部件。不同批次可能在模块位置、接口布置或选配项上存在差异,应以实车丝印和随车清单为准。

部件作用使用提示
WiFi/蓝牙天线无线网络和 APP_Agilex 通信不要用金属件遮挡或压折天线
前显示器与后屏幕显示状态、触摸交互后屏通常通过 USB 接口连接
深度相机RGB-D 图像与视觉识别保持镜头清洁,避免强逆光
T-mini Pro 雷达二维激光扫描与 SLAM避免碰撞和异物卡住旋转部件
轮毂电机与 RGB 车灯运动驱动和模式指示车灯颜色必须与当前模式一致
模式切换插销四轮差速与阿克曼机械切换切换后确认锁定到位
电池门与电源开关电池安装、开关机和程序暂停首次通电前确认电池接口牢固
海鸥门与 USB HUB键盘、鼠标及调试设备接入注意 HUB 总电流和多设备数量
扬声器与语音模块语音交互(选配)若未安装,语音章节仅作为扩展说明
升降杆控制接口视觉触发升降杆(选配)仅在车辆和升降杆完成联调后执行

1.6 功能亮点与车灯状态

LIMO 通过四个轮毂电机、快速切换轮系和集成传感器,在同一平台上覆盖教育演示、运动学实验、SLAM与 Nav2 开发、视觉识别和可选机械臂研究。

•四模态快速切换:四轮差速、履带、阿克曼和麦克纳姆轮。•计算平台升级:Jetson Orin Nano 配合 ROS 2 Humble,适合更现代的节点与导航开发。•传感器集成:T-mini Pro 雷达、Dabai 深度相机、IMU、显示器和无线通信。•开放调试:侧门内提供 USB HUB,支持键盘、鼠标、相机和调试设备接入。•扩展开发:底盘接口可连接视觉、语音、升降杆与 MyCobot 机械臂等选配模块。

车灯状态含义处理建议
绿色常亮阿克曼模式确认插销拔起,软件和 launch 使用阿克曼入口
黄色常亮四轮差速或履带模式两种模态共用差速控制模型
蓝色常亮麦克纳姆轮模式确认四个麦克纳姆轮辊子朝向正确
红色常亮程序暂停按开关键恢复或检查节点状态
红色闪烁低电量或主控报警停止实验,检查电池和错误状态

1.7 外观、开关与电量指示

首次通电前,将车辆放在平整、无坡度的地面,收起外接线缆,确认轮胎和插销到位。车体后部开关用于开机与程序暂停,电量表用于快速判断是否具备正常实验条件。

图 1-2 电量表与电源开关位置示意
图 1-2 电量表与电源开关位置示意

1.检查电池接口、轮胎、插销和周围空间,确保车辆不会碰撞人员或障碍物。

2.长按开关键开机;短按用于暂停程序。观察电量表,末位红灯亮起时及时充电或更换电池。

3.观察前方插销和 RGB 车灯,确认底盘机械模态与 APP/遥控器所选模式一致。

4.首次测试使用低速,先验证前进、后退、左转、右转和停车,再进入建图或导航。

车灯状态含义处理建议
绿色常亮阿克曼模式确认插销已拔起,APP 或导航使用阿克曼入口
黄色常亮四轮差速或履带模式两种模态共用差速控制模型,按实际轮系操作
蓝色常亮麦克纳姆轮模式确认四个麦克纳姆轮的辊子朝向正确
红色常亮程序暂停按开关键恢复或检查程序状态
红色闪烁低电量或主控报警停止实验,检查电量与错误信息

1.8 四种运动模态与切换方法

四种模态共享底盘和轮毂电机,但机械姿态、转向方式与适用场景不同。模式切换完成后,必须同时核对车灯状态和软件模式,避免“机械已切换、APP 仍停留在旧模式”造成的异常运动。

模态主要特点典型场景局限
四轮差速四轮驱动,可原地转向,控制简单通用实验、室内 SLAM滑移转向,轮胎磨损较大
模态主要特点典型场景局限
履带越野能力强,适合小台阶和复杂地面坡面、非结构化地面磨损和阻力较大,侧门需抬起
阿克曼前轮转向,接近汽车运动模型自动驾驶、轨迹研究转弯半径有限,需要零点校准
麦克纳姆轮可横移、斜行与全向运动狭小空间、全向控制辊子接触不连续,平地要求较高
图 1-3 四轮差速/阿克曼模式切换插销位置
图 1-3 四轮差速/阿克曼模式切换插销位置

模态切换步骤

•阿克曼:拔起两侧插销,顺时针旋转约 30 度,使较长指示线朝前并锁定;车灯变绿后确认切换成功。•四轮差速:旋转至较短指示线朝前,调整轮胎孔位后将插销插入;车灯变黄后确认切换成功。•履带:先在四轮差速状态安装履带,建议先套后轮;抬起两侧侧门,防止行驶时剐蹭。•麦克纳姆轮:拆下轮毂盖和普通轮胎,保留轮毂电机;使四个辊子朝向车体中心,用 M3 x 5 螺丝安装,再在 APP/遥控器中切至对应模式。

1.9 APP_Agilex 与首次移动

APP_Agilex 用于蓝牙连接、运动控制和模式选择。不同手机系统的安装入口可能不同,请使用包装资料或官方渠道提供的版本。蓝牙的有效控制距离约 10 m,实际距离受墙体、人体遮挡和手机天线影响。

1.开机后打开 APP_Agilex,进入蓝牙扫描页面。

2.选择以 LIMO_ 开头的设备并完成连接。出现连接失败时,先关闭其他已连接的手机或遥控程序。

3.选择与底盘机械模态一致的控制模式。首次移动建议使用低速,确认左右方向后再提高速度。

4.完成实验后先停车,停止 ROS 2 节点,关闭 APP 连接,再关闭车体电源。

操作区作用首次操作建议
左侧摇杆前进、后退与速度控制小幅度推动,确认车辆方向
右侧摇杆转向或原地旋转先短时轻推,观察转向方向
模式选择阿克曼、四轮差速、麦克纳姆等与机械插销和轮系保持一致
速度设置调整控制杆速度范围调试和建图时采用较低速度
蓝牙管理扫描、重连或修改设备名称重命名后需重新连接

1.10 首次联网与登录

LIMO 的远程操作使用 RDP 共享桌面和 SSH 终端两条通道:图形界面通过 Windows 远程桌面查看,ROS 2 命令通过 SSH 执行。同一局域网内可多设备同时连接,详细步骤见第9章。

访问方式适用场景关键点
RDP共享桌面图形界面、RViz2与多设备查看双击 AgileX共享桌面.rdp;192.168.0.242:3389;使用部署密码
SSH终端运行命令、传文件、查看日志ssh agilex@192.168.0.242;GUI需设置DISPLAY环境
RDP+SSH多人协同、边看界面边执行命令RDP看界面,SSH启停节点;统一控制权,避免重复启动

小车 IP 由路由器分配,可能变化:在车端执行 hostname -I 查看当前地址,并据此更新 AgileX共享桌面.rdp 和 SSH 命令。

首次登录提示 首次连接桌面时需要小车已开机并完成系统启动。若连接后黑屏,先在远程窗口里移动鼠标或按一下 Shift 唤醒;仍无画面说明车上的桌面会话没有起来(例如未接显示器且没有登录过),到车上点亮屏幕登录一次再连。

1.11 快速上手流程

阶段要完成的操作通过标准
1. 通电前检查电量、外接线缆、轮胎、插销、周围空间无松动、无短路风险、运行区无障碍
2. 通电与模式开机,核对车灯与 APP_Agilex 模式三者与预期一致
3. 低速移动前进、后退、左转、右转、停车方向正确,无异常噪声和报警
4. 通信检查终端检查节点、话题和电池状态驱动节点稳定,/scan 与 /limo_status 正常
5. 进入实验建图、导航或视觉功能上一实验进程已关闭,场地满足安全要求
Chapter 02

第2章 安全与底盘电气信息

LIMO 使用锂电池、轮毂电机和高速旋转的激光雷达。安全操作的重点是防止电池过放或过流、避免车辆挤压与跌落,并确保切换模态后由专人复核。发现异味、异常发热、冒烟或红色报警时,应立即停止实验并断开电池。

2.1 电池基本信息

项目额定参数项目额定参数
典型容量10 Ah最小容量10 Ah
标称电压11.1 V充电截止电压12.6 V
放电截止电压8.25 V最大持续放电电流10 A
推荐存储温度-25 至 45 摄氏度充电环境0 摄氏度以上

电池有两个接口:黄色为输出接口,黑色为充电接口。运输状态下电池不一定满电,这是存储安全要求,不代表异常。长期不使用时,将电池与车体断开。

电池红线 禁止拆解、短接、加热、投入火中或在高温环境中存储;禁止使用未认证充电器;禁止在电池几乎耗尽后才长期存放。出现鼓包、漏液、异味或异常发热时停止使用。

2.2 充电流程

1.先关闭车辆并取出电池,将黄色输出接口与车体分离。

2.将充电器接头连接到电池充电接口,再接通充电器电源。

3.根据指示灯确认充电状态:红灯为充电中,绿灯闪烁为即将充满,绿灯为已充满。

4.充满后先断开电池与充电器,再断开充电器电源。

指示灯电池状态操作
红色充电中保持通风,不覆盖充电器
绿色闪烁即将充满等待涓流充电完成
绿色已充满结束充电并断开接口

标准充电器为 12.6 V / 5 A。电池从放电截止状态充至接近满电约需 2.5 h,进入绿色状态后通常还会以约

0.1 A 涓流充电约 0.5 h。实际时间受电量、温度与电池状态影响。

禁止边充边用 充电时必须将电池与车体分离,不能一边充电一边给 LIMO 供电。

2.3 使用环境与机械安全

•工作温度为 -10 至 40 摄氏度,相对湿度建议为 30% 至 80%。•设备不防水,禁止在雨、雪、积水或高湿凝露环境使用。•不要在腐蚀性、易燃性气体附近使用,也不要靠近明火或热源。•建议海拔不超过 1000 m,昼夜温差不超过 25 摄氏度。•不要推动车辆倒转电机,防止逆向发电损坏主板或电池。•未经技术支持确认,不要私自改装内部结构、供电或安全保护。

风险典型原因预防措施
碰撞或夹伤高速遥控、侧门展开、场地人员靠近设置安全区,首次低速,急停人员在场
跌落或翻车坡度过大、边界无防护、轮系不匹配在平整地面开始,坡道与台阶实验加防护
电池过放长期关机存放、低电继续使用低电及时充电,长期不用断开电池
过流保护堵转、强行推车、外加负载过大清除障碍,确认负载不超过 4 kg
雷达损伤碰撞、异物卡住旋转部件固定传感器,发现异响立即断电

2.4 供电与通信拓扑

电池为底盘、Jetson 计算单元和传感器提供系统供电,最大输出电流按 10 A 设计;USB HUB 的三个 USB接口合计输出能力有限,不应外接大功率负载。LIMO 底盘与 Jetson 通过 UART 通信,APP_Agilex 通过蓝牙与底盘交互,雷达和相机通常通过 USB 接口连接到计算单元。

APP_Agilex运动模式 / 蓝牙遥控
LIMO 底盘电机 / IMU / 车身状态
LIMO 底盘UART 双向通信
Jetson Orin NanoUbuntu 22.04 / ROS 2 Humble
传感器(USB)T-mini Pro → /scan
Dabai → RGB-D 图像
远程电脑Wi-Fi / RDP 桌面 / SSH 终端
安全边界:同一时间只保留一个 /cmd_vel 发布者。
图 2-1 底盘、计算单元、传感器与远程调试链路示意
Chapter 03

第3章 ROS 2 平台与底盘驱动

本配置的软件核心是 ROS 2 Humble。底盘驱动、雷达、相机、建图与导航由独立节点组成,通过话题、服务、动作和参数协作。开发前应建立“终端环境已 source、上一实验进程已关闭、当前模态与 launch 文件一致”的基本习惯。

3.1 系统分层与工作空间

层级主要内容作用
应用层Cartographer、Nav2、RTAB-Map、limo_visions、trt_yolo建图、定位、规划、识别与交互
通信层话题、服务、动作、TF2、参数连接各节点并同步传感器与控制数据
驱动层limo_base、ydlidar_ros2_driver、orbbec_camera、aruco_ros将硬件数据转换为 ROS 2 消息
系统层Ubuntu 22.04、ROS 2 Humble、Jetson Orin Nano运行环境、计算与硬件接口
~/agilex_ws/
  src/
    limo_ros2/
      limo_base/
      limo_msgs/
      limo_bringup/
    limo_visions/
    trt_yolo/
  install/
  build/
  log/
启动前环境 新开终端后,先加载 ROS 2 和本机工作空间。若提示找不到 limo_bringup、limo_base 或相关接口包,优先检查 setup.bash 是否加载,而不是直接修改包名。
source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
ros2 pkg list | grep -E 'limo|ydlidar|orbbec'

3.2 limo_base 驱动包

底盘驱动主要位于 ~/agilex_ws/src/limo_ros2/limo_base,用于串口连接、速度控制、里程计、IMU、车辆状态和 TF 发布。limo_msgs 提供配套的消息、服务与动作接口。

cd ~/agilex_ws/src/limo_ros2/limo_base
├── CMakeLists.txt
├── include/
├── launch/
│   ├── limo_base.launch.py
│   ├── open_ydlidar_launch.py
│   └── start_limo.launch.py
├── package.xml
├── scripts/
│   └── tf_pub.py
└── src/
    ├── limo_base_node.cpp
    ├── limo_driver.cpp
    ├── serial_port.cpp
    └── tf_pub.cpp
目录内容开发用途
include头文件与驱动接口阅读通信协议、串口与驱动结构
launch节点启动文件选择底盘、雷达或组合启动入口
scriptsPython 辅助脚本TF 发布等辅助功能
srcC++ 源代码底盘节点、驱动与串口实现

驱动核心函数与职责

函数或模块作用
connect / serial_port连接底盘串口并维护通信状态
readData / processRxData读取串口数据并处理接收缓冲区
parseFrame / sendFrame解析和封装底盘协议帧
setMotionCommand设置速度、转向和运动模式命令
enableCommandedMode使能程序控制,切换为 ROS 2 指令模式
publishOdometry发布轮式里程计与位姿信息
publishLimoState发布电池、模式、错误码等车辆状态
publishIMUData发布 IMU 加速度、角速度与姿态
twistCmdCallback接收 /cmd_vel 并转换为底盘控制量
processErrorCode识别底盘错误和保护状态
角度换算函数处理度、弧度与内外转角转换

函数名称可能随源码版本调整,修改前应先搜索节点中的版本号与头文件引用。禁止在未理解单位和坐标系时直接修改串口协议或控制模式枚举。

3.3 limo_msgs 接口

LimoStatus.msg

std_msgs/Header header
uint8 vehicle_state
uint8 control_mode
float64 battery_voltage
uint16 error_code
uint8 motion_mode

该消息用于观察底盘状态、控制模式、电池电压、错误码和运动模式。通过 /limo_status 可以在实验前确认车辆是否处于预期状态。

limo_msgs 实际提供的接口

# 确认接口包内容
ros2 interface list | grep limo_msgs
ros2 interface show limo_msgs/msg/LimoStatus

本镜像的 limo_msgs 只提供 msg/LimoStatus.msg;LimoSrv.srv 与 LimoAction.action 并不存在,limo_base 也不提供业务 service 或 action(只有 ROS 2 参数服务)。下发速度用 /cmd_vel(geometry_msgs/msg/Twist),读取状态用 /limo_status;需要自定义服务或动作时,应在自己的接口包里新建并编译。

3.4 驱动启动与话题检查

# 终端 A:启动底盘驱动
ros2 launch limo_base limo_base.launch.py
# 终端 B:查看节点、话题与状态
ros2 node list
ros2 topic list
ros2 topic echo /limo_status --once
话题类型或用途开发提示
/cmd_velgeometry_msgs/msg/Twist发布线速度与角速度,控制底盘运动
/imusensor_msgs/msg/Imu提供加速度、角速度和姿态信息
/limo_statusLimoStatus查看车辆状态、电量、错误码与运动模式
/parameter_eventsrcl_interfaces/ParameterEventROS 2 参数变化事件
/rosout日志消息检查节点日志与错误输出
/tf、/tf_staticTFMessage坐标变换与静态安装关系
/odomnav_msgs/msg/Odometry轮式里程计与位姿估计
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.10, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}"
# 发布停车命令
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}"

开发检查顺序

1.确认节点存在,且没有同一底盘驱动重复启动。

2.确认 /cmd_vel、/odom、/scan、TF 等所需话题持续发布。

3.用 /limo_status 查看电池、模式和错误码,排除底盘报警。

4.先低速发布短时命令并立即停车,再接入算法节点。

3.5 Python 开发与速度控制

本配置的底盘主驱动为 C++ 节点,Python 开发通过 ROS 2 的标准消息接口完成,不需要绕过驱动直接访问串口。只要 Python 节点按 geometry_msgs/msg/Twist 发布 /cmd_vel,就可以复用底盘驱动、Nav2 和视觉跟踪节点的控制链路。

import rclpy
from rclpy.node import Node
from geometry_msgs.msg import Twist
class LimoPublisher(Node):
    def __init__(self):
        super().__init__('limo_python_demo')
        self.pub = self.create_publisher(Twist, '/cmd_vel', 10)
        self.count = 0
        self.timer = self.create_timer(0.1, self.tick)
    def tick(self):
        msg = Twist()
        msg.linear.x = 0.10
        msg.angular.z = 0.0
        self.pub.publish(msg)
        self.count += 1
        if self.count >= 10:
            self.pub.publish(Twist())
            self.destroy_timer(self.timer)
def main():
    rclpy.init()
    node = LimoPublisher()
    rclpy.spin(node)
    rclpy.shutdown()
if __name__ == '__main__':
    main()
开发方式适用场景关键接口
Python + rclpy算法验证、订阅图像、发布速度/cmd_vel、/limo_status、/scan
开发方式适用场景关键接口
C++ + rclcpp高频控制、驱动二次开发底盘驱动源码与自定义消息
ROS 2 launch一次启动多个节点与参数launch.py 与 YAML 配置
可视化调试检查节点、TF、图像与地图RViz2、rqt_image_view、rqt_graph

从脚本到 ROS 2 节点的验证顺序

1.启动底盘驱动,并在终端检查 /cmd_vel、/odom 和 /limo_status。

2.运行只发布零速度的 Python 节点,确认没有其他程序同时控制底盘。

3.将线速度改为 0.05-0.10 m/s,执行一个消息周期后立即发布停车。

4.使用 ros2 topic echo /cmd_vel 对照实际发布值,再接续视觉或导航算法。

# 运行 Python 节点前加载环境
source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
# 检查是否已有速度发布者
ros2 node list
ros2 topic info /cmd_vel --verbose
Chapter 04

第4章 底盘运动学与四模态控制

四模态使用同一个四轮轮毂电机底盘,但转向约束、轮地接触方式和控制输入不同。运动学章节用于解释为什么不同模态需要不同的速度组合,以及出现偏航、打滑或轨迹误差时应该检查哪些物理量。所有公式均以车辆中心或后轴参考点为基准,实际符号方向应与驱动坐标约定一致。

图 4-1 模式切换插销与四轮布置关系
图 4-1 模式切换插销与四轮布置关系

4.1 四轮差速运动模型

四轮差速通过左右两侧车轮的速度差转向。直线运动时左右速度相同,原地旋转时左右速度大小相同、方向相反。四轮独立驱动但同侧车轮目标速度通常保持一致。

量关系说明
整车线速度 vv = (vL + vR) / 2vL、vR 为左右侧等效线速度
整车角速度 omegaomega = (vR - vL) / LL 为左右轮等效轮距
左轮速度vL = v - omega L / 2根据期望 v、omega 反算
右轮速度vR = v + omega L / 2差速转向的核心关系
原地旋转vR = -vLv 近似为 0,omega 不为 0

在 ROS 2 中通过 /cmd_vel 的 linear.x 与 angular.z 表达运动意图,驱动节点完成轮速分配。不要直接把轮速写到串口,否则会绕过模式检查、限速和错误保护。

# 低速直线
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.08}, angular: {z: 0.0}}"
# 低速原地转向
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.0}, angular: {z: 0.25}}"

4.2 履带运动模型

履带模式可以采用与四轮差速相同的左右速度差模型。不同点在于履带与地面的接触长度更大,转向需要剪切地面,摩擦阻力、侧向约束和磨损均高于轮式差速。

•直行时可把左右履带看作速度相同的两组连续接触单元。•转向依靠左右履带速度差,转弯中心通常存在滑移,不能等同于前轮转向。•硬质地面长时间原地旋转会加剧磨损,建议采用较大半径的连续转弯。•履带模式沿用差速 launch;安装履带时必须抬升侧门,防止结构剐蹭。

场景建议参数原因
室内平地首次测试线速度不超过 0.08 m/s便于观察干涉和履带跑偏
台阶或坡面先人工评估,低角速度接近避免重心变化导致翻车
狭小空间短时差速转向履带滑移使急转更容易擦碰边界

4.3 阿克曼运动模型

阿克曼模式通过前轮转角改变车辆航向,内外前轮的转角不同,使各车轮运动方向尽量围绕后轴延长线上的同一瞬时转向中心。此模式更接近汽车运动学,适合轨迹跟踪和自动驾驶实验。

几何关系含义工程关注
转弯半径 R参考点至瞬时转向中心的距离LIMO 最小转弯半径约 0.4 m
轴距 Lw前轴与后轴距离影响相同转角下可达的转弯半径
轮距 W左右轮中心距离决定内外轮的转角差
内轮与外轮内侧轮胎走更小半径前轮连杆机构自动产生角度差
前轮转角 deltatan(delta) 与车长和半径相关小速度时近似成立,高速需考虑侧偏

•直线行驶需要左右前轮回正;发现车辆持续向一侧偏移时应检查舵机零点。•启动导航必须使用阿克曼入口,不能只修改 /cmd_vel 参数代替机械切换。•高速急转会导致侧向滑移,实验优先采用低速大半径轨迹。•如果机械插销拔起但车灯仍为黄色,应停止运动并回落插销重新切换。

4.4 麦克纳姆轮运动模型

麦克纳姆轮由轮毂和斜向被动辊子组成,四个独立驱动的轮子可以在不发生转向的前提下产生纵向、横向和旋转运动的组合。辊子的旋向和安装方向必须严格成对,否则横向速度分量会相互抵消。

运动意图四个轮子的速度形态结果
前进/后退四轮同向转动产生纵向线速度
左右横移对角轮同向、另一对角反向产生横向线速度
原地旋转两侧轮系反向组合产生角速度,车体中心平移近零
斜向运动纵向与横向速度叠加车体按合成方向平移

四轮速度分配依赖轮距、轴距、辊子安装角度和正方向定义。驱动源码中必须保持同一套符号约定;若只调换其中一个轮子的接线而不改速度矩阵,会出现横移方向错误、原地旋转中心和漂移。

4.5 四模态选择建议

模态优点局限优先用途
四轮差速控制简单、适应性强转向滑移,轮胎磨损SLAM、导航通用实验
履带接地面积大,通过性好阻力与磨损大,侧门需抬起坡面、小台阶、非结构地面
阿克曼接近汽车模型,轨迹平顺转弯半径有限,需要零点标定轨迹跟随、自动驾驶研究
麦克纳姆可全向移动,机动性好辊子接触不连续,平地要求高狭小空间、全向控制
Chapter 05

第5章 激光雷达建图

本配置使用 EAI T-mini Pro 360 度二维激光雷达。激光建图的目标是构建可被 Nav2 使用的二维栅格地图。建图质量不仅取决于算法,还取决于初始位姿、行驶速度、场地反光、动态行人和里程计稳定性。

5.1 雷达参数与数据

项目最小默认最大说明
测距频率-4000 Hz-每秒 4000 次测距
扫描频率6 Hz12 Hz通常采用 6 Hz
测距范围0.02 m-12 m室内、80% 反射率条件
扫描角度-0-360 度-二维平面扫描
测距精度-20 mm-0.05-12 m 范围
角度分辨率-0.54 度-数据密度参考

雷达数据发布在 /scan 话题,消息类型为 sensor_msgs/msg/LaserScan。常见字段包括 angle_min、angle_max、angle_increment、range_min、range_max、ranges 与 intensities。

# 单独启动雷达
ros2 launch ydlidar_ros2_driver ydlidar.launch.py
# 新终端启动 RViz2,添加 LaserScan 并选择 /scan
rviz2
图 5-1 RViz2 中显示 /scan 的绿色激光点
图 5-1 RViz2 中显示 /scan 的绿色激光点

5.2 GMapping 建图

GMapping 是基于粒子滤波的二维 SLAM 方法,常把轮式里程计与激光扫描结合,适合面积较小、结构相对清晰的室内场景。使用前先确认本机镜像是否提供对应的 ROS 2 GMapping 包与组合 launch(如 slam_gmapping、limo_gmapping.launch.py);没有则直接使用本手册的 Cartographer 方案。

检查项含义建议
scan topic输入激光数据应为 /scan 或 launch 中重映射后的话题
odom topic轮式里程计检查 /odom 与 TF 连续更新
particles粒子数量资源充足时可提高,过大将增加 CPU 负载
delta栅格地图分辨率常用 0.05 m,过小会增大内存和计算量
maxRange有效激光距离应小于或等于雷达可靠测距范围
# 先检查当前镜像是否提供 GMapping
ros2 pkg list | grep -E 'gmapping|slam'
ros2 pkg executables slam_gmapping
# 若 limo_bringup 提供组合入口
ros2 launch limo_bringup limo_start.launch.py
ros2 launch limo_bringup limo_gmapping.launch.py
# 检查地图与激光
ros2 topic echo /map --once
ros2 topic hz /scan

5.3 Cartographer 原理

Cartographer 是基于图优化的 SLAM 系统,可拆分为 Local SLAM 与 Global SLAM。Local SLAM 用连续激光帧建立并维护子图 Submap;Global SLAM 在子图之间执行回环检测和位姿优化,减少长距离行驶后的累积误差。

模块输入输出调参关注
Local SLAM激光帧、里程计、IMU局部子图与短期轨迹扫描频率、运动速度、传感器标定
Global SLAM已完成子图回环约束与优化轨迹回环半径、计算资源、场景相似度
图 5-2 Cartographer 建图界面示例
图 5-2 Cartographer 建图界面示例

5.4 Cartographer 建图操作

开始前 清空场地障碍,保持正常室内光照;关闭上一次建图、导航和雷达进程。首次行驶采用低速,避免急转、原地高速旋转和人员穿行。 1.终端 A 启动底盘与雷达组合功能。2.终端 B 启动 Cartographer,等待 RViz2 打开。

3.在 RViz2 中检查 /scan、地图、TF 和机器人模型,确认初始位置无跳变。

图 5-3 Cartographer 建图完成后的栅格地图与激光点重合效果
图 5-3 Cartographer 建图完成后的栅格地图与激光点重合效果

图为 Cartographer 运行约 4 分钟(面板 ROS Elapsed 239.92 s)时的 RViz2 画面:Fixed Frame 为 map,浅灰是已建栅格,白色小方块是当前帧 /scan。

第一组判据在左侧 Map 面板:Topic 为 map、Resolution 0.05、Width 188、Height 190,即约 9.4 m × 9.5 m、每格 5 cm;这两个数随场地和行驶范围变化,不是固定值(短距离试跑可能只有 91 × 127)。第二组判据看激光与墙线:白色点应紧贴灰色墙体边缘,出现双层墙或明显错位说明回环不足或里程计漂移,按 5.6 节降速并回到已见区域闭环。第三组看状态:Fixed Frame 无报错、LaserScan 的 Topic 为 /scan;若 RViz2 提示 map 不存在,先查 limo_cartographer.launch.py 日志里有没有 Inserted submap。

激光点完全不显示时,先把 LaserScan 的 Reliability Policy 改成 Best Effort:本机 /scan 的 QoS 是 BEST_EFFORT,RViz2 默认的 Reliable 收不到。

4.使用 APP_Agilex 低速遥控,先沿边界,再覆盖内部区域;尽量闭环回到起点。

5.地图边界稳定、回环重合后停车,保存地图。

# 终端 A:底盘与雷达
ros2 launch limo_bringup limo_start.launch.py
# 终端 B:Cartographer
ros2 launch limo_bringup limo_cartographer.launch.py
# 终端 C:保存地图
mkdir -p ~/agilex_ws/src/limo_ros2/limo_bringup/maps
cd ~/agilex_ws/src/limo_ros2/limo_bringup/maps
ros2 run nav2_map_server map_saver_cli -f map01

保存后通常得到 map01.pgm 与 map01.yaml。两个文件必须放在同一目录并保持文件名对应。YAML 中的image 字段应指向实际 PGM 文件,分辨率通常由建图参数决定。

5.5 RRT 自主探索建图

RRT 通过随机采样和快速扩展树在未知区域生成探索路径,机器人可在人工设定边界后自动选择前沿目标并逐步覆盖环境。RRT 不是基础底盘功能,需要导航、地图更新、目标管理和探索节点同时就绪。

1.先验证人工遥控建图,确认地图、/scan、TF 和 Nav2 状态正常。

2.启动探索节点,在 RViz2 中设置四个环境边界点和一个搜索起始点。

3.让系统低速探索,观察机器人是否反复访问同一区域或进入狭窄死路。

4.覆盖完成后停止探索节点,保存最终地图并检查边界是否闭合。

# 检查探索包是否已集成
ros2 pkg list | grep -E 'rrt|exploration'
# 示例入口:实际 launch 名称以本机 rrt_exploration 包为准
ros2 launch limo_bringup limo_start.launch.py
ros2 launch limo_bringup limo_cartographer.launch.py
ros2 launch limo_bringup limo_nav2_diff.launch.py
ros2 launch rrt_exploration rrt.launch.py

5.6 建图质量检查

现象可能原因处理
墙体双层或错位速度过快、回环不足、里程计漂移降速、回到已见区域闭环、检查轮径参数
地图断续激光遮挡、反光、TF 中断调整路线,检查 /scan 与 TF 频率
原点附近轨迹跳变初始位姿未稳定或驱动重复关闭所有进程后按单一入口重启
地图边缘像扇面转弯过快或扫描频率不匹配低速转弯,检查扫描频率和计算负载
Chapter 06

第6章 ROS 2 激光导航与路径巡检

LIMO ROS 2 配置采用 Nav2 导航栈。导航系统需要地图、定位、传感器、底盘控制和目标管理共同工作;本节按 ROS 2 Humble 与 Nav2 的术语和命令描述系统。

6.1 Nav2 组件

组件作用调试关注
Map Server加载 PGM/YAML 地图地图路径、分辨率、原点
AMCL在地图中估计机器人位姿初始位姿、粒子分布、激光与地图重合
Planner Server生成全局路径代价地图、膨胀半径、路径是否合理
Controller Server执行局部轨迹与控制速度限制、障碍距离、振荡与恢复
Behavior Server处理旋转、后退、等待等恢复行为卡住时是否自动恢复
BT Navigator组织导航行为树单点、多点、失败重试流程
参数以本机为准 本手册按 ROS 2 Humble 和 Nav2 统一表述;实际启用的 planner/controller 插件及参数,请以本机 launch 与 YAML 配置为准。
图 6-1 Nav2 与 RViz2 导航界面示例
图 6-1 Nav2 与 RViz2 导航界面示例

6.2 启动导航

先启动底盘与雷达,再启动与当前运动模态匹配的导航 launch。四轮差速、履带和麦克纳姆通常使用差速控制入口;阿克曼必须使用阿克曼入口,不能混用。

# 通用终端 A
ros2 launch limo_bringup limo_start.launch.py
# 四轮差速 / 履带 / 麦克纳姆
ros2 launch limo_bringup limo_nav2_diff.launch.py
# 阿克曼
ros2 launch limo_bringup limo_nav2_ackermann.launch.py

6.3 建立初始位姿

1.在 RViz2 中确认地图、/scan、TF、机器人模型与代价地图显示正常。

2.使用 2D Pose Estimate 在地图上给出车辆的位置与朝向。

3.低速遥控车辆旋转或小范围移动,使激光点与墙体轮廓重合。

4.在粒子云收敛、轮廓基本重合后再发布导航目标。

图 6-2 通过初始位姿与激光轮廓完成地图对齐
图 6-2 通过初始位姿与激光轮廓完成地图对齐

如果激光与地图始终不重合,不要用导航目标强行测试。先检查地图是否为当前场地、起始位置是否与建图坐标一致、TF 是否完整,以及手机摇杆是否仍处于手动接管状态。

6.4 单点与多点导航

点击 Nav2 Goal,在地图上选择目标位置与朝向;系统将生成全局路径和局部控制轨迹。车辆开始运动后,保持底盘处于指令模式(limo_base 启动时已通过 0x421 进入),并断开 APP_Agilex 蓝牙或让它停在非控制页面,避免手机摇杆与导航节点同时发布速度。

图 6-3 多点导航与开始执行按钮示例
图 6-3 多点导航与开始执行按钮示例

•全局路径应避开墙体与膨胀区域;若穿过障碍,先检查地图和代价地图参数。•局部路径频繁摆动时,降低速度、检查雷达遮挡和控制器参数。•卡住后观察行为树是否触发旋转、后退或等待恢复。•多点导航前先测试单点,确认每个途经点位于可通行区域。

检查项正常现象异常处理
定位粒子集中在机器人附近并逐渐稳定重新设置初始位姿或检查地图
激光与地图轮廓基本重合检查坐标系、地图版本和起始位置
全局路径连续且避障检查地图、代价地图与目标点
底盘响应速度平滑、无明显振荡降低速度并检查控制器参数
APP 状态指令模式,不持续手动摇杆切换模式后重新发送目标

6.5 导航前安全检查

1.清空路径与人行通道,确保急停人员能够迅速接近车辆。

2.确认电量足以完成路线,避免低电时速度限制或突然停止。

3.核对地图版本和当前场地,移走建图后新增的临时障碍。

4.从短路线和低速参数开始,确认目标朝向和停车行为后,再执行多点任务。

6.6 路径记录与巡检

路径巡检先录制一次人工驾驶路线,再由 limo_path_patrol 节点按 CSV 复跑。

6.6.1 运行边界与接口

同一时间只允许一个 /cmd_vel 发布者。巡检期间不要启动 MyCobot GUI、listen_real_service、mycobot_adapter、Nav2、手机 App、键盘遥控或其他会控制底盘的程序。

功能实际接口说明
底盘节点/limo_base_node接收 /cmd_vel,发布 /odom 和 /limo_status
雷达节点/ydlidar_ros2_driver_node发布 /scan
里程计/odom路径录制和跟随都必须使用该话题
雷达/scan跟随节点的前方障碍保护输入
速度控制/cmd_vel同一时间只能保留一个发布者

6.6.2 启动前检查

每次上电后先检查底盘状态、里程计、雷达和速度发布者。

检查项通过标准异常处理
/limo_statuscontrol_mode=1、error_code=0,电压明显高于低电量范围;正常约 12 V关机充电或检查底盘报警
/odom持续更新重启底盘驱动并检查串口
/scan持续更新重启雷达并检查 USB 连接
/cmd_vel录制前为 0 或仅有键盘遥控;巡检期间仅有 follower关闭多余控制程序
source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash

ros2 topic echo /limo_status --once
ros2 topic echo /odom --once
ros2 topic echo /scan --once
ros2 topic info /cmd_vel --verbose
ros2 node list | grep limo_path_patrol
ps -eo pid,cmd | grep '[f]ollow_path'

正常情况下只能存在一个 /limo_path_patrol_follower。重复启动 follower 会让两个节点同时创建 start、stop 服务和 /cmd_vel 发布者,可能导致控制指令冲突。

6.6.3 录制并校验路线

步骤 1:启动底盘和雷达。在终端 A 执行并保持运行,确认 /limo_base_node 和 /ydlidar_ros2_driver_node 已出现。

source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
ros2 launch limo_bringup limo_start.launch.py

ros2 node list | grep -E 'limo_base|ydlidar'

步骤 2:开始录制新路线。在终端 B 执行。新录制结果会覆盖旧路线,录制器把第一条 /odom 样本作为路线原点。

mkdir -p ~/.ros/limo_path_patrol
ros2 launch limo_path_patrol record_path.launch.py \
  path_file:="$HOME/.ros/limo_path_patrol/lab_route.csv" \
  odom_topic:=/odom

看到 First odometry sample received; route started. 后再开始驾驶。CSV 中的 x、y、yaw 都是相对该原点的位置和朝向。

步骤 3:启动键盘遥控。在终端 C 执行。连续按 q 降低速度,不要使用默认高速录制。

source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
ros2 run teleop_twist_keyboard teleop_twist_keyboard
按键功能
i前进
逗号 (,)后退
j左转
l右转
k立即停车
q降低整体速度

步骤 4:驾驶并录制路线。把小车放在固定起点、摆正车头,先按 i 直线前进一小段,再开始正常转弯;到达终点后按 k 停车。

  • 保持低速、连续和平滑,不突然加速、不急转弯。
  • 开始记录后不要先按 j 或 l 原地旋转,也不要横穿已经走过的路线。
  • 路线周围不要有新增固定障碍;第一段应是从静止直接缓慢前进。

步骤 5:保存路线。回到终端 B 按 Ctrl+C。只有看到 Saved ... points, route length ... m 才表示保存完成;没有 Saved 时不要继续巡检。

步骤 6:关闭键盘遥控。回到终端 C 按 Ctrl+C,再执行 ros2 topic info /cmd_vel --verbose,确认 teleop_twist_keyboard 已消失。

步骤 7:校验路线文件。以下脚本只读取 CSV,不会让小车运动。

python3 - <<'PY'
import csv
import math
from pathlib import Path

path = Path.home() / ".ros/limo_path_patrol/lab_route.csv"
with path.open(newline="", encoding="utf-8-sig") as f:
    rows = [(float(r["x"]), float(r["y"]), float(r["yaw"]))
            for r in csv.DictReader(f)]

if len(rows) < 2:
    raise SystemExit("FAIL: route has fewer than 2 points")

steps, turns = [], []
for a, b in zip(rows, rows[1:]):
    steps.append(math.hypot(b[0] - a[0], b[1] - a[1]))
    turns.append(abs(math.atan2(math.sin(b[2] - a[2]),
                               math.cos(b[2] - a[2]))))

route_length = sum(steps)
start_end = math.hypot(rows[-1][0] - rows[0][0],
                       rows[-1][1] - rows[0][1])
max_step = max(steps)
max_turn = max(turns)

cumulative = 0.0
initial_rotation = 0
for step, turn in zip(steps, turns):
    if cumulative > 0.20:
        break
    if step < 0.005 and turn > math.radians(3.0):
        initial_rotation += 1
    cumulative += step

print(f"points={len(rows)}")
print(f"route_length_m={route_length:.3f}")
print(f"start_end_distance_m={start_end:.3f}")
print(f"step_min_max_m={min(steps):.3f}..{max_step:.3f}")
print(f"max_turn_deg={math.degrees(max_turn):.1f}")
print(f"initial_rotation_segments={initial_rotation}")

failures = []
if len(rows) < 20:
    failures.append("too few points")
if route_length < 1.0:
    failures.append("route too short")
if max_step > 0.20:
    failures.append("large position jump")
if initial_rotation > 0:
    failures.append("rotation-only start")
if failures:
    print("FAIL:", ", ".join(failures))
    raise SystemExit(1)
print("PASS: route meets basic patrol checks")
PY
校验指标本次结果
路线点数160
路线长度8.691 m
起点到终点距离0.996 m
相邻点间距0.050–0.060 m
最大相邻点转角3.9°
起步原地旋转片段0
结论PASS

6.6.4 启动路径跟随与自动巡检

步骤 8:启动路径跟随节点。继续使用终端 B。该步骤只加载路线并等待服务,小车不会运动。

source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
ros2 launch limo_path_patrol follow_path.launch.py \
  path_file:="$HOME/.ros/limo_path_patrol/lab_route.csv" \
  odom_topic:=/odom \
  linear_speed:=0.05
参数本次值要求
linear_speed0.05 m/s首次复跑固定使用低速
obstacle_distance0.35 m前方障碍小于该距离自动停车
max_cross_track_error0.60 m偏离路线过大自动停车
goal_tolerance0.15 m到达终点附近自动结束
autostartfalse防止节点启动后立即运动

步骤 9:把小车放回录制起点。地面位置和车头方向要与录制开始时一致,并确认路线周围没有新增障碍、键盘遥控已经关闭、/cmd_vel 只剩 follower。

步骤 10:通过服务启动巡检。在终端 C 执行。成功时返回 success=True 和 Patrol started.;节点等待约 2 秒后开始发布 /cmd_vel。

ros2 service call /limo_path_patrol/start \
  std_srvs/srv/Trigger "{}"
步骤作用小车是否运动
步骤 8:启动 follow_path读取 CSV,连接 /odom、/scan,创建服务并等待 start不运动
步骤 10:调用 start 服务记录当前起点,重置路线进度,等待 2 秒后发布 /cmd_vel开始运动

6.6.5 前 10 秒检查与停止

巡检不是调用 start 后就结束。启动后应立即检查运动指令和里程计是否同时变化。

ros2 topic echo /cmd_vel --once
ros2 topic echo /odom --once
sleep 3
ros2 topic echo /odom --once
ros2 topic echo /limo_status --once
观察结果判断与处理
/cmd_vel 约 0.05 m/s,/odom 位置连续变化继续巡检并观察终点停车
/cmd_vel 持续非零,但 /odom 数秒不变立即调用 stop、发布零速度并检查 /limo_status
/limo_status 显示 8.9 V、error_code=3低电量保护:关机充电,不要提高速度
没有 /cmd_vel 或 scan is stale停止巡检,检查 follower 日志、雷达和重复进程
ros2 service call /limo_path_patrol/stop \
  std_srvs/srv/Trigger "{}"

ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}"

正常停止时调用 stop 服务即可,follower 程序仍然保留,可再次调用 start。紧急停止时优先按物理急停,也可以在终端 B 按 Ctrl+C 结束 follow_path,再调用 stop 并发布零速度。

error_code=3 的低位定义如下:0x0001 和 0x0002 均为低电量;0x0004 为遥控器失联;0x0008、0x0010、0x0020、0x0040 分别为 1–4 号电机驱动错误;0x0100 为驱动状态错误。

常见现象优先检查处理
出现 Cross-track error起点或车头方向不一致回录制起点对齐车头,必要时重录
录制后没有 Saved是否按 Ctrl+C,点数是否至少为 2重新录制并保存
/cmd_vel 有多个发布者Nav2、teleop、App、重复 follower只保留一个巡检发布者
有 /cmd_vel 但车不动/limo_status 电压、错误码、控制模式error_code=3 时关机充电
Laser scan is stale雷达节点和 /scan重启雷达并检查数据
No odometry received/odom重启底盘并检查串口
start 返回 already running上次巡检未 stop 或 follower 重复先 stop,再检查 follower 数量
第一次复跑偏离起点方向不对或路线开头旋转重录路线,不要放宽 0.60 m 阈值

6.6.6 验收与本次恢复

一条可自动复跑的路线应从固定起点开始,车头方向固定,开始记录后先直线前进,低速连续驾驶,不原地旋转、不急转弯、不横穿原路线,并且航线周围没有新增固定障碍。路线文件不要手工编辑,重新录制比修改 CSV 更可靠。

阶段通过标准
录制前环境已加载;/limo_base_node、/ydlidar_ros2_driver_node、/odom、/scan 正常;control_mode=1、error_code=0;没有多余 /cmd_vel 发布者
录制后出现 Saved;CSV 至少 20 个点、路线长度大于 1 m、最大相邻点间距不超过 0.20 m、起步没有原地旋转
自动巡检前键盘遥控已关闭;/cmd_vel 只有 limo_path_patrol_follower;只有一个 follower;小车回到录制起点并摆正车头;人员和急停就位
自动巡检后start 返回 success=True;/cmd_vel 约 0.05 m/s;/odom 位置连续变化;到达终点或调用 stop 后及时停车

本次恢复步骤:小车已经关机充电,充电完成后按以下顺序恢复。

  • 开机,等待底盘和网络启动。
  • source /opt/ros/humble/setup.bash 和 source ~/agilex_ws/install/setup.bash。
  • 启动 limo_start.launch.py。
  • 执行 ros2 topic echo /limo_status --once,确认 error_code=0、电压恢复正常。
  • 确认 /odom 和 /scan 都有数据。
  • 启动 follow_path.launch.py,保持 linear_speed:=0.05、autostart=false。
  • 把小车放回录制起点并摆正车头。
  • 关闭所有其他 /cmd_vel 发布者。
  • 调用 start 服务。
  • 前 10 秒确认 /cmd_vel 非零且 /odom 连续变化;若仍不变化,立即停止并重新检查 /limo_status。
Chapter 07

第7章 深度相机与雷达融合建图导航

ORBBEC Dabai 提供彩色与深度信息。RTAB-Map 将 RGB-D 数据、里程计和可选激光数据结合起来,构建三维环境地图并支持视觉定位。与纯激光导航相比,RGB-D 方案对纹理和光照更敏感,因此需要控制车速、保持相机清洁并保证计算负载稳定。

7.1 Dabai 深度相机

项目参数项目参数
深度距离0.3-3 m基线40 mm
深度 FOVH 67.9 度 / V 45.3 度彩色 FOVH 71 度 / V 43.7 度
深度分辨率最高 640 x 400 at 30 FPS彩色分辨率最高 1920 x 1080 at 30 FPS
精度1 m 处约 6 mm延迟30-45 ms
数据传输USB 2.0 或以上供电USB
工作温度10-40 摄氏度尺寸59.6 x 17.4 x 11.1 mm
# 启动相机
ros2 launch orbbec_camera dabai.launch.py
# 查看可用话题
ros2 topic list | grep -E 'color|depth|camera'
# 可视化图像
ros2 run rqt_image_view rqt_image_view
图 7-1 使用 rqt_image_view 检查相机画面
图 7-1 使用 rqt_image_view 检查相机画面

7.2 RTAB-Map 建图

RTAB-Map 的核心是外观与几何约束结合的地图管理。它通过关键帧、回环检测和图优化提高长路线的一致性,并可使用 RGB-D 数据构建稠密地图。计算资源不足时,算法会增加地图管理负担,因此应使用适当分辨率并控制处理频率。

数据库安全:limo_rtab_rgbd.launch.py 默认以 rtabmap -d 启动建图,会删除并重建 ~/.ros/rtabmap.db。需要重新建图时可直接执行;需要加载已有地图时,应先备份数据库,并使用 localization:=true,不能再次以默认建图模式启动。

# 终端 A:底盘与雷达
ros2 launch limo_bringup limo_start.launch.py
# 终端 B:深度相机
ros2 launch orbbec_camera dabai.launch.py
# 终端 C:RTAB-Map RGB-D 建图
ros2 launch limo_bringup limo_rtab_rgbd.launch.py
地图保存位置 建图完成后正常结束节点。数据库通常位于 ~/.ros/rtabmap.db。~/.ros 是隐藏目录,可在文件管理器按 Ctrl+H 显示。实验结束 前应把数据库复制到项目目录并备份。
图 7-2 RTAB-Map 建图与地图可视化界面
图 7-2 RTAB-Map 建图与地图可视化界面

7.3 RTAB-Map 定位导航

# 终端 A:底盘与雷达
ros2 launch limo_bringup limo_start.launch.py
# 终端 B:深度相机
ros2 launch orbbec_camera dabai.launch.py
# 终端 C:载入数据库并进入定位模式
ros2 launch limo_bringup limo_rtab_rgbd.launch.py localization:=true
# 终端 D:启动 Nav2 导航
ros2 launch limo_bringup limo_rtab_nav2.launch.py

使用视觉定位时,通常不需要像纯激光导航那样先在 RViz2 中手工校正二维位姿。启动 localization:=true 前必须确认 ~/.ros/rtabmap.db 是本次任务对应的数据库,并等待当前画面与地图定位状态稳定后再发送 Nav2 目标。

图 7-3 RTAB-Map 导航目标与路径显示
图 7-3 RTAB-Map 导航目标与路径显示
问题检查方向
定位无法启动数据库路径、数据库版本、launch 参数 localization:=true
当前位置识别错误光照变化、纹理不足、相机遮挡、相似场景
地图更新慢或卡顿降低相机分辨率或处理频率,关闭不必要节点
导航不启动定位状态、Nav2 生命周期、TF 和地图是否就绪
Chapter 08

第8章 视觉识别、巡线与交互应用

视觉节点均依赖 Dabai 相机。每次实验只启动一个相机驱动,并在新终端中检查图像话题后再启动识别节点。视觉算法受光照、目标尺寸、背景颜色和相机角度影响,示例命令用于功能验证,不应直接视为生产级参数。

8.1 通用准备

# 启动相机
ros2 launch orbbec_camera dabai.launch.py
# 检查图像话题
ros2 topic list | grep -E 'color|image'
# 可视化并选择图像话题
ros2 run rqt_image_view rqt_image_view

8.2 文字识别

文字识别节点获取 RGB 图像并执行灰度化、二值化等预处理,再调用 tesseract 识别文字。需要注意:镜像自带的 C++ 节点 ros2 run limo_visions recognition 只发布标注图像 /image_hsv,不发布 /ocr/result;需要结构化结果时使用下面的前置安装与 Python 脚本(/ocr/result 为 JSON,/ocr/image 为带框图像)。提高成功率的要点是正对目标、提高对比度并减少反光。

# 前置:tesseract 与 Python 绑定(只需一次)
sudo apt install tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng
pip3 install --user pytesseract
# 终端 A:启动相机
ros2 launch orbbec_camera dabai.launch.py
# 终端 B:文字识别,输出 /ocr/result 与 /ocr/image
cd /home/agilex/agilex_ws/src/limo_visions/scripts
python3 limo_recognition_text_read.py
图 8-1 文字识别实验画面
图 8-1 文字识别实验画面

8.3 颜色识别

颜色识别把相机 RGB 图像转换为适合颜色分割的空间,按预设阈值提取目标区域,再通过轮廓、边界框或中心点输出识别结果。它只判断画面中哪里出现指定颜色,不一定改变底盘速度。

ros2 launch orbbec_camera dabai.launch.py
ros2 run limo_visions recognition
调试点影响建议
HSV 色相范围颜色类别是否被选中在固定光源下取样重新标定
饱和度与亮度阴影和反光是否误检限制高亮区域并增加形态学处理
最小轮廓面积小色块噪声按目标实际像素大小设置阈值
相机曝光颜色漂移和过曝关闭自动曝光或锁定参数

8.4 视觉巡线(FollowLine)

本机 limo_visions 的 object_detect 可执行文件实际运行 FollowLine 节点。它订阅 /camera/color/image_raw,发布 /image_hsv 和 /cmd_vel。该节点不是只读的颜色识别工具,一旦识别到线路就可能直接驱动底盘;测试前必须架空车轮或清空场地,并确认没有其他速度发布者。

ros2 launch orbbec_camera dabai.launch.py
ros2 run limo_visions object_detect
# object_detect 即 FollowLine,会发布 /cmd_vel
图 8-2 object_detect / FollowLine 视觉巡线节点
图 8-2 object_detect / FollowLine 视觉巡线节点

8.5 升降杆控制(选配)

选配升降杆控制通过相机识别升降杆上方的二维标记,估计车辆与升降杆的距离。当距离进入设定阈值时,视觉节点向 /chatter_updown 发布触发消息,使升降杆抬起,并从产生触发到车辆通过的短暂时间内保持开放。本机没有安装 detect_ros 时说明未配置升降杆,按选配跳过本节命令。

ros2 launch orbbec_camera dabai.launch.py
ros2 launch detect_ros agx_ar_pose.launch.py
# 若镜像未提供该 launch,可按包内实际可执行文件运行
ros2 run detect_ros agx_ar_pose
现象可能原因调参方向
左右摆动比例增益过大降低角速度比例项
偏离后回不来增益过小或图像阈值错误提高增益,检查线路掩模
转弯冲出路外线速度过快、前瞻距离过短降低速度,增加预测距离
完全无线相机话题或 launch 名称不匹配检查图像话题与包内 launch

8.6 ArUco 二维码识别与跟随

ArUco 标记由黑白几何编码组成,aruco_ros 负责检测标记并估计位姿。应保证标记平整、尺寸一致、周围有留白,且摄像头能完整看到标记。

ros2 launch orbbec_camera dabai.launch.py
ros2 launch aruco_ros single.launch.py
ros2 run limo_visions move_to_ar
标记测试 打印标记时不要裁掉白色边界,也不要使用高反光纸张。训练前先检查标记 ID 与启动参数一致。

8.7 红绿灯识别

红绿灯节点将图像转换到 HSV 空间,按色相区间提取红色、黄色和绿色区域,再进行形态学处理、轮廓与外接圆检测,最后在图像上标出候选灯色,标注结果发布到 /image_hsv。环境光、曝光和红色背景是主要干扰因素。

ros2 launch orbbec_camera dabai.launch.py
ros2 run limo_visions traffic_light
图 8-3 在 rqt_image_view 中查看 /image_hsv 的红绿灯标注结果
图 8-3 在 rqt_image_view 中查看 /image_hsv 的红绿灯标注结果

图中是在 rqt_image_view 里选择 /image_hsv 后看到的画面:同一帧里三个灯位分别被标成 GREEN、YELLOW、RED,说明颜色分割、轮廓与外接圆检测都在正常工作。

判读要点:圆圈应落在灯体上;圈落在背景上或某个灯位没有圈时,先调整 HSV 色相区间与最小轮廓面积,再锁定相机曝光、避免窗光直射。三个灯同时被标出只表示画面里出现了这三类颜色区域,是否按红灯停车要由上层逻辑再判一次。窗口第二行的 /ocr/image_mouse_left 是保存图片用的路径框,与本图判读无关。

8.8 Ultralytics YOLO 目标检测

Jetson Orin Nano 可使用 TensorRT 加速的 YOLO 节点进行对象检测。首次运行前应确认模型文件、类别配置和相机话题与 launch 文件一致。

ros2 launch orbbec_camera dabai.launch.py
ros2 launch trt_yolo yolov8n_det.launch.py
图 8-4 YOLO 实时对象检测界面
图 8-4 YOLO 实时对象检测界面

下图为另一组实测画面:在 rqt_image_view 中选择 /yolov8/detection_image 后,节点对椅子目标输出检测框和类别标签,可用于确认图像话题和检测结果是否正常。

图 8-5 Ultralytics YOLO 对椅子目标的检测结果
图 8-5 Ultralytics YOLO 对椅子目标的检测结果
应用启动入口观察结果
文字识别limo_recognition_text_read.py/ocr/result 与终端输出
应用启动入口观察结果
颜色识别ros2 run limo_visions recognition目标区域、分类或图像标注
视觉巡线ros2 run limo_visions object_detect线路中心、/image_hsv 与 /cmd_vel 控制
升降杆ros2 launch detect_ros agx_ar_pose.launch.py距离阈值与 /chatter_updown 触发
视觉巡线ros2 launch limo_deeplearning follow_lane.launch.py线路偏移与 /cmd_vel 控制
ArUcoaruco_ros single.launch.py + move_to_ar标记 ID、位姿与跟随动作
红绿灯ros2 run limo_visions traffic_light图像中的灯色标记
YOLOtrt_yolo yolov8n_det.launch.py检测框、类别与置信度

8.9 视觉综合实验建议

实验输入目标输出安全要求
文字读取正面标牌识别文本与置信结果车辆保持静止
颜色巡检不同色块颜色类别和目标中心先验证颜色阈值,再接入速度
视觉巡线连续线条偏移、角速度和控制量设置最大速度与出线停车
红绿灯联动红绿目标灯色状态与停车条件识别到红灯必须优先停车
YOLO 检测目标物体类别、检测框与置信度检测和规划解耦,避免误检直接急转

综合实验应先验证单一视觉输出,再允许节点发布 /cmd_vel。建议增加“超时未识别即停车”和“单条消息最大持续时间”两项保护,避免旧识别结果持续驱动车辆。

Chapter 09

第9章 远程桌面、SSH与多设备协同

LIMO 的远程调试由两条通道组成:RDP 共享桌面负责查看和操作 Ubuntu 桌面、RViz2 与图形工具,SSH 终端负责运行 ROS 2 命令、传输文件和查看日志。两条通道可以同时使用,也可以从多台电脑同时连接。

9.1 网络准备与共享桌面文件

小车和所有控制电脑必须连接到同一个可互通局域网。优先使用实验室内网,不要使用会隔离设备的访客 WiFi。如果小车 IP 发生变化,先在车端执行 hostname -I 获取地址,再更新共享桌面文件。

  1. 在小车终端执行 hostname -I,记录当前局域网 IP。
  2. 将 Windows 电脑连接到同一路由器或实验内网。
  3. 双击 AgileX共享桌面.rdp。当前配置默认指向 192.168.0.242:3389,用户名为 agilex。
  4. 如果地址变化,右键 .rdp 文件选择“编辑”,修改“计算机”字段并保存。
项目当前配置说明
桌面入口AgileX共享桌面.rdp无需安装额外远程桌面客户端
远程地址192.168.0.242:3389IP 变化时修改 .rdp 中的计算机地址
登录账号agilex密码使用部署时设置的小车桌面密码
网络要求同一局域网电脑能够访问小车的 3389 端口
图 9-1 AgileX共享桌面.rdp 连接入口
图 9-1 AgileX共享桌面.rdp 连接入口
多设备同时连接 可以把 AgileX共享桌面.rdp 复制到多台 Windows 电脑,车端和电脑位于同一局域网时可同时连接。建议一人负责图形界面或 RViz2,一人通过 SSH 执行命令,另一台设备用于观察或记录。多人共用同一桌面时,应先确认当前由谁启动节点、谁发送目标,避免重复启动或同时控制车辆。

9.2 RDP登录与Windows安全提示

以下两个提示来自 Windows 对 .rdp 文件和 xrdp 自签名证书的安全检查。只有在确认小车 IP、网络环境和设备归属后,才应继续连接;在公共网络或地址不匹配时应取消。

图 9-2 Windows 提示远程连接发布者未知
图 9-2 Windows 提示远程连接发布者未知
  • 核对“远程计算机”是否为小车当前 IP,例如 192.168.0.242。
  • 确认处于受控实验网络,并且该 .rdp 文件来自项目维护者。
  • 通常不需要勾选智能卡或 WebAuthn;确认无误后点击“连接”。
图 9-3 xrdp 自签名证书与主机名提示
图 9-3 xrdp 自签名证书与主机名提示
证书提示如何判断 提示中的请求地址应是小车 IP,证书名称通常为 agilex-desktop。该证书来自 xrdp 自签名配置,因此 Windows 会报告“证书上的服务器名错误”和“证书来自不受信任的证书验证机构”。仅在地址、设备和网络均确认可信时点击“是”;如不希望重复询问,可在首次验证后勾选“不再询问”。
  1. 在 xrdp 登录窗口输入用户名 agilex 和桌面密码。
  2. 如进入 Ubuntu 登录界面,再选择 agilex 并输入系统密码。
  3. 登录后保持桌面在线。关闭 RDP 窗口可能导致该桌面启动的图形程序退出。
  4. 确认能够看到任务栏、应用窗口和网络状态。
图 9-4 通过 RDP 打开 LIMO 桌面并运行 RViz2
图 9-4 通过 RDP 打开 LIMO 桌面并运行 RViz2

图 9-4 是连接成功的参照状态:窗口标题显示 AgileX共享桌面 - 192.168.0.242:3389,Ubuntu 桌面中的 RViz2 正在显示地图、激光和坐标信息。

9.3 SSH终端、图形显示与多设备分工

RDP 和 SSH 可以同时使用。RDP 显示桌面结果,SSH 执行命令并保留终端日志。新建 SSH 终端后先加载 ROS 2 和工作空间环境。

ssh agilex@192.168.0.242
source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
ros2 node list
ros2 topic list

如果通过 SSH 启动 rviz2、rqt 或机械臂滑块等图形程序,先保持 RDP 桌面在线,再在当前 SSH 终端执行以下四行:

多台车或多台电脑接入同一网络时,ROS 2 默认的 ROS_DOMAIN_ID 都是 0,会互相收到对方的话题(包括 /cmd_vel)。多设备同时实验前,先约定一个私有 domain 并在所有设备上设成相同的值:export ROS_DOMAIN_ID=42,写入 ~/.bashrc 后重新打开终端生效。

# 先确认 display 号:ls /tmp/.X11-unix 里是 X0 还是 X1,下面以 :0 为例
export DISPLAY=:0
export XAUTHORITY=/run/user/1000/gdm/Xauthority
export XDG_RUNTIME_DIR=/run/user/1000
rviz2
通道最适合的任务结果显示位置
RDP 共享桌面查看桌面、RViz2、rqt、滑块和地图Windows 远程桌面窗口
SSH 终端运行 ros2 命令、查看日志、传输文件SSH 终端
RDP + SSH一人观察界面、一人执行命令并协同排障桌面与终端同时使用
设备建议分工注意事项
电脑 ARDP 查看 RViz2、地图和 GUI避免与其他设备重复点击导航目标
电脑 BSSH 启动节点、查看日志每个新终端都要 source 环境
电脑 CRDP 观察或记录实验结果共用桌面时不要争抢同一窗口操作
现场人员观察车辆、急停和物理边界远程操作不能替代现场安全值守
多设备操作规则 多台设备可同时连接,但同一实验只保留一个导航目标发布者、一个速度控制源和一份日志记录。开始行驶前由现场负责人确认控制权归属,结束后统一停车并关闭所有节点。

9.4 常见连接问题与日常维护

现象优先检查处理
RDP 无法连接同网段、IP 变化、3389 服务ping 小车地址;用 hostname -I 核对新 IP
出现发布者警告远程计算机地址和 .rdp 来源仅在可信实验网络确认后点击连接
证书名称不匹配请求 IP 与证书名确认地址和 agilex-desktop 均正确后再继续
SSH 无图形窗口RDP 是否在线、DISPLAY/XAUTHORITY保持 RDP 在线并在当前 SSH 终端重新 export
多设备操作冲突是否重复启动节点或点击目标明确一名主操作者,其余设备只观察
周期检查项目标准
每次实验前网络、电量、轮胎、相机与雷达连接稳定,无松动、无遮挡
每次实验后停止节点、备份地图与日志后台无残留进程,关键数据已备份
每周USB/CAN 线缆、侧门、散热和磁盘无破损,温度与空间正常
长期存放电池约 50% 电量并分离定期补电,避免过放
Chapter 10

第10章 SenseVoice语音识别与运动控制(选配)

本车 ROS 2 语音链路采用 SenseVoice-Small 离线模型、Sherpa-ONNX 推理、SoX 噪声处理和 ROS 2 节点。识别文本发布到 /voice/text,运动节点再把固定命令词转换为 /cmd_vel。

10.1 SenseVoice模型与系统部署

项目本机配置作用
识别模型SenseVoice-Small INT8 ONNX中文、英文等离线语音识别
模型日期2024-07-17中英日韩粤多语种版本
模型大小约 229 MB适合 Jetson 本地持续运行
推理框架Sherpa-ONNX 2.0.1ARM64 CPU 离线推理
语音前端arecord + SoX16 kHz 单声道录音、降噪和归一化
ROS 2 输出/voice/text发布识别文字
运动输出/cmd_vel由独立运动节点发布

选择 SenseVoice-Small 的原因是:相对大型云端 ASR 或 1B 以上模型,它更轻量、启动快,能够完全离线运行,同时支持中文和英文指令;对语音控制而言,固定命令词和短句识别比长篇连续转写更重要。FireRedASR、Qwen3-ASR 等更高精度方案需要更大的模型与计算资源,适合作为后续高性能版本,而不是当前 Jetson 实时控制的首要部署。

资源路径说明
模型文件~/limo_voice_test/models/sense-voice/model.int8.onnxINT8 ONNX 模型
词表文件~/limo_voice_test/models/sense-voice/tokens.txt模型 token 映射
Python 环境~/limo_voice_env安装 sherpa-onnx 与语音依赖
识别节点~/limo_voice_test/limo_voice_asr_sensevoice.py录音、降噪、识别并发布文本
运动节点~/limo_voice_test/limo_voice_command_node.py解析文本并发布受限速度

如重新部署 Python 环境,在虚拟环境中安装 Sherpa-ONNX:

source ~/limo_voice_env/bin/activate
python -m pip install sherpa-onnx
python -c "import sherpa_onnx; print(sherpa_onnx.__version__)"
模型离线运行 完成模型和依赖安装后,ASR、噪声处理与 ROS 2 消息发布均不需要联网。模型文件路径和 tokens.txt 必须同时存在,移动节点或重新部署时应整体复制。

10.2 语音转文字启动与验证

终端用途保持状态
终端 A启动 SenseVoice 识别节点持续运行,周期性录音
终端 B查看 /voice/text持续查看识别结果
终端 C运动控制节点先关闭运动权限验证,再开启
终端 D底盘驱动语音运动测试时启动
source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
source ~/limo_voice_env/bin/activate

python ~/limo_voice_test/limo_voice_asr_sensevoice.py \
  --ros-args \
  -p device:=plughw:0,0 \
  -p duration_sec:=4 \
  -p interval_sec:=6.0

启动后先加载模型,终端显示 SenseVoice-Small model ready。随后每一轮先保持安静约 0.5 秒,再说一条短命令。录音结束后节点自动执行 SoX 降噪、SenseVoice 推理并发布 /voice/text。

source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
ros2 topic echo /voice/text
中文命令English command预期结果
前进forward/voice/text 输出前进命令
后退back输出后退命令
左转left输出左转命令
右转right输出右转命令
停止stop输出停车命令
指标原始录音SoX预处理后
峰值电平-22.6 dBFS-3.0 dBFS
RMS电平-40.2 dBFS-17.0 dBFS
4 kHz以上能量占比35.36%0.08%
削波样本0

上表来自本车 USB 麦克风实测,说明 SoX 处理主要降低了高频噪声并提升了有效语音电平。最新处理后录音位于 /tmp/limo_voice_clean.wav,原始录音位于 /tmp/limo_voice_raw.wav,可用 aplay 试听。

10.3 语音控制运动实验

先把 APP 切换到指令模式,并停止其他 /cmd_vel 发布节点。运动节点默认关闭运动权限,用于先验证文本解析;确认后再把 enable_motion 设为 true。

# 终端 D:标准底盘与雷达
source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
ros2 launch limo_bringup limo_start.launch.py

# 终端 C:先禁止运动,验证文本解析
source ~/limo_voice_env/bin/activate
python ~/limo_voice_test/limo_voice_command_node.py \
  --ros-args -p enable_motion:=false -p odom_topic:=/odom

确认 /voice/text 能收到命令后,停止终端 C 并以低速重新启动。标准 limo_start 链路的前进和后退使用 /odom 累计里程,每次目标默认 1 米;若使用 limo_start_ekf.launch.py,应把里程计主题设为/odometry/filtered。达到目标后运动节点自动停车。

里程计选择:标准 limo_start.launch.py 链路使用 /odom;limo_start_ekf.launch.py 链路使用 /odometry/filtered。请根据实际启动链路设置 odom_topic 参数。

python ~/limo_voice_test/limo_voice_command_node.py \
  --ros-args \
  -p enable_motion:=true \
  -p odom_topic:=/odom \
  -p linear_speed:=0.10 \
  -p backward_speed:=0.08 \
  -p angular_speed:=0.25 \
  -p pulse_sec:=0.7 \
  -p forward_distance_m:=1.0 \
  -p backward_distance_m:=1.0 \
  -p max_travel_sec:=20.0
语音文本运动行为停止机制
前进 / forward以 0.10 m/s 前进,按里程累计 1 m达到 1 m 或 20 s 超时停车
后退 / back以 0.08 m/s 后退,按里程累计 1 m达到 1 m 或 20 s 超时停车
左转 / left以 0.25 rad/s 左转0.7 s 后自动停车
右转 / right以 0.25 rad/s 右转0.7 s 后自动停车
停止 / stop立即输出零速度无需等待计时结束
其他文本不产生运动保持零速度
语音运动安全边界 首次测试使用架空车轮;落地测试时前方至少保留 2 m 空间。只允许一个节点发布 /cmd_vel,不得同时使用 APP 摇杆、Nav2、巡线或键盘遥控。odom 中断、未知命令、节点退出或超过最大行驶时间时,运动节点必须持续发布零速度。现场人员应保留立即断电能力。

开始实验前用 ros2 topic info /cmd_vel --verbose 检查速度发布者,并用 ros2 topic echo /odom 确认里程计持续更新。使用 EKF 时应检查 /odometry/filtered。标准 limo_base 链路使用 /odom。前进方向异常时先检查底盘模态与电机配置,不要仅靠反向命令长期替代正确配置。

10.4 故障排查与验收

现象优先检查处理
ModuleNotFoundError虚拟环境是否激活source ~/limo_voice_env/bin/activate
模型加载失败模型与 tokens 路径检查 model.int8.onnx 和 tokens.txt
没有识别文本麦克风设备、录音电平和降噪结果aplay /tmp/limo_voice_clean.wav
识别词不准确说话距离、环境噪声、命令词缩短命令,靠近麦克风,坚持固定词表
有文字但不运动enable_motion 与 /cmd_vel先设 enable_motion:=true
按1米目标不准确轮式里程计与打滑检查 /odom;在防滑地面复测
同时运行就乱动多个速度发布者关闭 APP、Nav2、巡线或其他遥控节点
转动方向相反角速度符号增加 -p invert_angular:=true
验收标准 中文和英文固定命令都能稳定进入 /voice/text;一次前进或后退的目标距离约 1 m 且自动停车;停止命令立即生效;未知文本、里程计中断和节点退出均不会维持运动;多设备查看时只有一个速度控制源。
Chapter 11

第11章 MyCobot 机械臂控制(选配)

MyCobot 280 M5 通过六个关节实现抓取和姿态控制,可采用关节角 API、图形滑块、键盘、模型跟随与 MoveIt 2 等方式。标准 LIMO 未安装机械臂时,本章作为选配扩展参考;执行真实机械臂命令前必须确认本机已安装对应硬件和软件包。

项目参数项目参数
自由度6有效负载250 g
工作半径280 mm重复定位精度约 0.5 mm
机械臂自重约 800 g输入电源12 V / 5 A
通信USB Type-C工作温度-5 至 45 摄氏度

11.1 连接与工作空间检查

source /opt/ros/humble/setup.bash
source ~/agilex_ws/install/setup.bash
ls -l /dev/ttyACM*
groups
ros2 pkg list | grep -E 'mycobot|moveit|cobot'
检查项通过标准处理
USB 设备出现稳定 ttyACM 端口重新插拔,禁止使用频繁变化的端口
串口权限当前用户属于 dialout重新登录使权限生效
姿态关节无顶死,线缆无拉扯先人工调整至安全姿态
供电12 V / 5 A 稳定不要在带载运动中热插拔
工作空间抓取目标在可达半径内避免碰撞车身或相机

11.2 MoveIt 2 仿真预检查

ros2 launch mycobot_280_moveit2 demo.launch.py   # RViz2 会随 demo 一起启动

本机 MoveIt 2 demo 使用 ros2_control 的 mock_components 假硬件控制器,只验证 URDF、关节名称、Planning Group 和碰撞模型,不会驱动真实机械臂。先在仿真中确认关节方向、限位和末端工作空间,再进行真实硬件检查。

11.3 真实机械臂滑块控制

该 launch 直接连接 /dev/ttyACM0,并已包含 slider_control 节点,不能再次执行 ros2 run mycobot_280 slider_control。首次运动应清空 280 mm 工作半径并小角度操作。

ros2 launch mycobot_280 slider_control.launch.py \
  port:=/dev/ttyACM0 baud:=115200
快速拖动风险 真实机械臂会跟随滑块目标运动。首次拖动采用小角度逐步执行,不要在连接真实机械臂后突然将模型关节拖到远端。

11.4 模型跟随真实机械臂

mycobot_follow.launch.py 已包含 follow_display 节点,不需要再次 ros2 run 启动。

ros2 launch mycobot_280 mycobot_follow.launch.py \
  port:=/dev/ttyACM0 baud:=115200

启动后缓慢手动掰动机械臂,RViz2 模型应同步变化。若关节方向相反或延迟很大,停止拖动并检查机械臂固件、波特率和关节方向配置。

11.5 GUI 与键盘控制

# 默认只读观察;确认工作空间后再显式允许运动
ros2 launch mycobot_280 simple_gui.launch.py enable_motion:=false
ros2 launch mycobot_280 simple_gui.launch.py enable_motion:=true

# 键盘控制
ros2 launch mycobot_280 teleop_keyboard.launch.py \
  port:=/dev/ttyACM0 baud:=115200
ros2 run mycobot_280 teleop_keyboard

simple_gui 默认 enable_motion=false,只用于观察;确认机械臂工作空间和限位后,才能显式设置为 true。键盘控制在 teleop launch 提供服务后再运行 teleop_keyboard。首次运动应使用低步长并保持断电能力。

11.6 MoveIt 2 仿真规划

本机 MoveIt 2 demo 使用 mock_components 假硬件,适合验证 URDF、Planning Group、轨迹规划和碰撞模型,不会直接驱动真实机械臂。仿真规划成功也不代表现场无碰撞,执行真实硬件前仍需检查夹爪、线缆、相机和车身模型。

ros2 launch mycobot_280_moveit2 demo.launch.py
图 11-1 MoveIt 2 MotionPlanning 面板与 MyCobot 280 规划场景
图 11-1 MoveIt 2 MotionPlanning 面板与 MyCobot 280 规划场景

图为 MoveIt 2 的 MotionPlanning 面板与 MyCobot 280 模型:Displays 中 MotionPlanning 与 Global Status 均为 Ok,Planning Group 为 arm_group,Start State 与 Goal State 都是 <current>;窗口标题显示本机使用的配置文件是 mycobot_280_moveit2/share/mycobot_280_moveit2/config/moveit.rviz。

先看三处判断环境是否就绪:面板 Status 是否 Ok、末端标记是否落在 280 mm 工作半径内(不要穿到桌面、车身或相机)、Velocity 与 Accel Scaling 是否为小值(示例为 0.10,与本节“低速执行”的要求一致)。判据是“先 Plan 出轨迹再 Execute”:未规划时 Execute 按钮为灰色,执行过程中关节应连续、无线缆拉扯、无碰撞告警。

面板显示正常不等于现场安全:碰撞模型只覆盖 URDF 里的连杆,夹爪线缆、相机支架和车身并不在其中,执行前仍需人工目视确认工作空间。

步骤在 MoveIt 2 中完成的操作通过标准
加载模型确认 URDF 和关节名称模型与真实机械臂结构一致
设置目标拖动末端标记到目标位姿目标在工作空间内
步骤在 MoveIt 2 中完成的操作通过标准
规划检查轨迹是否避开车身路径连续、碰撞模型正确
执行低速执行并观察真实机械臂无碰撞、无拉扯、关节不越限

11.7 移动抓取

移动抓取把 Nav2 导航与机械臂抓取组合:车辆先到达抓取点,再调用机械臂轨迹,最后离开抓取区域。实现时应把导航入口统一为 Nav2,并核对任务脚本中的坐标、坐标框架和抓取姿态。

1.在目标场地完成建图和 Nav2 导航测试。

2.在 RViz2 中记录抓取点和离开点,确认坐标与朝向。

3.将目标点、机械臂抓取姿态和等待时间写入任务脚本。

4.先空载运行,验证到达、停车、抓取和退出顺序。

5.再放置轻质目标进行低速抓取,现场人员保持急停能力。

兼容入口默认行为是配置检查,不会直接执行移动抓取。必须先修复配置中的 missing 项并得到 ready: true,再显式传入 --execute。

ros2 launch limo_bringup limo_start.launch.py
ros2 launch limo_bringup limo_nav2_diff.launch.py

cd /home/agilex/agilex_ws/src/set_nav_point
# 1. 仅检查导航点、抓取点和机械臂姿态配置
python3 more_task_node.py --check

# 2. 只有检查结果为 ready: true 后才执行任务
python3 more_task_node.py --execute
抓取顺序 必须先停车再执行机械臂,避免底盘运动与机械臂同时动作。脚本最终版本应包含导航失败、抓取失败和超时的停车/复位分支。
Appendix

附录 A 整车三视图与外形尺寸

整车外形尺寸为 322 x 220 x 251 mm。下图为整车三视图,用于布置实验场地、检查箱体尺寸和确认传感器突出部位。选配机械臂、升降杆或线缆会增加实际占用空间。

图 A-1 LIMO 正视图、侧视图与俯视图
图 A-1 LIMO 正视图、侧视图与俯视图
尺寸项数值使用说明
长度322 mm不含外接线缆和完全展开的侧门
宽度220 mm安装麦克纳姆轮或履带后复核实际占地
高度251 mm雷达、天线和选配模块可能导致高度增加
轴距200 mm运动学计算和控制器参数的基础量
轮距175 mm差速与麦克纳姆速度分配的基础量
Appendix

附录 B 基本操作与常用命令

B.1 Linux 基本操作

操作命令示例
查看当前位置pwd
切换目录cdcd ~/agilex_ws
返回上级cd ..cd ../src
查看文件ls / ls -lals -la ~/.ros
创建目录mkdir -pmkdir -p ~/agilex_ws/src
复制 / 移动cp / mvcp map01.yaml backup/
终止程序Ctrl+C停止 launch 或视觉节点
显示隐藏文件Ctrl+H文件管理器显示 .ros

B.2 ROS 2 编译和工作空间

任务命令
加载 ROS 2source /opt/ros/humble/setup.bash
加载本机工作空间source ~/agilex_ws/install/setup.bash
编译整个工作空间cd ~/agilex_ws && colcon build --symlink-install
编译单个包colcon build --packages-select limo_base
创建 Python 包ros2 pkg create learning_limo --build-type ament_python --dependencies rclpy
启动 launchros2 launch package launch_file.launch.py
运行节点ros2 run package executable

B.3 本机常用任务

任务命令
加载环境source /opt/ros/humble/setup.bashsource ~/agilex_ws/install/setup.bash
启动底盘ros2 launch limo_base limo_base.launch.py
启动底盘与雷达ros2 launch limo_bringup limo_start.launch.py
单独启动雷达ros2 launch ydlidar_ros2_driver ydlidar.launch.py
查看激光数据ros2 topic echo /scan --once
查看底盘状态ros2 topic echo /limo_status --once
发布停车速度ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.0}, angular: {z: 0.0}}"
任务命令
Cartographerros2 launch limo_bringup limo_cartographer.launch.py
保存地图ros2 run nav2_map_server map_saver_cli -f map01
差速/全向导航ros2 launch limo_bringup limo_nav2_diff.launch.py
阿克曼导航ros2 launch limo_bringup limo_nav2_ackermann.launch.py
启动相机ros2 launch orbbec_camera dabai.launch.py
RTAB-Map 建图ros2 launch limo_bringup limo_rtab_rgbd.launch.py
RTAB-Map 定位ros2 launch limo_bringup limo_rtab_rgbd.launch.py localization:=true
RTAB-Map 导航ros2 launch limo_bringup limo_rtab_nav2.launch.py

B.4 常用路径

内容路径
底盘驱动~/agilex_ws/src/limo_ros2/limo_base
消息与服务~/agilex_ws/src/limo_ros2/limo_msgs
建图与导航入口~/agilex_ws/src/limo_ros2/limo_bringup/launch
地图目录~/agilex_ws/src/limo_ros2/limo_bringup/maps
视觉脚本/home/agilex/agilex_ws/src/limo_visions/scripts
RTAB-Map 数据库~/.ros/rtabmap.db
路径核对 不同镜像的包名或目录可能略有差异。使用 tab 补全、ros2 pkg prefix 和 find 核对实际路径,不要为了匹配示例而修改系统目录。

B.5 查看本机版本

报障、核对资料或准备重装镜像前,先用下面四条命令确认本机版本,并把输出一起保存:

head -2 /etc/os-release                              # 系统版本:Ubuntu 22.04.5 LTS
head -1 /etc/nv_tegra_release                        # JetPack:R36.4.3
echo $ROS_DISTRO                                     # ROS 版本:humble
git -C ~/agilex_ws/src/limo_ros2 log -1 --oneline    # 驱动源码版本

不同批次的镜像可能使用不同版本的驱动源码,实际版本以本机输出为准。

Appendix

附录 C ROS 2 系统架构

ROS 2 系统按操作系统、通信中间层和应用层分层。本机使用 ROS 2 Humble,节点发现依赖 DDS,不再需要单独启动 ROS Master。

层级ROS 2 Humble 对应
操作系统Ubuntu 22.04 + ROS 2 Humble
通信DDS、ROS 2 话题/服务/动作
节点发现DDS 自动发现,无中心节点
工作空间colcon 工作空间 + colcon build
启动.launch.py Python 配置
可视化rviz2、rqt_graph、rqt_image_view

C.1 计算图核心概念

概念含义本车示例
节点 Node执行一项功能的进程limo_base、Nav2、相机驱动、视觉节点
消息 Message有严格数据结构的数据Twist、LaserScan、Image、Odometry
话题 Topic多对多的异步发布/订阅/cmd_vel、/scan、/imu
服务 Service请求-应答的同步调用保存地图、坐标变换查询
动作 Action带目标、反馈、结果的长任务导航到目标点、机械臂轨迹
参数 Parameter节点运行时配置速度限制、地图路径、AMCL 粒子数
TF2随时间变化的坐标树map -> odom -> base_link -> sensor

C.2 文件系统

组成作用
Package 功能包节点、库、launch、参数和执行文件的基本单元
package.xml声明包名、版本、依赖和维护信息
CMakeLists.txtC/C++ 包或消息接口包的构建规则
setup.py / setup.cfgPython 包的安装与入口点
msg / srv / action自定义通信接口
launch一次启动多个节点并加载参数
config / paramYAML 参数与算法配置

C.3 话题、服务、动作和参数的选择

需求推荐机制原因
持续发布速度、激光、图像、状态话题高频、异步、可多订阅者
保存地图、查询一次性结果服务需要明确请求和应答
导航、抓取、长时运动动作需要进度反馈和可取消能力
调整限速、地图和算法阈值参数启动期或运行期配置
Appendix

附录 D ROS 2 工作空间与开发基础

D.1 工作空间结构

~/dev_ws/
  src/       # 功能包源代码
  build/     # 编译中间文件
  install/   # 编译后的安装空间
  log/       # 编译日志
source /opt/ros/humble/setup.bash
cd ~/dev_ws
colcon build --symlink-install
source install/setup.bash

每个新终端都要加载 ROS 2 和工作空间环境。安装空间不是源代码目录,修改 src 后必须重新 colconbuild,或使用 --symlink-install 支持部分 Python 和资源文件的软链接更新。

D.2 创建功能包

cd ~/dev_ws/src
ros2 pkg create learning_limo \
  --build-type ament_python \
  --dependencies rclpy std_msgs geometry_msgs
cd ~/dev_ws
colcon build --packages-select learning_limo
source install/setup.bash

创建 talker.py 与可执行入口

上一步创建的 Python 包还需要添加实际节点代码,并在 setup.py 注册 talker 入口,否则 ros2 run 和 launch.py 都找不到该可执行文件。

# 文件:~/dev_ws/src/learning_limo/learning_limo/talker.py
import rclpy
from rclpy.node import Node
from std_msgs.msg import String

class Talker(Node):
    def __init__(self):
        super().__init__('learning_talker')
        self.publisher = self.create_publisher(
            String, '/learning_topic', 10)
        self.create_timer(1.0, self.publish_message)
        self.count = 0

    def publish_message(self):
        self.count += 1
        self.publisher.publish(
            String(data=f'Hello LIMO {self.count}'))

def main():
    rclpy.init()
    node = Talker()
    try:
        rclpy.spin(node)
    except KeyboardInterrupt:
        pass
    finally:
        node.destroy_node()
        rclpy.shutdown()

if __name__ == '__main__':
    main()

在自动生成的 setup.py 中设置 console_scripts 入口:

entry_points={
    'console_scripts': [
        'talker = learning_limo.talker:main',
    ],
}

保存后回到 ~/dev_ws 执行 colcon build --packages-select learning_limo,再加载 install/setup.bash。之后 ros2 run learning_limo talker 才能启动。

D.3 编写 launch.py

from launch import LaunchDescription
from launch.actions import IncludeLaunchDescription
from launch.launch_description_sources import PythonLaunchDescriptionSource
from launch_ros.actions import Node
from ament_index_python.packages import get_package_share_directory
def generate_launch_description():
    return LaunchDescription([
        Node(
            package='learning_limo',
            executable='talker',
            output='screen',
            parameters=[{'use_sim_time': False}],
        ),
    ])

D.4 RViz2 与 rqt 调试

rviz2
rqt_graph
rqt_image_view
ros2 run tf2_tools view_frames
# TF 树(首次使用前先安装)
sudo apt install ros-humble-rqt-tf-tree
ros2 run rqt_tf_tree rqt_tf_tree
工具用途典型检查
rviz2三维显示TF、激光、地图、机器人模型、导航目标
rqt_graph节点关系图谁发布 /cmd_vel,谁订阅 /scan
rqt_image_view相机图像RGB、Depth 话题是否存在
tf2_tools view_frames生成 TF 树 PDFmap、odom、base_link 是否完整连接

D.5 最小开发闭环

一个可复现的 LIMO ROS 2 开发闭环应至少包含:加载环境、启动底盘、验证状态、发布短时命令、接续算法和停止清理。下面的顺序适合新建任何视觉、运动学或导航实验。

1.在一个终端启动底盘或组合 launch,并确认没有重复进程。

2.在第二个终端使用 ros2 topic list、ros2 topic hz 和 ros2 topic echo 检查输入输出。

3.运行自写节点,先只打印数据,不发布速度。

4.接管 /cmd_vel 后设置低速和停车超时,再进行闭环实验。

5.保存 launch、YAML、日志和地图,按 Ctrl+C 停止全部节点。

ros2 launch limo_base limo_base.launch.py
ros2 node list
ros2 topic list
ros2 topic hz /scan
ros2 run learning_limo talker
Appendix

附录 E 系统镜像烧录

烧录前确认 先确认本机使用 microSD、eMMC 还是 NVMe 启动,并记录当前系统备份和网络配置。Jetson 型号、存储介质和镜像版本不匹配会造成无法启动或驱动缺失。

E.1 获取正确镜像

1.从设备供应商或官方资料获取与 Jetson Orin Nano、Ubuntu 22.04 和 LIMO 驱动匹配的镜像。

2.核对镜像 SHA256 或发布说明,避免下载不完整或把旧 Jetson Nano 镜像用于 Orin Nano。

3.备份工作空间、地图、RTAB-Map 数据库、标定文件和课程资料。

4.准备稳定电源、读卡器或 USB 数据线和足够的存储空间。

E.2 microSD 卡烧录

步骤操作检查
1安装 balenaEtcher从 https://etcher.balena.io/ 获取对应版本
2选择官方镜像文件确认文件类型和大小
3选择目标存储卡只选正确的可移动设备,避免擦除电脑硬盘
4执行 Flash 并校验等待写入和 Verify 完成
5安全弹出后插入 Jetson首次启动连接显示器或串口

E.3 eMMC/NVMe 或开发板模式

若配置使用 eMMC 或 NVMe,使用 NVIDIA SDK Manager 或供应商提供的恢复模式流程。不同载板和模块的按键与 USB 接口不同,必须按对应硬件说明进入恢复模式,不能照搬旧版 Nano 的通用步骤。

E.4 首次启动检查

source /opt/ros/humble/setup.bash
printenv ROS_DISTRO
ros2 pkg list | grep -E 'limo|ydlidar|orbbec|nav2'
ls -l ~/agilex_ws
Appendix

附录 F 底盘固件升级

底盘固件升级用于修复通信、运动控制或保护逻辑。固件版本必须与本机的底盘硬件和 ROS 2 镜像匹配,不要使用其他型号或其他批次的固件。升级期间保持电源稳定,不得移动车辆。

1.记录当前固件版本、底盘型号和报错现象,关闭所有 ROS 2 和 APP 控制。

2.从官方渠道获取对应的升级软件和固件文件,核对型号与版本。

3.在关机状态下按设备说明进入固件升级模式,等待计算单元正常启动。

4.打开升级工具,选择正确的串口和固件文件。

5.执行升级并等待完成,不要拔电源或关闭串口。

6.升级成功后关闭串口,重新上电,检查底盘状态、模式灯和 /limo_status。

固件升级工具通常在 Windows 个人电脑上运行,不在车上执行。使用前核对工具版本、目标串口和固件文件,并按发布说明完成升级;不要照搬 Linux 串口或 chmod 命令。

检查项正确结果
串口选择底盘实际端口,不与雷达或机械臂串口混用
固件文件型号、版本号与发布说明匹配
进度升级过程持续供电,工具无超时
升级后状态模式灯正常,/limo_status 能持续发布
Appendix

附录 G 建图与导航参数配置

ROS 2 Humble 采用 Nav2 生命周期节点和 YAML 参数文件;不同镜像版本的参数名与插件机制可能不同。本节保留调参逻辑和参考值,具体键名必须在本机 YAML 中核对。

find ~/agilex_ws/src/limo_ros2/limo_bringup -type f \
  \( -name '*.yaml' -o -name '*.lua' -o -name '*.launch.py' \) | sort

G.1 GMapping 参数

参数概念参考值作用
particles30粒子数量,越大越稳定但更耗 CPU
delta0.05栅格分辨率,单位 m
linearUpdate1.0平移超过该距离处理一次扫描
angularUpdate0.5旋转超过该角度处理一次扫描
maxRange按雷达有效距离限制参与建图的最远激光
minimumScore0.0扫描匹配最低分数,过低易产生错误匹配
resampleThreshold0.5基于有效粒子数的重采样阈值

G.2 Cartographer 参数

参数常见配置说明
map_framemap地图父坐标系
tracking_framebase_link 或 IMU frame实际追踪坐标系
published_frameodom 或 base_link发布位姿的父坐标系
provide_odom_frametrue是否由 Cartographer 发布 odom
use_odometrytrue/false是否融合轮式里程计
num_laser_scans1本配置使用单台二维雷达
lookup_transform_timeout_sec0.2TF 查询超时
submap_publish_period_sec0.3子图发布周期

G.3 Nav2 定位与局部控制

参数组关注项调参建议
AMCLmin/max_particles、误差、更新距离粒子过少会丢定位,过多会增加计算负载
Controllermax_vel_x、max_vel_theta、加速度先降速,再调角速度与加速度
Goal tolerancexy_goal_tolerance、yaw_goal_tolerance按场地精度调和停车行为
Costmap inflationinflation_radius保证车身与行人安全距离
Plannerplanner plugin、路径代价先确认地图正确,再改路径偏好
Recovery旋转、后退、等待行为狭小场地应减少后退与大幅旋转
参数修改原则 一次只改变一组参数,保留修改前版本并记录效果。地图、TF、传感器话题异常时,不要通过增大速度或放宽碰撞约束来掩盖问题。
Appendix

附录 H 配套课程与资料

配套课程与资料随版本更新,建议以官方渠道提供的最新版本为准。学习时应重点掌握机器人结构、运动学、传感器原理与算法思路;具体命令、工作空间、launch 文件与导航包以本手册的 ROS 2 写法为准。

学习模块建议练习本手册对应章节
产品与底盘模式切换、电池充电、APP 低速控制第 1-2 章
驱动与通信话题检查、Twist 控制、状态订阅第 3 章
运动学差速、阿克曼、麦克纳姆速度验证第 4 章
激光与导航建图、初始位姿、单点与多点导航第 5-6 章
视觉与融合RTAB-Map、文字、颜色、巡线与 YOLO第 7-8 章
语音与机械臂录音识别、模型跟随、MoveIt 2 与移动抓取第 10-11 章

课程资料、镜像、固件和示例包可能随版本更新。下载时应记录版本号与发布日期,先备份现有系统,再替换整机镜像;不要把旧版软件包直接复制进 ROS 2 工作空间。

Appendix

附录 I 故障排查

现象优先检查处理
上电无反应、电量表不亮电池是否插到位、电量是否耗尽重新插紧输出接口;充电后再试
发 /cmd_vel 车辆不动APP/遥控是否切到 ROS 2 指令模式、/odom 数值是否冻结底盘 MCU 挂死:整车断电重上电;再确认 APP 或遥控器未抢控制
蜂鸣器长鸣遥控器或 APP 是否断开失联报警:重新连接或断开后按开关键;软件层关不掉,需保持连接或物理处理
终端反复刷 Invalid frame! Check sum failed是否有多个进程同时读底盘串口sudo fuser -v /dev/ttyTHS1 只保留一个 limo_base;串口波特率 460800
RViz2 里看不到 /scan 点云/scan 的 QoS 是否匹配把 LaserScan 的 Reliability Policy 改为 Best Effort(默认 Reliable 收不到)
SSH 里 rviz2 起不来或报 cannot open displayDISPLAY / XAUTHORITY 是否设置、车上是否已有桌面会话按 9.2 设置环境变量;先在车上或远程桌面登录一次
多台车同网时互相干扰、车自己动ROS_DOMAIN_ID 是否相同(默认都是 0)所有设备设成同一个私有 domain,见 9.1
ros2 launch 找不到包是否 source 了 ROS 与工作空间重新加载 setup.bash,核对包名
雷达无 /scanUSB、串口占用、驱动日志关闭重复驱动后重新连接雷达
相机无图像USB 带宽、相机占用、话题名移除冗余 USB 设备,只保留一个相机驱动
导航没有全局路径地图、初始位姿、目标点、代价地图重新设置位姿,确认目标点在可通行区域
定位粒子不收敛地图版本、起始位置、map→odom重新估计位姿,检查 TF 与地图是否对应
车辆原地摆动控制器参数、激光是否被遮挡降低速度与增益,检查雷达视野
磁盘写满、日志暴涨~/.ros 与日志目录清理旧 bag、地图备份与日志,保留必要数据

I.1 通用排查顺序

1.停止所有正在运行的相关节点,记录错误日志最后 20 行。

2.确认 ROS 环境和当前模态,查看 node、topic 与 status。

3.一次只启动一个功能入口,验证传感器和底盘后再叠加算法。

4.保留复现步骤、包版本、launch 文件和关键日志,便于进一步定位。

ros2 node list
ros2 topic list
ros2 topic hz /scan
ros2 topic echo /limo_status --once
ros2 pkg prefix limo_bringup
Appendix

附录 J 使用检查表与版本说明

J.1 收货验收(约 30 分钟)

新车拆箱后按顺序做一遍,任何一项不通过都先别急着做实验,按附录 I 排查或联系供应商。命令都在车上终端执行,需要先 source 工作空间。

检查项怎么做通过标准
外观与配件对照 1.2 表格清点;检查轮胎、雷达、相机、外壳与侧门无破损、无缺件、螺丝无松动
电池与接线取出电池看电量表或万用表,插紧黄色输出接口电压不低于 11.1 V,接口无松动
开机与电量表长按开关键开机,观察前置屏幕与电量表正常进入系统,无红灯报警
四种模态与车灯依次切换四轮差速/阿克曼/麦克纳姆,观察车灯车灯颜色与机械模态一致
雷达数据ros2 launch ydlidar_ros2_driver ydlidar.launch.py;再执行 ros2 topic hz /scan频率约 6 Hz,frame_id 为 laser_link
相机图像ros2 launch orbbec_camera dabai.launch.py;ros2 topic list | grep -E "color|depth"能看到彩色与深度话题
APP 遥控APP_Agilex 蓝牙连接,低速前进、后退、转向、停车方向正确,能正常停车
联网与登录按9.1-9.3连接局域网,并用RDP共享桌面或SSH登录能进入桌面或命令行
建图自检按 5.4 慢速走一小圈后保存地图生成 map.pgm 与 map.yaml,墙体闭合
关机顺序停车 → 停止节点 → 关闭 APP → 关机 → 断开电池无异常报错,电量表熄灭

J.2 每次实验前检查表

[ ] 电池电量充足,输出接口与充电接口连接正确

[ ] 轮胎、插销、履带或麦克纳姆轮与当前模式一致

[ ] LIMO 位于平整场地,行驶区无人和临时障碍

[ ] APP_Agilex 已连接,并在低速模式下完成方向测试

[ ] 终端已经 source ROS 2 Humble 与本机工作空间

[ ] 同一设备没有重复启动底盘、雷达或相机驱动

[ ] 已准备急停、断电人员和必要防护措施

J.3 内容校准说明

本手册内容以本机实机配置为基线(Jetson Orin Nano、Ubuntu 22.04、ROS 2 Humble),并结合实机验证结果整理。参数、界面与包名可能随镜像版本变化,实验前请以实机命令输出为准。

对于源资料中可能因版本更新而变化的内容,如插件名称、地图参数、相机话题和视觉脚本路径,本手册强调先在本机 launch/YAML/ROS 话题中核对。设备实际发行版本、校准参数与现场安全规范优先于示例文本。

J.4 修订记录

版本日期主要修改
1.1.32026.11重写 6.6 路径巡检操作,补充 YOLO 检测图,修复图 2-1、图号、固件升级说明和目录残留。
Appendix

附录 K 依赖包一览

本手册用到的 ROS 2 包和脚本分成两类:一类随镜像预装,照着命令就能跑;一类本机没有预装(或只在选配硬件上才有)。下表在 LIMO(Jetson Orin NX / Ubuntu 22.04 / ROS 2 Humble)上逐条核对过,遇到没有的按最后一列处理,不要硬套命令。

包 / 文件用途本机预装未预装时怎么办
limo_base / limo_bringup / limo_msgs底盘驱动、启动入口、消息定义是—
ydlidar_ros2_driverT-mini Pro 激光雷达是—
orbbec_cameraDabai 深度相机是—
limo_visions颜色、红绿灯、ArUco、文字识别与巡线节点是—
trt_yoloTensorRT 加速的 YOLO 检测是—
aruco_rosArUco 标记识别(8.7)是—
robot_localization + rf2o_laser_odometry抗打滑建图的 EKF 与激光里程计是按 5.5 增量包安装
mycobot_280 / mycobot_280_moveit2 / mycobot_280_moveit2_control机械臂滑块、跟随、MoveIt 2 与同步节点(11.x)是—
slam_gmapping / limo_gmapping.launch.pyGMapping 建图(5.2)否改用 Cartographer(5.3–5.4)
rrt_explorationRRT 自主探索(5.5)否用 Cartographer 建图 + Nav2 多点导航
agilex_pure_pursuit路径记录与复现(6.6)否用 Nav2 航点复现
detect_ros升降杆标记识别(8.5)否(选配硬件)未装升降杆就不执行
rqt_tf_treeTF 树可视化(D.4)否sudo apt install ros-humble-rqt-tf-tree
voice旧版语音包(第 10 章已改用 SenseVoice)否按第 10 章的 SenseVoice 流程
limo_path_patrol路径录制、CSV 校验与自动跟随当前资源包提供检查 launch 与服务;未安装时按 6.6 和附录 L 核对

下面这张表把手册里出现的启动命令与脚本按用途归到一起,方便按“我现在要做什么”反查;标注“随包提供”的脚本放在配套资源包的对应目录里,其余由镜像预装。

脚本 / 命令位置用途章节
limo_base.launch.pylimo_base启动底盘驱动:串口、/cmd_vel、/odom、/imu、/limo_status、TF3.4
limo_start.launch.pylimo_bringup底盘 + 雷达组合入口(已含 ydlidar)5.1、5.4、6.2
limo_cartographer.launch.pylimo_bringupCartographer 2D 建图,输出 /map 与 submap5.4
limo_nav2_diff / limo_nav2_ackermann.launch.pylimo_bringupNav2 导航(差速用 diff,阿克曼用 ackermann)6.2
limo_rtab_rgbd.launch.pylimo_bringupRTAB-Map RGB-D 建图,落库 ~/.ros/rtabmap.db7.2
limo_rtab_nav2.launch.pylimo_bringupRTAB-Map 定位 + Nav2 导航7.3
ros2 run limo_visions recognitionlimo_visions颜色识别,发布标注图 /image_hsv(不发 /ocr/result)8.3
ros2 run limo_visions object_detectlimo_visionsFollowLine 巡线节点:订阅 /camera/color/image_raw,发布 /image_hsv 与 /cmd_vel8.4
ros2 run limo_visions traffic_lightlimo_visions红绿灯识别,按 HSV 标 RED/YELLOW/GREEN8.8
ros2 run limo_visions move_to_arlimo_visionsArUco 跟随:对准标记并移动到设定距离8.7
limo_recognition_text_read.pylimo_visions/scripts(随包提供)文字识别:输出 /ocr/result 与 /ocr/image8.2
yolov8n_det.launch.pytrt_yoloTensorRT YOLOv8 检测(首次需 serialize)8.9
slider_control.launch.pymycobot_280滑块控制关节角(内置节点,参数 port/baud)11.2、11.3
mycobot_follow.launch.pymycobot_280模型跟随真机(内置 follow_display)11.4
simple_gui / teleop_keyboard.launch.pymycobot_280GUI 输入关节角、键盘控制末端11.5
mycobot_280_moveit2 demo.launch.pymycobot_280_moveit2MoveIt 2:mock_components 假硬件 + RViz2 规划面板11.2、11.6
ros2 run mycobot_280_moveit2_control sync_planmycobot_280_moveit2_control把规划结果同步到真实机械臂11.6
more_task_node.pyset_nav_point(随包提供)多点任务入口:导航到点后调用机械臂抓取11.7
limo_voice_asr_sensevoice.py~/limo_voice_test(随包提供)SenseVoice 语音转文字,发布 /voice/text10.2
limo_voice_command_node.py~/limo_voice_test(随包提供)把 /voice/text 转成 /cmd_vel 运动命令10.3
tf_pub.pylimo_base/scripts发布 base_link→laser_link 等静态 TF3.2
Appendix

附录 L 配套资源包使用说明

本手册正文引用了一部分不在系统镜像里的文件:Windows 远程桌面配置、SenseVoice 语音脚本与模型、抗打滑建图的 EKF 增量包、文字识别与多点任务脚本,以及本手册的 Word 版。它们统一放在配套资源包(随车 U 盘提供,同一份内容也会发布到项目仓库)里,下文说明包内结构、校验方法和部署步骤。

L.1 包里有什么

下表按目录列出内容与用法;“对应章节”列给出该文件在正文里的出处。

目录 / 文件内容怎么用对应章节
manual/本手册 Word 版直接打开;改版以此为准全文
rdp/AgileX共享桌面.rdpWindows 远程桌面连接配置拷到 Windows 双击;IP 变了右键“编辑”改“计算机”9.1–9.2
docs/Windows远程桌面连接LIMO小车教程.pdfRDP 图文教程(含黑屏、VNC error 排查)电脑上阅读9.2
docs/抗打滑建图_EKF融合里程计.mdEKF 融合里程计的完整说明电脑上阅读5.5
ekf/抗打滑建图增量包:install.sh、3 个 launch、3 个参数文件、rf2o 日志补丁在能 ssh 的电脑上执行 bash ekf/install.sh5.5
scripts/limo_recognition_text_read.py文字识别脚本拷到车上 limo_visions/scripts,再按 8.2 装 tesseract8.2
scripts/more_task_node.py多点任务入口拷到车上 set_nav_point/11.7
voice/limo_voice_asr_sensevoice.py录音 → SoX 降噪 → SenseVoice → /voice/text拷到车上 ~/limo_voice_test10.2
voice/limo_voice_command_node.py口令 → /cmd_vel同上,配合 10.3 使用10.3
voice/models/sense-voice/SenseVoice-Small 模型(229 MB,含 tokens.txt)整个目录拷到 ~/limo_voice_test/models/10.1
voice/noise.profSoX 噪声剖面拷到 ~/limo_voice_test10.2
docker/ROS 2 开发容器草案与说明见 docker/README.md附录 D

L.2 拿到包后先做三件事

1.校验完整性。解压后进入包目录执行 sha256sum -c SHA256SUMS(Windows 用 certutil -hashfile <文件> SHA256 逐个比对),输出 OK 才算完整;模型文件 229 MB,传输中断最容易坏在这里。

2.解压到电脑本地目录,不要在 U 盘或网络盘里直接运行脚本。

3.打开包内 README.md,确认这次要用的是哪几项,再按 L.3 部署。

L.3 部署到车上

(1)脚本类(8.2 文字识别、11.7 多点任务)。改好权限再运行:

scp scripts/limo_recognition_text_read.py agilex@<小车 IP>:/home/agilex/agilex_ws/src/limo_visions/scripts/
scp scripts/more_task_node.py agilex@<小车 IP>:/home/agilex/agilex_ws/src/set_nav_point/
ssh agilex@<小车 IP> "chmod +x ~/agilex_ws/src/limo_visions/scripts/*.py ~/agilex_ws/src/set_nav_point/*.py"

(2)抗打滑建图增量包(5.5)。在能 ssh 到车的电脑上执行,脚本会自动同步文件、编译 limo_bringup 并校验安装结果:

bash ekf/install.sh
# 启动(三选一,不要同时跑)
ros2 launch limo_bringup limo_start_ekf.launch.py
ros2 launch limo_bringup limo_cartographer_ekf.launch.py
ros2 launch limo_bringup limo_rtab_rgbd_ekf.launch.py

(3)语音模块(10.x)。先把脚本和模型放到车上,再建虚拟环境:

scp -r voice/*.py voice/models voice/noise.prof agilex@<小车 IP>:~/limo_voice_test/
ssh agilex@<小车 IP>
python3 -m venv ~/limo_voice_env && source ~/limo_voice_env/bin/activate
python -m pip install sherpa-onnx numpy     # SoX 用 sudo apt install sox
python ~/limo_voice_test/limo_voice_asr_sensevoice.py   # 另开终端看 /voice/text

(4)Windows 远程桌面(9.2)。把 rdp/AgileX共享桌面.rdp 拷到 Windows,双击即可;若提示无法连接,先在车上执行 hostname -I 确认 IP,再右键该文件“编辑”,把“计算机”改成新的 IP:3389。

L.4 常见问题

模型缺失或路径不对:报错里通常带 FileNotFoundError 或找不到 model.int8.onnx。确认 ~/limo_voice_test/models/sense-voice/ 下同时有 model.int8.onnx 与 tokens.txt,两个文件缺一不可。

仓库里拉不下模型:GitHub 单文件上限 100 MB,229 MB 的模型请用发布附件(Release)或 git lfs,最省事的是直接用随车 U 盘里的 zip。

ekf/install.sh 报 ssh 连接失败:先在电脑上确认 ssh agilex@<小车 IP> 能登录,且已 source 过 ROS 环境;脚本依赖这台电脑能直连小车。

脚本无法执行:scp 过去后补 chmod +x;用 python3 显式指定解释器也可以绕过执行位问题。