提示：
感知拓展套件SDK文档主要用于用户购买感知拓展套件（感知传感器包括激光雷达、深度相机）后，可通过该文档快速实现三维建图、重定位、导航以及避障等示例。

1 物料准备

1.1 硬件准备

1.2 开发环境

• 本文档内示例的代码基于Ubuntu 20.04操作系统、ROS1（noetic）版本开发，请提前准备好开发环境。

• 三维建图和重定位需要用到ros自带工具rviz用于查看地图、点云。您可以先下载准备好下方文件至本地。

  • Limx 建图的Rviz：📎 limx_mapping_rviz.rviz

  • Limx 重定位的Rviz：📎 localization_rviz

1.3 雷达、相机结构参数

雷达基于机器人本体Base（IMU）的结构参数

x：-0.00044m
y：0
z：0.1681m
角度：pitch旋转180°（刚好倒着）

相机基于机器本体Base的坐标和角度参数（共三档可调节角度）

角度①：
相对本体IMU坐标：x：0.1967；y：-0.0175；z：-0.03042
角度：138°（如图）


角度②：
相对本体IMU坐标：x：0.20542；y：-0.0175；z：-0.01965
角度：120°（如图）


角度③：
相对本体IMU坐标：x：0.21039；y：-0.0175；z：-0.00671
角度：102°（如图）

2 搭建环境

2.1 硬件搭建

拿到感知拓展套件后，先参照快速上手指南2025-0617 感知拓展套件 快速上手指南-单页-小A3.pdf将其安装至机器人扩展平台，将网线插入机器人网口，电源线插入机器人外接24V电压输出口，设备开机，等待约4秒后，开发板网口灯光亮起，雷达震动，表示套件已成功上电。

提示：

• 为保证用户开发过程中网络连接的通畅，我们推荐用户可以先将下图连接至TRON1本体的网线接入电脑、电脑连接无线网络（即拔出7号口网线，插入电脑有线网络端口）。否则在开发过程中电脑将无法连接外网。

提示：
注意：感知拓展套件安装时应遵循从TRON本体前方向后方送入滑轨的次序，否则将损坏滑轨及外壳。

2.2 开发板环境搭建

2.2.1 设置IP地址

提示：
**注意：**感知套件开发板出厂时设置的IP地址为：10.192.1.3。

将用户电脑IP地址与机器人、开发板IP地址保持在同一局域网内，即10.192.1.x。

2.2.2 终端SSH连接到开发板

当IP地址更新完成，且感知拓展套件已上电，将用户电脑连接机器人WiFi（密码；12345678），执行下指令进行环境搭建。

ssh guest@10.192.1.3    #密码：123456

2.2.3 开发板连接网络

若遇到下图中的报错，运行remove with中的代码后重新ssh连接即可。

安装环境时，开发板需连接网络，可通过用户电脑执行以下命令完成网络连接（该方法不适用隐藏的无线网络）。

ssh guest@10.192.1.3    #密码：123456    #上面终端未退出则不用在ssh
nmcli dev wifi list  
sudo nmcli dev wifi connect "wifi名称" password "密码" #wifi名称和密码需根据用户自行填写
#连接成功后，会显示 Device 'wlan0' successfully activated with “设备号”
ping www.baidu.com #执行百度可ping通

2.2.4 安装ROS Noetic

• **我们推荐在Ubuntu 20.04操作系统上建立基于ROS Noetic的算法开发环境。**ROS提供了一系列工具和库，如核心库、通信库和3D可视化工具（如rviz），极大地便利了机器人算法的开发、测试和部署。这些资源为用户提供了一个丰富而完整的算法开发环境。

安装方法一：官方安装方式

ROS Noetic 安装请参考文档：Ubuntu install of ROS Noetic，选择“ros-noetic-desktop-full”进行安装。

安装方法二：第三方脚本安装

如果采用官方安装方式不成功，可尝试采用第三方脚本安装。输入以下指令可进行一键安装。

wget http://fishros.com/install -O fishros && . fishros

详情可参考以下链接： “https://fishros.org.cn/forum/topic/20/%E5%B0%8F%E9%B1%BC%E7%9A%84%E4%B8%80%E9%94%AE%E5%AE%89%E8%A3%85%E7%B3%BB%E5%88%97”

• ROS Noetic安装完成后，采用以下指令验证是否安装完成：

roscore

• ROS Noetic 安装完成后，Bash终端输入以下Shell命令，安装开发环境所依赖的库，包括C++ >= 17, OpenMP >= 4.5, CMake >= 3.10.0, Eigen >= 3.2, Boost >= 1.54

sudo apt-get update
sudo apt install ros-noetic-map-server \
                 ros-noetic-octomap-ros \
                 ros-noetic-octomap-msgs \
                 ros-noetic-octomap-server \
                 ros-noetic-dwa-local-planner \
                 ros-noetic-octomap-rviz-plugins\
                 ros-noetic-move-base \
                 ros-noetic-pointcloud-to-laserscan \
                 ros-noetic-teb-local-planner\
                 ros-noetic-global-planner\
                 python3.8 \
                 libeigen3-dev \
                 cmake build-essential libpcl-dev libeigen3-dev libopencv-dev  \
                 python3-pip libboost-all-dev libtbb-dev -y
sudo apt-get install libboost-all-dev libwebsocketpp-dev nlohmann-json3-dev
sudo apt-get install ros-noetic-realsense2-camera ros-noetic-realsense2-camera-dbgsym ros-noetic-realsense2-description

• 安装完成依赖后，下面开始克隆、编译代码

提示：
在如下操作过程中，请注意：

• 编译过程会下载配置文件用来编译，请保证网络通畅，可以检查一下能否正常打开GitHub网页
• 若任意代码编译报错，请清除编译缓存后再重新尝试
• 清除编译缓存的方法为删除文件夹下的build目录

• 在tools目录下运行下程序。

#安装Livox-SDK

cd ~/ && mkdir tools && cd tools #工作在tools文件夹下
git clone https://github.com/Livox-SDK/Livox-SDK
cd Livox-SDK/build
cmake .. && make   #先运行cmake，再运行make
#若无报错信息，则证明编译成功
sudo make install

cd ../../ #退出至tools目录

sudo make install后界面如下代表成功安装Livox-SDK。

#安装Livox-SDK2

git clone https://github.com/Livox-SDK/Livox-SDK2
cd Livox-SDK2 && mkdir build && cd build
cmake .. && make
#若无报错信息，则证明编译成功
sudo make install

cd ../../ #退出至tools目录./build.sh ROS1

sudo make install后界面如下代表成功安装Livox-SDK2.

#安装gtsam
wget -O gtsam.zip https://github.com/borglab/gtsam/archive/refs/tags/4.1.1.zip
unzip gtsam.zip
cd gtsam-4.1.1/ && mkdir build && cd build
cmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF -DGTSAM_USE_SYSTEM_EIGEN=ON ..
sudo make install -j6 

#编译结束后可使用如下命令验证
ldd examples/VisualISAMExample | grep gtsam
#若显示文件名则证明编译成功
#若显示无法找到目录，则需要重新安装编译

#安装成功后退出至tools目录
cd ../../ 

ldd examples/VisualISAMExample | grep gtsam后界面如下代表成功安装gtsam。

#安装TEASER-plusplus
git clone https://github.com/MIT-SPARK/TEASER-plusplus.git
cd TEASER-plusplus && mkdir build && cd build
cmake .. -DENABLE_DIAGNOSTIC_PRINT=OFF
sudo make install 
sudo ldconfig

sudo make install后界面如下代表成功安装TEASER-plusplus.

#下载和编译建图定位导航代码
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
git clone https://github.com/limxdynamics/tron1-ss
cp -r tron1-ss/src/* ./ 
rm -rf tron1-ss
cd ..
catkin_make_isolated 

#若存在Failed to process package "livox_ros_driver2"，则执行以下指令
#若无报错信息，可忽略以下代码 
cd src/livox_ros_driver2
source /opt/ros/noetic/setup.sh
./build.sh ROS1
cd ~/catkin_ws/
source devel_isolated/setup.bash

#若存在Failed to process package "livox_ros_driver"，则执行以下指令
#若无报错信息，可忽略以下代码 
cd ~/tools/Livox-SDK/build
sudo make install

catkin_make_isolated 后界面如下代表成功。

2.3 雷达&电脑环境搭建

2.3.1 配置雷达IP地址

提示：
提示
雷达IP地址出厂时已通过觅道软件修改为：10.192.1.5，无需修改雷达IP

以下为知悉内容，新手可无需关注，直接执行后续“2.3.2配置机器人软件序列号”部分

雷达IP地址修改方式：

• 将雷达网线与用户电脑相连，连接成功后在觅道360官网（https://www.livoxtech.com/cn/mid-360/downloads）下载雷达软件Livox Viewer 2，按照用户手册进行安装。

• 安装完成后，将用户电脑与雷达改成同一网段后，刷新上述软件，则可读取雷达IP地址。

• 在Vim编辑器修改雷达IP，从而确保开发板与雷达IP地址一致。可执行以下指令进入Vim编辑器。（Vim的编辑与保存指令：当进入到Vim编辑器中，按键盘上的Insert，此时Vim进入编辑模式，可对代码进行编辑，编辑完成后按Esc键回到命令模式，输入:wq保存并退出。）

ssh guest@10.192.1.3    //密码：123456
cd ~/catkin_ws/
vim src/livox_ros_driver2/config/MID360_config.json

2.3.2 配置机器人软件序列号

当安装完上述依赖后，下面需要使用前面已经安装完成的websocket对机器进行控制。

• 获取机器人软件序列号：

首先需要操作用户电脑通过无线连接方式连接TRON1机器人，请选择并连接您机器人的Wi-Fi热点,密码为:12345678。

之后在浏览器中输入http://10.192.1.2:8080可以进入"机器人信息页",并查看机器人信息，如下图所示。

机器人软件序列号不同于SN(机器人序列号)，其格式为“xx_TRON1A_xxx”，需将SN中间的字段统一替换为“TRON1A”。例如页面中显示的SN为PF_TRON1A_075，则无需替换；若页面中显示的SN为PF_TRON1B_360，则机器人软件序列号应为WF_TRON1A_360

• 配置机器人软件序列号：

ssh guest@10.192.1.3    //密码：123456
vim ~/catkin_ws/src/sentry_navigation/sentry_tools/velocity_smoother_ema/src/velocity_smoother_ema.cpp

在vim编辑器的代码中，修改成对应的机器人软件序列号，

修改代码后，需重新编译。

cd ~/catkin_ws/
catkin_make_isolated
source devel_isolated/setup.bash

2.3.3 Rviz环境安装

当上述配置完成后，下载下面Rviz文件在本地电脑，其中limx_mapping用于Rviz建图；limx_localization为重定位Rviz。
limx_mapping_rviz.rviz
localizaiton_rviz.rviz

在用户电脑终端执行以下操作：

ssh guest@10.192.1.3    //密码：123456
sudo vim ~/.bashrc

在~/.bashrc文件末尾增加以下命令行

export ROS_IP=10.192.1.3
export ROS_MASTER_URI=http://10.192.1.3:11311

# ROS environment setup
source /opt/ros/noetic/setup.bash
source /home/guest/catkin_ws/devel_isolated/setup.bash

3 三维建图、重定位、导航示例

3.1 三维建图

3.1.1 地图录制

提示：
提示
前提条件：感知拓展套件已安装至机器人本体，开机并确保机器人处于准备状态（遥控器按L1+O，保持机器人base水平）

• 用户电脑连接机器人Wi-Fi，名称格式通常为「TRON1_xxx」，Wi-Fi密码：12345678。

• 用户电脑打开两个终端，分别通过SSH连接开发板开启雷达进程和建图进程，并录制地图：

开启雷达进程

ssh guest@10.192.1.3    //密码：123456
cd ~/catkin_ws
source devel_isolated/setup.bash
roslaunch livox_ros_driver2  msg_MID360.launch

执行roslaunch livox_ros_driver2 msg_MID360.launch后出现如下界面且持续运行则雷达进程开启成功。

再新建一个终端，开启三维建图进程

ssh guest@10.192.1.3    //密码：123456
cd ~/catkin_ws
source devel_isolated/setup.bash
roslaunch fast_lio_sam_sc_qn run.launch lidar:=livox_mid360

执行roslaunch fast_lio_sam_sc_qn run.launch lidar:=livox_mid360后出现如下界面且持续运行则三维建图进程开启成功。

• 查看建图效果：在用户电脑重开一个终端，且不要使用SSH指令连接开发板。

source /opt/ros/noetic/setup.bash
export ROS_MASTER_URI=http://10.192.1.3:11311  
export ROS_IP=10.192.1.x #x代表本地用户电脑ip地址最后一位
rviz
#开启上面的limx_mapping_rviz.rviz

• 打开Rviz后，选择file，找到上面的limx_mapping_rviz.rviz文件，然后打开。

• 出现如上图片数据后，表示地图已经开始录制，通过遥控器控制机器人行走，可进行地图录制。

3.1.2 地图保存

提示：
3.1.2中的程序均为开发板环境中执行，请在SSH连接完成的终端里执行以下操作！

• 保存pcd三维点云图：

完成地图录制后，通过Ctrl+C的方式结束上面三维建图进程(run.launch) 终端，其余终端保持不变。

三维点云图自动保存在fast_lio_sam_sc_qn文件下，路径如下

/home/guest/catkin_ws/src/fast-lio-mapping_and_localization-sc-qn/fast_lio_sam_sc_qn/

此时文件夹内存在result.bag、result.pcd两个文件，其中result.bag 在后面被用于重定位，result.pcd则用于导航。

• 将pcd三维点云图转换成 pgm二维栅格地图：确定result.pcd文件位置后，首先需要修改aa.launch文件。

vim ~/catkin_ws/src/fast-lio-mapping_and_localization-sc-qn/fast_lio_localization_sc_qn/launch/aa.launch

根据下面图片修改result.pcd对应的位置。

执行aa.launch文件

source devel_isolated/setup.bash
roslaunch fast_lio_localization_sc_qn aa.launch

aa.launch出现如下界面代表运行成功。

新起一个终端（依然需要ssh连接到NX开发板）保存地图，此时将得到limx_map.pgm、limx_map.yaml两个文件。

source /opt/ros/noetic/setup.bash
cd ~/
rosrun map_server map_saver -f limx_map  //保存地图为 limx_map 名字
#地图越大，点云越多，保存需要时间越长，请耐心等待，比较大图需要1分钟左右

提示：
注：建议将result.bag、result.pcb以及limx_map.pgm limx_map.yaml等文件放在同一个目录文档。

完成上面操作后，停止 aa.launch程序。

3.1.3 地图修整

• Linux需要提前下载gmp图片编辑软件，本地安装指令如下：

sudo apt install -y gimp language-pack-gnome-zh-hant language-pack-gnome-zh-hans

• 下载完成后，可以通过搜索GIMP打开软件：

• 将生成的limx.pgm从开发板传输至用户电脑。

方法一：在用户电脑端请求文件

则新开一个终端（不需要连接ssh）

scp guest@10.192.1.3:/home/guest/limx_map.pgm ~/ 
#guest是开发板的名称，10.192.1.3是开发板的ip，
#/home/guest/limx_map.pgm是开发板中pgm地图的保存路径，~/是pgm地图在用户电脑的保存路径。

方法二：ssh到开发板终端，从开发板端发送文件

ssh guest@10.192.1.3    //密码：123456
scp -r limx_map.pgm julychen@10.192.1.2:~/  #julychen@10.192.1.2 这部分根据客户实际情况

• 左上角文件选择刚传输的PGM文件，对二维栅格图进行编辑，修改，杂点进行清除：

地图路径在你当前运行map_server的目录下

• 将修改后的地图进行导出，文件格式和名字切勿修改，直接保存覆盖，覆盖完成后直接叉掉软件，此时弹窗选择“放弃修改”。

• 将对应的pgm文件打开确认看是否为已经修改完的地图，若是，则直接执行下命令，即将修改后的文件拷贝至英伟达开发板中，用于导航。

scp -r limx_map.pgm guest@10.192.1.3:~/  #该命令在用户电脑本地终端执行

3.2 定位和导航

3.2.1 环境配置

• 进行定位模块和3D重定位的位置配置。

 ssh guest@10.192.1.3    //密码：123456
 cd ~/catkin_ws/src/fast-lio-mapping_and_localization-sc-qn/fast_lio_localization_sc_qn/

• 配置3D重定位地图，给出建图生成的result.bag所在位置（绝对位置）。

vim config/config.yaml  #配置3d重定位的地图

• 配置2D静态地图，给出2D静态地图所在位置。

vim launch/run.launch

3.2.2 开启重定位

• 配置完成后，保存现有终端，新起一个终端，执行下命令。若雷达没有开启，则需开启雷达指令。

ssh guest@10.192.1.3    //密码：123456
cd ~/catkin_ws
source devel_isolated/setup.bash
roslaunch livox_ros_driver2  msg_MID360.launch

• 开启重定位

#开启一个新终端
ssh guest@10.192.1.3    //密码：123456
cd ~/catkin_ws
source devel_isolated/setup.bash
roslaunch fast_lio_localization_sc_qn run.launch lidar:=livox_mid360

• 本地打开Rviz，选择定位的Rviz。

source /opt/ros/noetic/setup.bash
export ROS_IP=10.192.1.x   #x代表本地用户电脑ip地址最后一位
export ROS_MASTER_URI=http://10.192.1.3:11311
打开定位的rviz   
#开启上面的limx_localization_rviz.rviz

• 打开Rviz后，选择file，找到limx_localization_rviz.rviz文件，然后打开。

• 当本地打开Rviz后，需将机器人通过遥控器操作起来，以找到特殊标志位进行重定位，若是重定位成功，终端将会打印下指令。

3.2.3 开启导航

• 执行导航避障指令。

roslaunch sentry_nav sentry_movebase.launch 

• 在rviz 上点击【2D Nav Goal】按钮，然后在地图中点击机器人要到达的目标点，并拖动设置方向(左键点击并保持按住，拖动设置方向)。

导航效果展示如下：

避障效果展示如下：