跳到主要内容

nlink_parser2驱动包使用教程

1.ROS2驱动包开发环境配置​

1.1安装git​

如已安装git可忽略本步骤

$ sudo apt install git

1.2安装colcon构建工具​

colcon是 ROS 2 的标准化构建工具，用于自动化处理软件包的编译、依赖关系和环境设置，相当于 ROS 1 中的 catkin工具。

$ sudo apt install python3-colcon-common-extensions

2.搭建ROS2工作空间​

建议先搭建一个独立的工作空间，以便验证传感器完整功能

$ mkdir -p ~/nooploop_ws/src
$ cd ~/nooploop_ws/src

这个步骤非常重要，需要使用git clone --recursive命令来获取子模块，并且将功能包安装在src目录下

$ git clone --recursive https://github.com/nooploop-dev/nlink_parser2.git

$ cd ~/nooploop_ws
$ colcon build --symlink-install

使用cd命令回到工作空间目录，编译ROS2功能包。

出现 colcon build successful则表明成功

5.激活ROS2工作空间环境(source的使用方法)​

该步骤非常重要

关键步骤提示：编译完成后，必须通过source命令激活工作空间的配置脚本，才能将新编译的功能包路径添加到当前终端的环境中，从而允许ROS2工具(如 ros2 run、ros2 launch、ros2 echo)等发现和使用这些包。

一共有两种配置环境的办法

方法一：永久配置(推荐使用)

此方法通过将source命令添加到用户的shell启动配置文件(~/.bashrc)中，使得每次打开新终端时都会自动激活指定的工作空间环境。

操作步骤(任选其一即可)

选项A：使用绝对路径

$ cd ~/nooploop_ws
$ echo "source ~/nooploop_ws/install/local_setup.bash" >> ~/.bashrc
$ source ~/.bashrc

选项B：使用命令生成路径 此方法利用 $(pwd)命令自动获取当前所在目录的绝对路径，避免手动输入。

$ cd ~/nooploop_ws
$ echo "source $(pwd)/install/local_setup.bash" >> ~/.bashrc
$ source ~/.bashrc

方法二：临时配置(按需激活)

每次新打开终端都需要激活，此方法仅在执行source命令的当前终端窗口中有效。一旦关闭该终端，配置即失效。适用于快速测试新编译的包或临时使用某个特定工作空间。

$ cd ~/nooploop_ws
$ source install/setup.bash

6.配置串口环境(安装CH343串口驱动)​

目前Nooploop产品主要采用两种USB转TTL串口芯片：CP210x​ 与 CH343。Linux内核通常已集成CP210x驱动，但未包含CH343驱动。若无法确定产品所用芯片型号，一般建议依照本节教程安装CH343驱动，以确保兼容性。驱动开源仓库驱动链接

6.1下载驱动源码​

首先，将官方驱动源码克隆到本地。

$ cd ~/Downloads/
$ git clone https://github.com/WCHSoftGroup/ch343ser_linux.git

6.2编译驱动模块​

进入串口驱动的driver目录，make编译生成内核模块。

$ cd ch343ser_linux/driver/
$ make

常见问题一：编译环境缺失​

若执行 make命令时出现类似下图所示的错误，提示编译器缺失：

解决方案：安装必要的编译工具链。 
$ sudo apt update
$ sudo apt install -y gcc-12 g++-12

安装成功后，重新执行make命令即可。

6.3加载驱动模块​

将编译好的驱动模块动态加载到当前运行的内核中。 
$ sudo make load

常见问题二：安全启动阻止加载​

则需要参考以下帖子重启电脑进入BIOS，修改安全启动选项，禁用安全启动选项，开机后重新sudo运行之前的指令：

https://blog.csdn.net/qq_43135204/article/details/118547385

https://askubuntu.com/questions/762254/why-do-i-get-required-key-not-available-when-install-3rd-party-kernel-modules

6.4安装驱动​

$ sudo make install

运行结果和上图一致，则说明安装成功。

6.5开启串口设备权限​

第一次使用串口设备通常需要开启串口权限，一般建议依照本节步骤开启串口权限，以确保兼容性。开启方法，可参考 Fix serial port permission denied errors on Linux，也可以跟着本教程一步一步执行。

$ sudo usermod -aG dialout $USER

输入该命令重启系统

$ reboot

登录回来后打开终端，输入该命令

$ groups

输入完命令后，能看到输出里有dialout，便意味着成功完成。

7.硬件连接​

7.1无转接需求(使用官方连接线)​

如果使用官方usb-A口转typeC线(注意是数据线)或官方双端GH1.25-4P端子连接线，可进行下一步配置串口环境&&查看串口端口号

7.2需转接接口​

使用USB转TTL模块连接，需要检查产品与USB转TTL模块的接线线序，以及产品的供电电压(具体型号供电电压范围参考官网下载的数据手册，大部分型号都是5V供电的，不能使用3.3V供电)，产品和USB转TTL模块的接线参考下图：

接线时需要注意：UART通信中双方的TX和RX应该交叉连接

UART：接口信号线为3.3V的TTL电平，232和485的串口不能直接连接，需要通过对应的TTL转/232/485电平转换模块进行转接。不带USB口的型号，需要通过UART接口连接USB 转TTL模块到电脑使用NAssistant软件查看数据和配置参数，不能直接连接电脑的USB接口。接口线序简写为“VGRT”，对应VCC、GND、RX、TX，各个产品的线序以对应产品构造示意图中的简写线序为准，接口一一对应；除了LTPTag以外，所有产品配有1到2个用户UART接口。其中配备两个UART接口的型号的两个UART口，在硬件上是连接在一起的，只是接口方向不同，用户使用其中任意一个接口即可。此外需要注意不要同时连接两个UART接口，不要同时连接USB接口和UART接口，否则可能会出现冲突。

8.查看设备端口号​

本步骤是运行传感器的核心，必须查看该步骤

重要前提 在执行本步骤前，请确保：

本步骤旨在指导用户快速确定目标传感器或产品所对应的设备端口号(如 /dev/ttyUSBx、/dev/ttyCH343USBx或 /dev/ttyACMx)。

8.1工作原理概述​

当目标传感器或产品接入运行ROS2的Linux设备时，内核会识别硬件并自动创建设备端口号(如 /dev/ttyCH343USBx、/dev/ttyUSBx或 /dev/ttyACMx)。通过对比设备接入前后系统设备端口号的变化，可以精确确定目标设备对应的端口号。本方法的核心是差异比对。

8.2操作步骤​

本操作示例以ttyCH343USB类设备为例，其他类型(ttyUSB， ttyACM)逻辑相同。

步骤1：记录初始状态(设备接入前)​

将目标传感器或产品接入运行ROS2的Linux设备之前，首先在终端中执行以下命令，查看当前系统已存在的相关设备端口号，并记录列表。完整记录所有识别到的设备端口号信息。

依次输入以下三条命令，并记录所有出现的设备端口号

$ ls -l /dev/ttyUSB*
$ ls -l /dev/ttyCH343USB*
$ ls -l /dev/ttyACM*

记录示例：根据上图输出，记录结果如下：

  • ttyUSB*：列表为空(无设备端口号)。

  • ttyCH343USB*：发现设备 /dev/ttyCH343USB1。

  • ttyACM*：列表为空(无设备端口号)。

步骤2：接入设备记录状态​

将产品通过USB线或者Nooploop官方的NUTT(NUTT-B、NUTT-C)型号的USB转TTL模块连接至ROS2的Linux设备中。目标传感器接入ROS2的Linux设备后，然后再次输入相同的三条命令。

$ ls -l /dev/ttyUSB*
$ ls -l /dev/ttyCH343USB*
$ ls -l /dev/ttyACM*

结果对比与判定：

对比步骤1与步骤2的命令输出列表，在步骤2中新出现的设备端口号即为目标传感器对应的端口号。

根据上述记录示例分析：

  • ttyUSB*与 ttyACM*列表对比前后无变化。

  • ttyCH343USB*列表中新增了/dev/ttyCH343USB0设备端口号。

因此，可以确定目标传感器的设备端口号为 /dev/ttyCH343USB0。

异常处理：如果对比后发现列表没有任何变化，请排查传感器硬件连接、电源或设备本身是否工作正常。

步骤3：验证(推荐执行)​

通过重新插入→再次检测的循环验证，确保识别准确性：

  • 再次拔除：设备端口号应再次消失

  • 插入设备：消失的设备端口号应重新出现

  • 确认端口与设备物理连接的严格对应关系，避免误判

常见问题：通过上述方案，如果设备端口号被识别为 ttyACM* 而非 ttyCH343USB*​

解决方法：

  • 情况判断：如果您已确保安装了串口驱动并开启了串口权限。但目标传感器仍然被识别成ttyACM*设备端口号，而不是 ttyCH343USB*设备端口号。

  • 解决方案：将已找到的 ttyACM*设备端口号确定为最终可用的设备端口号。

  • 后续应用：在接下来的 Launch 文件配置中，请直接使用此 ttyACM*设备端口号。后续也可以正常使用。

9.配置Launch与运行​

重要前提 在执行本步骤前，请确保：

9.1 准备环境​

本章节的目标是：将已确认的设备端口号配置到对应产品的Launch文件中，并启动相应的ROS2节点。

新开终端，进入工作空间并激活环境(source)​

$ cd ~/nooploop_ws
激活ROS2工作空间环境(source)(如未激活请先执行下方命令) 
$ source install/setup.bash

9.2 配置与启动产品节点​

配置产品参数，Launch的设备端口号配置方法​

根据确认的新增设备端口号(/dev/ttyCH343USBx、/dev/ttyUSBx 或 /dev/ttyACMx)来配置设备端口号。 您可以通过以下两种方式配置设备端口号的参数：

方法一：命令行参数配置(快速配置)​

无需修改文件，直接在启动命令中指定端口和波特率参数。(注意波特率参数需跟产品设置的波特率参数一致，一般默认出厂参数为921600)

参数说明：

  • port_name:=/dev/您的设备端口号 - 指定串口设备路径

  • baud_rate:=波特率值- 指定通信波特率(需与模块设置一致)

根据您的产品型号，选择并执行对应的启动命令：​

  • 启动 LinkTrack 系列
$ ros2 launch nlink_parser2 linktrack.launch.py port_name:=/dev/ttyCH343USB0 baud_rate:=921600

  • 启动 LinkTrack AOA系列
$ ros2 launch nlink_parser2 linktrack_aoa.launch.py port_name:=/dev/ttyCH343USB0 baud_rate:=921600

  • 启动 TOFSense/TOFSense-F系列
$ ros2 launch nlink_parser2 tofsense.launch.py port_name:=/dev/ttyCH343USB0 baud_rate:=921600

  • 启动 TOFSense-M系列
$ ros2 launch nlink_parser2 tofsensem.launch.py port_name:=/dev/ttyCH343USB0  baud_rate:=921600

方法二：修改Launch文件(永久配置)​

如需永久修改某个产品的Launch配置，可直接编辑其Launch文件(.launch.py)，找到port_name和baud_rate参数定义处进行修改。 打开并修改nlink_parser2功能包的launch目录下对应产品的*.launch文件内的默认端口设备号，以及如果之前对连接到ROS的这个模块的波特率参数进行过修改，还需要把launch文件中的波特率也改为对模块设置的波特率。

LinkTrack系列​ linktrack.launch.py

LinkTrack AOA系列​ linktrack_aoa.launch.py

TOFSense/TOFSense-F系列 ​ tofsense.launch.py

TOFSense-M系列​ tofsensem.launch.py

修改步骤：

  1. 打开对应产品的launch文件： 客户可根据自己的路径打开launch文件 本教程的launch路径为Home / nooploop_ws / src / nlink_parser2 / launch

  1. 查找并修改以下参数：

  1. CTRL+S保存launch文件，打开终端输入以下命令

根据您的产品型号，选择并执行对应的启动命令：​

  • 启动 LinkTrack系列
$ cd ~/nooploop_ws
$ source install/setup.bash
$ ros2 launch nlink_parser2 linktrack.launch.py

  • 启动 LinkTrack AOA系列
$ cd ~/nooploop_ws
$ source install/setup.bash
$ ros2 launch nlink_parser2 linktrack_aoa.launch.py

  • 启动 TOFSense/TOFSense-F系列
$ cd ~/nooploop_ws
$ source install/setup.bash
$ ros2 launch nlink_parser2 tofsense.launch.py

  • 启动 TOFSense-M系列
$ cd ~/nooploop_ws
$ source install/setup.bash
$ ros2 launch nlink_parser2 tofsensem.launch.py

launch启动常见问题：​

问题一：运行launch没报错，但没有出现红框所示的内容​

这个问题非常常见，多数客户都是卡在这一步。表现为启动launch文件后，提示“Serial port opened successfully， waiting for data.”而没有提示“xxx has been advertised，use 'ros2 topic echo /xxxxxxxxxxx' to view the data”，如

排查方法：

  1. 产品必须先连接NAssistant软件(https://www.nooploop.com/download/)，确认可以正常识别模块并获得相应的坐标距离角度等输出数据以后再连接ROS(LinkTrack系列产品需要按照用户手册等教程的步骤搭建好测试系统，连接console或anchor进行一键标定获得正确刷新的标签坐标后再把标签连接ROS，同时需要注意此时所有的控制台和基站都需要处于上电状态)。(如果联系售后工程师排查需提供出现此问题的该模块在NAssistant下正常识别并获取数据的截图或视频)
  2. 将产品连接NAssistant软件确认正常识别模块且输出数据正常后，进入设置页面，确认并记录该模块设置的波特率，检查运行的launch文件中的波特率是否和记录的波特率一致，如果不一致，将launch文件中的波特率改为记录的波特率。如果NAssistant软件是在运行ROS的这台PC上运行的，完成1、2步的检查后需要关闭NAssistant软件
  3. 绝大部分客户是这一步出现的问题： 从运行ROS的PC或板卡上拔掉连接产品的USB线或者USB转TTL模块，打开一个命令行窗口执行
$ ls -l /dev/ttyUSB*
$ ls -l /dev/ttyCH343USB*
$ ls -l /dev/ttyACM*

产品通过USB线连接或者通过USB转TTL模块连接运行ROS的PC或板卡(虚拟机需要映射端口)，再执行

$ ls -l /dev/ttyUSB*
$ ls -l /dev/ttyCH343USB*
$ ls -l /dev/ttyACM*

(如果联系售后工程师排查必须提供运行上述四个命令后的截图)记录增加的那个ttyUSB端口号，如ttyUSB1或ttyCH343USB0，检查运行的这个launch 参数的端口号是否和这个新增的端口号一致，如果不一致，更改launch 参数的端口号为新增的端口号。

  1. 如果使用的是CH340型号的USB转TTL模块(部分CH340模块在Ubuntu下921600波特率通信不稳定)，需要先把模块连接NAssistant软件把自身波特率改为115200，同时把launch文件中的波特率改为115200来进行应用

  2. 上述步骤后，如果还是waiting for data，检查运行ROS的这台PC或板卡上有没有运行NAssistant等与串口或者虚拟串口相关的软件(如NAssistant等软件打开后会自动连接串口)，如果有的话需要关闭这些软件

此时一般来说可以解决绝大多数的问题，如果还是waiting for data，可以准备上述的截图等材料联系售后工程师进行排查

问题二：未配置环境，找不到功能包​

not found: "package 'nlink_parser2' not found， searching: ['/opt/ros/humble']"

未激活ROS2工作空间环境，请先执行下方命令

$ source install/setup.bash

10.使用echo命令查看产品数据​

操作前提与确认

本章节旨在指导用户如何查看由 Nooploop 产品节点发布的实时数据。 在开始本章操作前，请确保您已按照第9章的步骤，成功启动了产品的Launch文件。成功的明确标志是：在运行ros2 launch ...的终端中，出现了类似下图红框中的提示信息： 'ros2 topic echo /************' to view the data 这个提示信息至关重要。 其中，/************ 是该节点发布的实际话题名称(例如 /nlink_linktrack_tagframe0或 /nlink_tofsense_frame0等等)。此话题名即为该节点对外发布核心数据的确切通道。因此，最直接的查看方法是：复制红框提示中的完整话题名，直接用于 ros2 topic echo命令。

只有当您看到此提示时，才表示相应的ROS 2节点已正常启动并开始发布数据。此时，请按照以下通用流程在新终端中查看数据：

  1. 打开新终端：保持节点运行终端不变，新开一个终端窗口用于执行数据查看命令。

  2. 激活环境：在新终端中，激活包含 Nooploop 功能包的工作空间环境。

  3. 方法一：直接查看：使用从红框中获得的具体话题名，直接执行 ros2 topic echo <话题名>。

  4. 方法二：列出并选择：或先执行 ros2 topic list查看当前系统所有活跃话题列表，从中确认目标产品数据的话题名称，再使用 ros2 topic echo命令订阅并打印。

重要提示： 执行 ros2 topic list命令后显示的话题列表，与您当前连接的硬件模块类型、数量及其工作模式(配置)直接相关。

10.1 查看数据​

LinkTrack系列(以查看tagframe0话题为例)​

$ source ~/nooploop_ws/install/setup.bash
$ ros2 topic list
$ ros2 topic echo /nlink_linktrack_tagframe0

LinkTrack AOA系列​

$ source ~/nooploop_ws/install/setup.bash
$ ros2 topic list
$ ros2 topic echo /nlink_linktrack_aoa_nodeframe0

TOFSense/TOFSense-F系列​

$ source ~/nooploop_ws/install/setup.bash
$ ros2 topic list
$ ros2 topic echo /nlink_tofsense_frame0

TOFSense-M系列​

$ source ~/nooploop_ws/install/setup.bash
$ ros2 topic list
$ ros2 topic echo /nlink_tofsensem_frame0

10.2常见错误​

错误一：未配置环境，echo找不到​

未激活ROS2工作空间环境，请先执行下方命令

$ source ~/nooploop_ws/install/setup.bash

11. 话题订阅与数传示例​

重要提示：

在本示例中，接入ROS2系统的LinkTrack系列模块被设置为标签T0，使用的输出协议为Tag_Frame0，所以在使用本示例时，需将LinkTrack模块，使用NAssistat软件设置成Tag_Frame0协议和对应的模式。如果使用其它输出协议如标签默认的nodeframe2协议，则参考本示例编写和订阅对应nodeframe2的话题，同时需要注意(变长协议话题订阅注意事项)

另外A0基站需先在另一台电脑连接至上位机NAssistant软件(上位机NAssistant软件下载)，LinkTrack模块配置如下图所示

本例程演示基于ROS2的节点通信与数据回传流程，实现以下功能：​

  • 订阅nlink_parser2 发布的 NLink_LinkTrack_Tag_Frame0话题，实时显示标签定位数据。

  • 向/nlink_linktrack_data_transmission话题发布数据，实现标签数传功能。

  • 通过 A0 基站在上位机验证数据是否成功接收。

11.1 安装并编译功能包​

本步骤需新开一个终端，且需要创建该示例的工作空间。 注意：编译前需先激活nlink_parser2所在工作空间的(source)环境变量，确保系统能够正确找到依赖项。

$ source ~/nooploop_ws/install/setup.bash
$ mkdir -p ~/nooploop_example_ws/src
$ cd ~/nooploop_example_ws/src/
$ git clone https://github.com/nooploop-dev/nlink_example2.git
$ cd ~/nooploop_example_ws/
$ colcon build --symlink-install

显示 colcon build successful则表明成功

需另外新开一个终端，每个终端都必须重新 source 环境变量，再启动nlink_parser2节点，发布标签数据话题：

$ source ~/nooploop_ws/install/setup.bash
$ ros2 launch nlink_parser2 linktrack.launch.py port_name:=/dev/ttyCH343USB0 baud_rate:=921600

11.3 运行数据接收与数传示例​

新开终端或使用11.1步骤下创建的终端。 重要前提：本示例中演示的数传功能是通过标签T0向A0基站上传数据的完整链路。其中A0基站需先在另一台电脑连接至上位机NAssistant软件(https://www.nooploop.com/download/) 在验证数传示例步骤前，请确保：

  • A0基站已连接至上位机NAssistant软件

nlink_example2功能包，包含两个核心功能：

  • 1.数据接收与显示：订阅 nlink_parser2包发布的话题，接收并打印NLink_LinkTrack_Tag_Frame0格式的数据。

  • 2.数据发送：通过向 /nlink_linktrack_data_transmission 话题发布消息，将数据经由T0标签，通过UWB无线模块发送给所有基站(如A0基站)和控制台(C0)模块，从而使用LP模式下的数传功能。

$ cd ~/nooploop_example_ws/
$ source install/setup.bash
$ ros2 run nlink_subscriber nlink_subscriber

图中红框说明：

  1. 第一个红框：显示订阅标签T0的NLink_LinkTrack_Tag_Frame0定位数据。

  2. 第二个红框：显示通过该功能包将数据发布到/nlink_linktrack_data_transmission话题，又通过话题将数据由标签T0发送给基站A0。

11.4 数传数据接收验证​

用户可以通过另外一台电脑连接A0基站接收并通过串口传输给上位机，并使用NAssistant自带的串口调试助手和数传窗口来验证数传功能。 数据经标签T0发送后，由A0基站接收并转发至上位机。 下图所示为，上位机串口助手界面中的数传图标， 数传图标只有接收到数传数据才会出现。

A0基站接收到的数据内容：

上图红框说明：显示标签T0的数传模块将数据转发后，由A0基站接收，上位机最终接收到的数据内容。

11.5 变长协议话题订阅注意事项​

在使用部分产品时，需特别注意其部分协议(如Anchor_Frame0，Node_Frame0，Node_Frame1，Node_Frame2，Node_Frame3，Node_Frame4，Node_Frame5，Node_Frame6，Node_Frame7)包含可变长度的数组。这一特性直接影响您编写订阅者节点处理数据的方式。

重要前提：nlink_parser2驱动包已完成了底层串口协议的解析，并将数据封装为标准化的ROS2消息。您通过话题(如/nlink_linktrack_nodeframe0)接收到的，是一个结构化的数据对象，而非原始字节。

1. 消息结构分类​

根据nodes数组是否可变，可分为两类：

  • 定长消息：如 Tag_Frame0对应的消息。其所有字段长度是固定的。

  • 变长消息：如 Node_Frame2对应的消息。其 nodes数组长度会动态变化。

2. 变长部分(nodes数组)的原理​

变长协议的核心在于其 nodes 部分。每个 nodes 对应一个基站、标签或控制台等设备的数据块。

  • 长度变化触发条件：系统中有效设备的数量或部分模块发生丢包现象时发生变化时，nodes部分的数据块数量会相应增减。

3. 变长协议结构示例​

本文档以 “1标签 (T0) + 4基站 (A0~A3) + 1控制台 (C0)” 运行于 LP_MODE0为例，其 Node_Frame2协议数据结构如下图所示：

主要数据字段说明表：

字段组字段名描述单位/备注
​role当前连接ROS的模块(本地节点)对应的角色参数
id当前连接ROS的模块(本地节点)对应角色参数的ID
local_time本地节点时间毫秒 (ms)
system_time系统时间毫秒 (ms)
voltage本地节点接口供电电压伏特 (V)
pos_3d标签位置米 (m)
eop_3d标签位置精度估计米 (m)
​vel_3d标签速度米/秒 (m/s)
angle_3d标签欧拉角度 (°)
quaternion四元数
注意：(仅极少数硬件支持，大部分硬件为无效值)imu_gyro_3d惯性测量单元角速度
弧度/秒 (rad/s)
注意：(仅极少数硬件支持，大部分硬件为无效值)imu_acc_3d惯性测量单元加速度
米/秒² (m/s²)
nodes数组[x] (每个nodes元素) ​
role对应的远程非直连节点的角色
id对应的远程非直连节点的角色参数的ID
dis本地节点到该节点的距离米 (m)
fp_rssi本地节点到该节点的第一路径信号强度dB
rx_rssi本地节点到该节点的接收信号强度dB

4. 【关键】在应用中安全处理变长数组​

在您的应用程序中订阅此类消息时，必须始终意识到 nodes数组的长度是动态的。

  • 安全访问原则：在订阅ROS 2话题时，用户应始终通过 msg->nodes.size()获取数组当前的实际元素数量，并以此值作为循环和索引访问的边界，从而确保不会越界访问动态数组 nodes中的元素。