上周帮实验室把一台AT128接到工控机上前后折腾了两天才把实时点云在屏幕上刷出来。网上资料不少但真正从零讲到能跑起来的教程很少很多博客直接跳过了驱动编译和PandarView 2的坑。这篇就把我走通的完整路径留个档从系统准备、驱动编译到Rviz可视化再到PandarView 2安装避坑全部整理成能照着做的步骤。如果你正被雷达驱动编译不过、点云看不见、PandarView启动即崩这类问题卡住这篇文章就是给你的。先说结论AT128要在Ubuntu 20.04上实时出点云核心链路就三步——装好ROS Noetic和依赖库、用Hesai官方General驱动把雷达数据转成sensor_msgs/PointCloud2话题、再用Rviz或PandarView 2消费话题做可视化。链路本身不复杂但每一步都有几个容易踩的坑尤其是网络配置和PandarView 2那套CUDA/GL依赖能劝退不少人。1. 动手之前AT128点云落地的整体思路1.1 雷达本体的通信与数据链路AT128是禾赛的半固态前向主雷达128线水平视场FOV通常120度左右垂直视场约25.4度测距能力在实际道路场景里能到两百米级别。它的测距原理是飞行时间法ToF激光发射后打到物体表面再返回通过时间差算出距离配合电机在水平方向做一维扫描一帧就能覆盖前向扇形区域。这里要强调一个很多人刚接触时容易忽略的点AT128不是360度机械式扫描它是前向雷达安装在车辆前端或者测试台架上正前方才是它的有效感知区域。所以你把点云画出来之后看到的应该是一个扇形面而不是四周一圈。这个特点决定了它在自动驾驶里主要负责前向目标检测、可通行空间判断这些任务跟补盲、环视用的机械雷达定位完全不同。数据回传走的是千兆以太网。雷达内部已经完成了测距、标定和点云解析直接通过UDP把点云数据包发给上位机上位机这边需要做的只是“收包、按协议解包、还原成三维坐标点”。这句话说起来轻巧实际做的时候你会发现网络配置不对就啥都收不到所以后面我会专门花一节讲网口设置。1.2 选型思路Ubuntu 20.04 ROS Noetic 与驱动、可视化工具的分工为什么偏偏是Ubuntu 20.04一是禾赛官方驱动和PandarView 2对这些版本有明确的适配测试二是ROS Noetic正好只支持20.04三是大多数做感知的同事手里的工控机装的就是这个系统。你当然可以在18.04或者22.04上自己折腾但没必要遇到诡异报错时环境略偏离官方支持范围会很难排查。整个软件栈我习惯拆成四个层次看系统层Ubuntu 20.04 LTS 对应NVIDIA驱动如果你只跑Rviz看点云NVIDIA驱动不是必须的但PandarView 2要GPU加速渲染没有N卡驱动基本跑不起来。中间件层ROS Noetic负责节点通信驱动节点把点云发布到话题上可视化工具订阅话题。驱动层HesaiLidar_General_ROS官方维护的ROS驱动支持AT128、QT、Pandar等主流型号。注意别下载老版的HesaiLidar_ROS那个已经不维护了而且默认不支持AT128。应用层Rviz和PandarView 2。Rviz做实时三维可视化最方便PandarView 2更适合回放、逐帧分析点云和录制数据。我个人的建议是先只用Rviz把链路跑通再装PandarView 2做分析。原因很简单Rviz不依赖CUDA环境干净能把“驱动是否正常”这件事验证得明明白白PandarView 2功能强但依赖重装挂的概率也更大把它放到第二步能省很多排查时间。1.3 环境版本对照总览给一张我实测可行的版本对照表你照着准备基本不会出大错组件推荐版本备注操作系统Ubuntu 20.04.6 LTS内核5.4/5.15均可ROSNoetic对应Ubuntu 20.04编译工具cmake 3.16gcc/g 9系统默认就够关键依赖libpcap-dev、libyaml-cpp-dev、libeigen3-dev驱动编译和点云处理用NVIDIA驱动470.x或520.x取决于显卡PandarView 2需要CUDA见第5节驱动源码HesaiLidar_General_ROS 最新master别用旧的HesaiLidar_ROSPython系统自带Python3.8即可一般不用改这张表不是死的。比如你用的显卡比较新驱动版本当然跟着上如果只是跑ROS驱动看话题NVIDIA驱动可以完全不装。但如果你打算用PandarView 2显卡驱动这关绕不开。2. 环境准备与依赖安装2.1 干净的系统与ROS Noetic安装我强烈建议先装一个最小化系统不要刻意去装很多额外的桌面软件。原因是我遇到过多次由于系统里已有的ROS版本冲突、conda环境里的库干扰、或者是Python版本改动导致驱动编译失败的情况。Ubuntu 20.04装好之后第一件事是把系统更新到最新然后安装ROS Noetic。安装ROS Noetic用官方源的方式最省心大致是这几步sudo sh -c echo deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main /etc/apt/sources.list.d/ros-latest.list sudo apt install curl curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add - sudo apt update sudo apt install ros-noetic-desktop-full这里我强烈建议装desktop-full虽然耗时间但Rviz、rviz插件、常用点云工具链全都齐了。只装ros-noetic-ros-base的话后面还得单独装rviz和一堆依赖反而更费事。装完后记得把环境变量加进~/.bashrcecho source /opt/ros/noetic/setup.bash ~/.bashrc source ~/.bashrcROS装好后顺手装一下后续要用的点云和图像相关软包sudo apt install ros-noetic-pcl-ros ros-noetic-rviz ros-noetic-eigen-conversionspcl-ros非常关键它提供PointCloud2话题和PCL点云类型之间的转换。你后续如果要做点云配准、点云分割、3D目标检测PCL这套工具链是避不开的先把pcl-ros装好后面不用再回头补。2.2 驱动编译依赖pcap、yaml-cpp、cmake与CUDA环境的取舍雷达驱动底层要抓UDP包所以要装libpcap-dev。这个库的作用是让你写的程序能直接从网卡抓取原始数据包驱动解包的第一步就是调pcap。如果缺这个库编译时大概率会报找不到pcap.h或者链接时提示找不到libpcap。另外一个是libyaml-cpp-dev。禾赛驱动用YAML文件来配置雷达参数、标定信息解起来需要yaml-cpp这个C库。缺了它编译报错会非常绕你会看到一长串跟yaml有关的undefined reference不看编译日志的话很难联想到是系统库缺失。所以直接一次性装齐sudo apt install git cmake build-essential libpcap-dev libyaml-cpp-dev libeigen3-dev关于CUDA这时先不用装。因为运行ROS驱动节点并不需要CUDA真正用到CUDA的是PandarView 2。我建议先把驱动跑通、看到点云再回头装CUDA和PandarView 2。这样即使PandarView 2安装过程出问题也不会影响你对雷达数据的正常使用。Linux里CUDA很常见的一个坑是先装了NVIDIA驱动又用某个工具的依赖把CUDA装上结果版本不匹配某些软件喊找不到libcuda.so某些软件喊driver version不足。处理思路是记住你的工具链支持什么版本尽量用发行版自带的软件源去对齐不折腾反而最稳。2.3 网络与防火墙准备雷达通信的基础这块是我觉得整个教程里最容易被跳过的但也是最容易导致“什么都配好了就是没有点云”的原因。AT128通过千兆网口和上位机通信默认情况下雷达的IP一般是192.168.1.201上位机的网口需要配一个同网段的静态IP比如192.168.1.102。不同批次雷达出厂设置可能不同如果你不确定可以先用一条网线直连雷达和电脑的千兆口然后用nmap或者arp扫描工具扫一扫网段sudo apt install iputils-ping arp-scan sudo arp-scan --interfaceeth0 --localnet如果雷达供电正常并且网线没问题一般能扫到它的IP。扫到之后把你的电脑IP改到同一网段例如sudo ip addr add 192.168.1.102/24 dev eth0 sudo ip link set eth0 up注意如果你工作的工控机是双网卡一个网口用来上网一个网口用来接雷达一定要搞清哪个网口对应哪个网卡名。我见过有人把雷达接到内网口然后在错误的网卡上抓包折腾两小时最后才发现是插错口了。先看一眼ip a确定设备名再动手。另外检查你机器上有没有装ufw防火墙建议把对应网口的入站数据放行或者干脆在接雷达的网卡上关掉防火墙sudo ufw allow from 192.168.1.0/24在测试阶段我先用一条网线直连雷达和电脑不经过交换机少一层不确定性。确认能出点云以后再接路由器或交换机做多设备联调这样排查问题范围小很多。3. 从源码编译Hesai雷达驱动3.1 获取驱动源码与工程结构说明禾赛官方的驱动仓库是HesaiLidar_General_ROS在GitHub上能找到。我建议直接clone最新master旧标签和老的HesaiLidar_ROS不要碰。拉代码时注意网络环境如果GitHub不太稳定可以找一下国内镜像或者用代理方案但这不是本文重点你只要能拿到源码就行。source /opt/ros/noetic/setup.bash mkdir -p ~/catkin_ws_hesai/src cd ~/catkin_ws_hesai/src git clone https://github.com/HesaiTechnology/HesaiLidar_General_ROS.git驱动工程的结构大概是src目录下是驱动核心代码包括lidar驱动、udp包处理、点云解算等launch目录里放着示例launch文件conf或cfg目录一般放雷达配置比如AT128的选配参数。打开CMakeLists.txt会看到它用什么方式编译、依赖哪些库这一层值得花点时间看明白比直接瞎跑强。这个工程整体上是一个ROS包编译的时候需要在catkin工作空间里做。仓库目录本身就是包的根目录所以把它放进src就能被catkin识别。3.2 编译过程的重点参数与常见报错进入工作空间根目录编译cd ~/catkin_ws_hesai catkin_make第一次编译的时候如果之前环境变量没source好会出现catkin_make命令找不到的情况。不用慌检查一下source /opt/ros/noetic/setup.bash是不是已经写进~/.bashrc了重新开个终端一般就正常了。我自己的经验里编译阶段最常撞到这几个问题第一是缺pcap库或者yaml-cpp库编译器报错说找不到头文件。解决办法就是前面第2节提前装好libpcap-dev和libyaml-cpp-dev基本上不会再犯。第二是Eigen版本冲突尤其是你系统里同时存在ros-noetic自带Eigen和手动装过Eigen 3.4的情况。驱动源码里可能指定了Eigen路径你只要保证CMake找到的是同一个版本就没问题。如果报错指向Eigen的宏定义多半是版本混了。第三是编译时内存不够。AT128驱动的源码量不大但catkin_make在编译所有依赖时内存小于2GB的机器会卡住或直接OOM。我的工控机当初卡在了某几个模板实例化严重的文件上。解决办法是限制并行任务数catkin_make -j2用-j2降一降负载慢是慢点但不会中途崩。编译成功后你会看到生成的可执行文件一般叫hesai_lidar_pandar或者hesai_lidar_node之类。再检查一个环节放到ROS环境里能不能被找到。source ~/catkin_ws_hesai/devel/setup.bash roscd hesai_lidar如果你能进入到这个包目录说明ROS已经认识这个包了。到这一步驱动编译其实就已经成功了大半。3.3 launch文件配置讲解驱动安装好后launch文件是实际配置雷达型号、IP、话题名的关键。我看过不下十个版本的launch写法但核心参数就那几个。以下是我用的AT128 launch配置思路。打开launch目录下的示例文件找到类似这样的参数段param namelidar_type valueAT128/ param nameframe_id valueat128/ param nameserver_ip value192.168.1.102/ param namelidar_ip value192.168.1.201/ param namesource_port value2369/ param nameudp_port value2368/注意几个容易出错的地方lidar_type必须设成AT128驱动内部会根据这个值选择不同的解包逻辑和点云格式填错型号是肯定出不来的。frame_id决定点云话题里每个点的坐标系名字你在Rviz里把fixed frame设成这个值点云才能正常显示。server_ip是上位机的IP必须和实际网口IP一致lidar_ip是雷达的IP别写反了。port参数的具体数值不同固件版本会有差异。如果雷达是你第一次用我建议先用tcpdump -i eth0 udp port 2368之类命令抓一下包看看数据到底发到哪个端口。抓包是排查网络问题最直接的方式比反复改launch参数猜半天快得多。配置好之后把这些参数用launch文件组织起来roslaunch hesai_lidar hesai_lidar.launch驱动节点起来后会尝试接收UDP数据如果收包正常终端里通常会打印设备信息或者点云帧率统计。要是终端安安静静的大概率就是网络或者IP配置出了问题回第2.3节再排查一轮。4. 启动驱动并在Rviz中看到点云4.1 手动启动驱动节点的完整流程实际操作时我习惯分两个终端跑一个跑roscore和驱动节点一个跑Rviz。这样日志输出不会混在一起有问题好观察。终端一source /opt/ros/noetic/setup.bash source ~/catkin_ws_hesai/devel/setup.bash roslaunch hesai_lidar hesai_lidar.launch终端二source /opt/ros/noetic/setup.bash rosrun rviz rviz如果驱动正常你用rostopic list应该能看到一个名字类似/hesai_lidar或者/lidar_points的sensor_msgs/PointCloud2话题。想看具体话题名称终端三执行rostopic list rostopic hz /hesai_lidarrostopic hz会周期性打印话题发布频率如果雷达在10Hz这里会稳定显示在10.0左右。看到这个数字说明驱动到点云话题的链路已经通了。这时别急着关用rostopic echo /hesai_lidar -n 1看一眼点云消息有没有真的带点数以及点坐标范围是否合理。正常情况应该能看到height、width和data字段data很大都是原始二进制点云数据。如果点和坐标范围都在合理区间那你已经把驱动这关彻底拿下了。4.2 Rviz显示配置话题、坐标系与色彩渲染打开Rviz后默认界面是全黑或者只有网格很多人会以为没数据。其实只是还没设置好显示项。我把关键配置列出来左边的Display面板点击Add选By topic找到你的点云话题添加PointCloud2显示。添加后在左侧选中这个PointCloud2需要重点检查两个地方。第一个是Fixed Frame设置。全局配置里Fixed Frame必须和驱动launch里的frame_id保持一致通常是at128。如果不一致Rviz会强行把点云变换到别的坐标系下而系统又没有对应的TF树结果就是点云直接消失或者位置错乱。我见过太多人跑完驱动后Rviz空白检查半天最后却发现Fixed Frame没设对。第二个是Size和Color的设置。Size是指点的大小默认1像素在远处点云看起来会很稀疏可以调到2到3。Color默认是FlatColor颜色单一建议改成Rainbow或者Intensity用强度值染色这样能明显分辨车道线、反光牌、植被这些不同反射率的物体。看障碍物轮廓和距离时Intensity配色比纯色容易读很多。设置完之后你应该能看到一个扇形点云画面中间部分密、两侧逐渐稀疏。如果点云是一片混乱的星点且雷达本身没有移动优先怀疑坐标系和位姿问题如果显示是规则的扇形说明数据链路完全正常。4.3 用已有PCAP包先“本地复盘”点云有些情况下一时没有雷达硬件比如别人给你发了个录好的pcap包或者你想先不接雷达提前把驱动跑通。这时候驱动本身支持离线回放模式我测下来非常实用。找到launch文件里的replay参数一般在驱动参数里会有一个开关比如pcap_file路径参数或者replay_mode布尔值。把它设成pcap文件路径重新launch驱动驱动就会从pcap文件里读UDP包不再等待网卡数据。Rviz的显示步骤和实时模式完全一样。这个技巧在出差调试时很救命。我自己的习惯是拿到新版本驱动先不接雷达直接用厂家提供的pcap文件本地跑一遍确认驱动编译和可视化链路没问题再上车接真雷达。这样就能把“驱动没编好”和“现场网络有问题”这两类问题彻底隔离开排查效率高很多。5. PandarView 2安装实战与避坑指南5.1 PandarView 2的定位与安装前置条件PandarView 2是禾赛出品的点云可视化和数据分析工具跟ROS的Rviz相比它更贴近雷达原生数据格式支持同时打开多个数据源、逐帧回放、点云录制还能直接导入pcap离线包做分析。对不熟悉ROS或者不想拉起整个ROS环境的人来说装一个PandarView 2就能快速验证雷达状态是现场交付和售后排查利器。但PandarView 2安装门槛比Rviz高不少它依赖CUDA和OpenGL做GPU渲染。我这台工控机装的时候第一次跑起来黑屏卡死后来发现是NVIDIA驱动版本太老压根不兼容它要求的最低CUDA版本。所以安装前先确认两件事第一显卡是不是NVIDIA的第二驱动版本够不够。执行nvidia-smi看右上角的CUDA Version如果结果为空说明系统还在用Nouveau开源驱动PandarView 2基本跑不起来。如果确实没有NVIDIA显卡我建议老老实实用Rviz别在PandarView上死磕。它本质上是CUDA渲染工具没有N卡就是会失败。有这个时间还不如先把数据链路跑通。5.2 安装步骤实录我从禾赛官网或者提供的下载渠道获取PandarView 2安装包通常是一个tar.gz压缩包。拿到后的安装逻辑很简单——解压配库路径跑启动脚本。我习惯把工具放到固定的安装目录比如/opt/hesaisudo tar -xzf PandarView_2.x.x_Linux.tar.gz -C /opt/hesai/ cd /opt/hesai/PandarView*解压完之后看看目录里有没有一些带so后缀的库文件目录以及启动脚本常见叫PandarView.sh或run_PandarView.sh。启动脚本里通常已经设置了部分环境变量如果脚本写得不够全就需要自己手动指定动态库路径。以我见过的最常见结构为例启动前建议做这几件事。第一步把安装目录下的lib路径加进LD_LIBRARY_PATH。第二步如果启动时报缺少libGL、libX11相关库补装对应的OpenGL库sudo apt install libgl1-mesa-glx libgl1-mesa-dri libx11-6第三步直接运行启动脚本./PandarView.sh如果能看到主界面说明安装成功了一大半。接下来在工具里配置雷达IP和端口就能看到实时点云了。这里也有一个小坑PandarView 2连接雷达时会和ROS驱动同时抢UDP数据二者不能同时挂在同一个网口上接收同一路数据。实际操作时要么先关掉ROS驱动再开PandarView要么用交换机的镜像口分开给。这个点文档里往往不写但真联调时很容易遇到。5.3 启动、连雷达与帧率设置的坑启动脚本跑起来后会遇到几类比较典型的错误我挨个说。第一类是缺动态库。报错通常是error while loading shared libraries: libxxx.so。不用慌先看看报错的库在不在安装目录里如果在就是LD_LIBRARY_PATH没设置好如果不在系统里用apt-file search或者直接上网搜该库属于哪个包装上就行。我遇到最多的是找不到libcuda.so和libOpenGL相关的库前者是NVIDIA驱动没配好后者是系统图形库缺失。第二类是权限问题。PandarView 2要访问原始网络套接字读取UDP包普通用户可能因为没有CAP_NET_RAW权限而收不到数据现象是界面能开起来但数据源列表里一直显示不出点云。这时用sudo运行启动脚本或者给启动脚本添加capability。虽然用sudo运行不算最优解但现场排查时最快。第三类是帧率和分辨率设置。PandarView里通常会有一个设备配置或者旋转频率参数。AT128默认旋转频率一般是10Hz如果你在某个环境里看到点云的帧率忽高忽低可以检查一下数据源是否设置了丢帧或者显示抽稀。还有一种可能是电脑性能不足GPU渲染跟不上这时适当降低点云显示的点数上限或者关掉实时阴影和环境光画面会流畅不少。6. 常见问题排查与排查思路速查表6.1 点云始终为空从网口到话题一层层排查这是出现频率最高的问题。我的排查顺序完全按照数据流网卡收包 - 驱动解包 - ROS发布 - Rviz显示。第一步确认物理链路。雷达供电是否正常网线是否插对电脑IP和雷达IP是否同网段。第二步抓包看数据有没有到网卡。sudo tcpdump -i eth0 udp -nn -c 100如果一直没有输出说明UDP包根本没进来问题在网络配置和供电如果有大量的UDP包说明网络层正常问题大概率在驱动参数的端口或者IP设置上。这个判断非常有效能把排查范围缩小一大半。第三步看驱动有没有发布点云。重新打开驱动终端看有没有周期性日志或者用rostopic hz看话题频率。如果话题没有输出检查launch里的lidar_type、port、frame_id是否和雷达实际发送的一致。用一张表把这层逻辑整理一下现象优先排查常见原因tcpdump无UDP包网线/供电/IP网段雷达没启动或IP不在同一网段tcpdump有UDP包但话题无数据port/lidar_type参数驱动端口配置错误或型号不匹配话题有数据但Rviz空白Fixed Frame设置frame_id不一致或坐标系未配置Rviz有数据但点云混乱时间戳/TF有多个雷达时坐标系未区分6.2 点云不出墙/距离异常标定参数与坐标系小问题还有一种情况是点云出来了但看着不对比如点都堆在非常近的距离上或者有些点飞得很远。排除雷达硬件问题后最常见的原因有两个。第一是反射率和噪点没有过滤干净。雷达在玻璃、黑色物体、强阳光下会产生一些不稳定点这些点表现为孤立飞点。在后处理阶段用PCL做点云滤波时可以用统计滤波或半径滤波把这些噪点去掉。现在驱动里也一般带有距离裁剪参数可以直接把太近和太远的点过滤掉。第二是坐标系的旋转关系没对。如果你在Rviz里看到的点云整体是“躺着”的或者前后方向颠倒多半是驱动发布点云时采用的坐标系和你的车体坐标系定义不一致。这时不需要改驱动源码直接用静态坐标变换把点云转到期望的坐标系就行。测试时我常用static_transform_publisher发布一个固定的TF变换观察点云姿态是否符合预期。6.3 图形工具崩溃CUDA与OpenGL资源冲突最后说说PandarView 2和Rviz同时在一个机器上使用时的问题。两个工具本身不冲突但都用OpenGL渲染时如果机器上有多个GPU或者集显独显混用偶尔会出现渲染画面黑屏、花屏或者程序闪退。一个直接的解决方法是在远程或者无头环境里用Xvfb虚拟显示器跑PandarView 2避免OpenGL渲染和现有X会话抢资源。具体做法是sudo apt install xvfb xvfb-run -a ./PandarView.sh这样即使没有物理显示器PandarView 2也能在一个虚拟的X环境里跑起来界面输出你可能看不到但程序不会崩配合截图工具或者VNC服务就能远程查看。我出差时经常这么干比接一堆显示器省事。至于CUDA版本不匹配的报错我一般先看nvidia-smi显示的CUDA版本和PandarView要求的版本区间再决定是升级驱动还是软链CUDA库。记住一个原则先保证驱动版本满足显卡要求再满足PandarView要求两层都满足后基本不会出问题。到这一步从Ubuntu 20.04系统准备、ROS Noetic安装、驱动编译、Rviz可视化再到PandarView 2安装调试整条链路已经完整了。我个人实际操作中的体会是最耗时间的往往不是编译和代码而是网络、IP、坐标系这种“看起来很简单”的配置项。如果一开始就按数据流顺序逐层验证很多坑其实都可以提前避开。最后再分享一个小经验拿到一台陌生的AT128别急着接电脑上配驱动先花五分钟用PandarView 2或者tcpdump确认它的IP和端口再进ROS环境能少走一大半弯路。