说实话AT128 这雷达我已经在 Ubuntu 20.04 上跑过好几轮了每次帮同事配环境还是会碰到一些奇奇怪怪的问题。这篇东西我早就该整理出来前前后后踩过的坑加起来比教程本身还长。网上虽然也能搜到零散的安装记录但大部分都卡在 PandarView 2 装不上、点云出不来这一步就断了很少有一篇能让你从头到尾照着敲完就直接看到实时点云的文章。这篇保姆级教程要解决的就是四件事把 Ubuntu 20.04 的网络环境配好让电脑能拿到 AT128 的数据包把官方可视化工具 PandarView 2 顺利装上绕开我在安装过程中遇到的各种依赖报错用工具把实时点云显示出来并且能判断数据到底正不正常最后再往 ROS 方向走一步告诉你日后开发时怎么用 RViz 来接替 PandarView。不管你是刚拆箱的研究生还是帮实验室调设备的技术支持只要手头有一台 AT128、一台装了 Ubuntu 20.04 的电脑这篇文章应该都能帮你省下至少一个通宵。1. AT128 雷达与点云应用场景先搞清楚你要面对的是什么1.1 AT128 不是“大号 Velodyne”半固态扫描方式决定了很多使用习惯要改很多人第一次拿到 AT128下意识会把它和传统的 64 线、128 线机械旋转雷达摆在一起比觉得无非是线数更多、角度更广。这个理解方向对了一半但 AT128 的本质区别在于它是半固态激光雷达内部通过转镜结构实现扫描而不是整个雷达头部绕垂直轴旋转。所以它的水平视场角不是 360 度而是 120 度左右垂直视场角大约 25 度测距能力最远能到 200 米点频在 153.6 万点每秒上下波长是 905 纳米。这样带来的直接后果是如果你之前用惯了机械式雷达指望单台设备覆盖车辆周围一圈那拿到 AT128 之后这个习惯要改。AT128 的应用场景多数是安装在车头或者车顶前向用多台拼接来覆盖 360 度环境。当然单台做前向感知、路侧感知、园区巡检也完全没问题数据输出依然是标准的三维点云坐标、距离、反射强度这些信息都包含在内。1.2 点云数据流向雷达到电脑这条链路每个环节都可能出问题AT128 内部已经完成了从激光发射、信号采集到点云计算的全过程对外输出的直接就是标准 UDP 以太网数据包。换句话说电脑端不需要任何专用的采集卡只需要一张千兆网卡、一根网线把雷达的数据包接住然后交给软件解析渲染。这里我习惯打一个比方雷达就像一家快递仓库把每一帧点云数据打包成一个个 UDP 包裹通过网络发给你电脑上运行的可视化软件就是快递分拣员负责拆包、整理、把点云画到屏幕上。整个过程看起来简单但任何一个环节出问题都会直接影响结果。网卡没识别、IP 配置错了、防火墙拦截、数据包被网线质量拖累导致丢包、可视化软件依赖缺失这些我在实际调试里都遇到过后面每一节都会对应展开讲。1.3 推荐学习路线PandarView 2 验证、SDK 二次开发、ROS 集成拿到雷达之后我建议你按照三个阶段来推进。第一阶段用官方工具 PandarView 2 做整机验证确认设备是好的、网络通了、点云正常这个阶段的目标是“看到点云”。第二阶段再去看官方提供的 SDK 和驱动代码理解点云数据是怎么解析出来的为后续写自己的应用打基础。第三阶段是接入 ROS无论是跑 SLAM、做目标检测还是标定ROS 环境才是真正干活的舞台。很多人一上来就想着直接编译 ROS 驱动结果连最基本的数据链路都没有验证过最后出了问题根本分不清是硬件还是软件的问题。所以我这篇教程会严格按这个顺序来先把 PandarView 2 跑通再讲 ROS 集成这样排错的范围可以大大缩小。2. Ubuntu 20.04 环境准备网卡、静态 IP、数据包验证一条龙2.1 网络拓扑与接线直连比路由器靠谱AT128 采用的是标准以太网输出雷达端通常是一个工业级网口电脑端用普通千兆网口就能对接。连接方式上我强烈建议你直接用网线把雷达和电脑连起来也就是“点对点直连”不要图方便把雷达插到实验室的交换机或者路由器上。原因有二。第一AT128 的数据量不小每秒上百万个点换算成网络带宽大约是几十兆字节每秒的 UDP 流量如果交换机上有其他大流量设备在跑丢包的概率会明显上升。第二雷达通过 UDP 广播发送数据如果接到公司或实验室的大网里这些广播包会扩散到整个局域网既影响别人也可能被路由器的防火墙策略误伤。直连就清爽得多一台电脑一个雷达没有中间商赚差价。上电的时候也要注意AT128 的供电是通过专用线束完成的电压范围一般是 9V 到 36V 直流常见的是 12V 或 24V 供电。千万不要自己乱接线最好使用雷达包装里附带的原装线缆。上电后雷达内部的转镜会起转工作正常时能听到轻微的风扇声和转镜运转声状态指示灯也会亮起。2.2 配置静态 IP让电脑和雷达处于同一网段雷达出厂时一般会有一个默认 IP 地址通常在 192.168.1.x 这个网段具体以你拿到设备附带的手册为准常见的是 192.168.1.201。雷达不会主动去请求 DHCP 地址它就像一个固定地址的服务器一直在往外发数据。所以电脑端的 IP 必须手动设置成与雷达同一个网段才有可能收到数据。举个例子如果雷达默认 IP 是 192.168.1.201那么电脑的 IP 可以设置为 192.168.1.102子网掩码 255.255.255.0网关不用填。在 Ubuntu 20.04 上我建议直接用 netplan 来配置简单直接。打开配置文件sudo vim /etc/netplan/01-netcfg.yaml写入以下内容network: version: 2 renderer: networkd ethernets: enp0s3: dhcp4: no addresses: - 192.168.1.102/24注意把 enp0s3 换成你电脑实际网卡的名字可以用命令ip a查看。保存后执行sudo netplan apply然后检查一下网卡 IP 是否生效ip addr show enp0s3这里补充一句我不推荐在 Ubuntu 桌面版里用图形界面的网络设置去改 IP因为有时候 NetworkManager 和 netplan 的配置会互相覆盖改了半天发现 IP 没变。用 netplan 统一管理至少在服务器端和桌面端都能保持一致行为。2.3 用 tcpdump 验证雷达数据包是否到达IP 配好之后先别急着打开 PandarView先确认数据包是不是真的到了电脑网卡里。这里推荐用 tcpdump 抓包看一眼。执行sudo tcpdump -i enp0s3 udp -c 100如果网卡名是 enp0s3并且雷达已经上电、网线也接好了应该能看到不断刷新的 UDP 包源地址是雷达的 IP端口一般是雷达数据输出端口。看到这些数据包就说明物理链路和数据链路都已经通了下一步装软件才有意义。如果 tcpdump 什么都没有输出不要急着去装驱动先回头查三层问题网线有没有松、网卡有没有起来、IP 是不是在同一网段。我遇到过很多次折腾了半天软件最后发现问题只是网线插错了口。3. PandarView 2 安装避坑指南依赖、权限、GLIBC 这些坑我都替你踩过了3.1 PandarView 2 是什么为什么我建议你先用官方工具验证PandarView 2 是禾赛官方提供的点云可视化软件可以用来实时显示雷达点云、调整视角、查看距离和反射强度信息。和后来我们做开发常用的 RViz 相比PandarView 2 的优势在于它不需要搭建 ROS 环境不需要编译任何驱动装好之后直接配置 IP 就能连接雷达非常适合做设备验收和快速验证。从拿到手到跑通我的经验是先把这个工具点亮确认雷达本身没问题然后再去碰 ROS 那套东西。否则你就得在一个充满未知变量的环境里同时调试硬件和软件出了问题很难定位。3.2 安装前依赖准备一次性安装齐全PandarView 2 是图形界面程序依赖 Qt、OpenGL、libpcap 这些库。很多人装完之后双击图标没有反应或者终端里报错找不到某个 so 文件十有八九就是缺依赖。建议在安装之前一次性补齐sudo apt update sudo apt install -y libpcap-dev libqt5core5a libqt5gui5 libqt5widgets5 libgl1-mesa-dev libglu1-mesa-dev如果你的电脑装了独立显卡尤其是 NVIDIA 显卡建议同时装好显卡驱动。PandarView 2 渲染点云时对 OpenGL 的要求比较高集显虽然也能跑但点云一多旋转视角就会掉帧。NVIDIA 驱动装好之后可以用glxinfo | grep OpenGL renderer确认当前使用的渲染器是不是独立显卡。注意glxinfo 属于 mesa-utils 包如果提示找不到命令先执行sudo apt install -y mesa-utils3.3 安装与启动三步走拿到 PandarView 2 的安装包后一般是一个压缩包或者一个可执行文件。这里以压缩包为例说明完整流程。第一步解压。假设压缩包在当前用户的主目录下cd ~ tar -xzvf PandarView2_xxx.tar.gz第二步进入解压出来的目录给可执行文件加权限。有些压缩包解压之后文件没有可执行权限直接运行会提示 Permission deniedcd PandarView2_xxx chmod x PandarView2第三步运行。这里有一个重点如果你采用以太网直连的方式抓取雷达数据PandarView 2 抓包时可能涉及 socket 权限问题普通用户执行会提示无法打开网络设备。我建议先用 sudo 启动sudo ./PandarView2如果你的系统是桌面版且当前用户在 sudo 组也可以将用户加入 sudo 组后继续用这种方式。当然如果你是在自己控制的机器上做实验sudo 运行是最省事的方案。3.4 高频报错集合附解决办法这里我整理一下 PandarView 2 安装和启动时最高频的几个报错每个都是我亲身遇到过的或者帮别人排查过的直接对号入座就能解决。报错信息根本原因解决方法error while loading shared libraries: libpcap.so.1缺少 libpcap 运行库安装 libpcap-devcannot open shared object file: libQt5Core.so.5Qt5 核心库缺失安装 libqt5core5a 等 Qt5 依赖QXcbConnection: Could not connect to display没有图形环境或 DISPLAY 变量错误确认在桌面环境运行或 export DISPLAY:0socket: Operation not permitted权限不足无法抓包使用 sudo 启动启动后窗口黑屏 / 画面不刷新OpenGL 渲染异常检查显卡驱动试用 mesa-utils 确认渲染器类型./PandarView2: /lib/x86_64-linux-gnu/libc.so.6: version GLIBC_xx not found系统 GLIBC 版本低于软件要求确认 Ubuntu 20.04 已更新到最新补丁必要时升级系统最后一个 GLIBC 问题比较隐蔽因为 Ubuntu 20.04 的 GLIBC 版本可能因为长期没有执行过sudo apt upgrade而停留在比较旧的版本。遇到这种情况先跑一下sudo apt update sudo apt upgrade把系统基础库更新一遍然后再运行软件。4. 实时点云显示与数据质量校验4.1 PandarView 2 界面操作与参数配置PandarView 2 启动之后界面里一般会有连接参数设置区域包括雷达 IP、电脑 IP 和数据端口。软件里通常会有默认端口保持默认即可。这里要特别提醒雷达 IP 必须和雷达实际的 IP 完全一致不能随便填。你可以在雷达手册上找到出厂 IP或者在上一步 tcpdump 抓包时从数据包源地址里看到雷达 IP两者对照一下最稳妥。点击连接按钮之后如果参数正确界面上的点云会立刻开始刷新。此时你会看到一个扇形分布的三维点云这就是 AT128 的 120 度水平视场角扫描结果。点云的疏密程度和距离有关近处密集远处稀疏这是激光雷达的正常特性。操作方面鼠标左键旋转视角滚轮缩放右键平移。你可以把视角拉近看最近的物体也可以拉远看整体轮廓感受一下 128 线雷达的纵向分辨率。说实话第一次在 PandarView 里看到 AT128 点云时那种墙面像刀切一样平直的效果会给你留下很深的印象。4.2 如何快速判断点云是否正常看到点云之后先别急着开心按照下面几个维度快速做个体检。第一看地面。在雷达安装正常的前提下地面点云应该是连续、平整的一条线或一面中间没有大的空洞。如果地面点云有明显的断层或者大面积缺失可能是雷达安装角度有问题也可能是某个线束的探测异常。第二看反射强度。PandarView 2 一般可以用颜色表达反射强度。高反射物体比如路牌、车身的颜色应该明显区别于低反射物体比如深色路面。如果整个画面的强度值都一样说明反射强度信息没有正常解析可能是软件显示模式设置的问题。第三看远处。找一栋 50 米以外的建筑或一棵树观察点云是否还能勾勒出轮廓。AT128 在 905 纳米波长下对远处低反射率物体测距能力有一定衰减但如果 100 米开外的墙体完全没有任何点那就要考虑设备标定或者故障问题。第四看帧率。PandarView 2 界面上一般会显示当前的帧率和点数。AT128 的点频大约为 153.6 万点每秒以一帧 10Hz 为例一帧应该在 15 万点上下。如果显示的点数明显偏少多半是丢包了检查网线是否千兆、接口是否松动。4.3 点云显示异常的常见表现与应对方法实际调试过程中最常见的就是“点云很稀疏”。这通常不是雷达的问题而是电脑网卡协商成了百兆模式或者网线质量太差丢了大量 UDP 包。可以用ethtool enp0s3查看网卡协商速率确认是 1000Mb/s。如果协商成了 100Mb/s换一根六类网线或者检查网口是否有灰尘。另一个常见的现象是“点云抖动”——视角看起来在不停摇晃。这要看情况如果雷达本身没有固定好物理抖动会直接反映在点云上如果雷达固定没问题那可能是你观察的是动态场景。AT128 是半固态转镜扫描不是瞬间快照同一帧内不同线束的扫描时间略有差异运动物体会出现轻微的运动畸变这属于正常现象。如果点云彻底不显示但 tcpdump 能看到数据包那问题基本都出在软件配置上。最常见的是雷达 IP 填错或者电脑本地网卡选错。PandarView 2 里如果有多网卡机器一定要确认当前选的是直连雷达的那张网卡而不是连接外网的无线网卡。5. 进阶ROS 驱动集成与 RViz 点云可视化5.1 为什么建议开发阶段切换到 ROSPandarView 2 作为验证工具足够优秀但它做不了算法开发。如果你想把点云数据接入到 SLAM、目标检测、感知融合这些流程里ROS 几乎是绕不开的基础设施。Ubuntu 20.04 搭配 ROS Noetic 是我目前用得最顺的组合。好消息是 AT128 的 ROS 驱动方案比较成熟官方维护了驱动代码社区里也有不少现成配置。编译完成后点云会以 PointCloud2 消息发布到 ROS 话题上RViz 可以订阅话题并实时显示。整个过程跑通之后你就拥有了一个标准的 ROS 点云数据源后面做任何算法开发都方便。5.2 在 Ubuntu 20.04 上编译 Hesai ROS 驱动在开始编译之前确保 ROS Noetic 已经完整安装。如果没有安装参考 ROS 官方文档安装 ros-noetic-desktop-full。然后创建工作空间并拉取驱动代码mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src git clone https://github.com/HesaiTechnology/hesai_lidar.git cd ~/catkin_ws catkin_make编译之前记得 source 一下 ROS 环境source /opt/ros/noetic/setup.bash如果编译过程中提示缺少依赖包根据报错信息用 apt 安装即可。编译完成后配置驱动参数。关键文件在 hesai_lidar 包的 launch 目录下打开对应的 AT128 launch 文件把 server_ip 改成雷达的实际 IPhost_ip 改成你电脑的 IP。这里的 IP 必须和网络配置阶段保持一致否则驱动收不到数据。启动驱动source ~/catkin_ws/devel/setup.bash roslaunch hesai_lidar hesai_lidar.launch驱动启动后终端里会持续输出接收到的点云帧信息。此时可以新开终端用命令确认话题rostopic list你应该能看到类似/hesai/pandar或者包含 points 的点云话题。再看一眼话题的消息类型应该是 sensor_msgs/PointCloud2。5.3 RViz 中显示实时点云确认话题存在后启动 RVizrviz在 RViz 界面里把左侧 Displays 面板的 Fixed Frame 设置为驱动 launch 文件里配置的 frame_id通常类似 hesai/AT128。然后点击 Add选择 By topic找到点云话题确认消息类型是 PointCloud2点击 OK 添加。这时你应该能在 RViz 的 3D 视图里看到和 PandarView 2 类似的点云画面了。RViz 默认的点云渲染方式是大方块如果觉得太粗可以在 PointCloud2 的 Display 属性里把 Style 改为 PointsSize 调小一点看起来就细密多了。如果 RViz 画面里看不到任何点优先检查 Fixed Frame 是否和话题时间戳的 frame_id 匹配这是新手最常犯的错误。另外确认驱动端打印的帧数和点数是不是正常增长如果驱动起来但没人订阅话题有些驱动版本会默认不发布数据需要在 launch 里设置 publish 参数为 true。6. 常见问题速查与排障实录6.1 高频问题速查表把我在各种场合遇到的高频问题整理成一张速查表按图索骥命中率很高。问题现象可能原因排查与解决tcpdump 收不到 UDP 包网线问题、网卡未启用、IP 网段不一致先查网线再看 IP然后看网卡协商速率PandarView 连接后无点云雷达 IP 配置错误、端口错误、防火墙拦截核对 IP用默认端口确认没有开启 ufw 或放行 UDP点云显示很稀疏网卡协商百兆、网线质量问题、CPU 处理不过来用 ethtool 查看速率换六类线关闭其他大流量应用点云画面卡顿GPU 渲染性能不足、OpenGL 驱动异常装 NVIDIA 驱动用 glxinfo 验证渲染器RViz 里看不到点Fixed Frame 不匹配、话题未发布、frame_id 配置错误检查 launch 配置确认 rostopic hz 有数据雷达上电后不工作供电电压不足、线缆松动、设备故障检查电源指示灯用原装线缆联系售后6.2 两个隐藏比较深的坑第一个坑是 UDP 丢包率。AT128 数据量很大如果电脑网卡的接收缓冲区不够内核丢包会在完全不知道的情况下发生。用netstat -su可以查看 UDP 丢包统计如果发现大量的 receive buffer errors可以适当调大网卡缓冲区sudo sysctl -w net.core.rmem_max134217728这个参数让我在跑长时间采集任务时少了很多莫名其妙的问题特别是在录制 bag 包的时候推荐大家都设置一下。第二个坑是时间戳。AT128 输出的点云数据带有时间戳但如果雷达和电脑之间没有做时间同步点云时间戳和系统时间可能对不上。后期做多传感器融合的时候这个问题会变得致命。入门阶段不用太在意但如果你要做相机和雷达的联合标定一定要提前考虑 PTP 时间同步方案从第一天开始就把时间戳问题纳入考虑范围。6.3 关于 AT128 后续扩展的一些经验整个流程跑通之后你会发现 AT128 就是一个标准的数据源后续想怎么玩完全取决于你的应用场景。比如做多雷达拼接需要注意不同雷达之间的外参标定做目标检测需要同步采集图像和点云做融合做点云配准和语义分割可以先从公开数据集练手再用实车数据做验证。基本链路是通的剩下就是在算法和应用层面深挖。写到这里AT128 在 Ubuntu 20.04 上从零跑通实时点云的完整流程就讲完了。回看整个过程真正困难的地方其实不是某一个具体步骤而是每个环节里那些零碎的小坑。我自己在帮别人排错的时候体会最深的一句话是先把链路一步步拆开验证哪一步有问题就定位哪一步千万别一口气把软件硬件全堆上去再查问题。照着这个原则来哪怕你以后换别的型号激光雷达处理思路也是一样的。