1. 为什么选禾赛AT128P搭配ROS做感知开发
禾赛AT128P这款激光雷达在自动驾驶和机器人感知圈子里热度一直不低，128线的垂直分辨率加上200米的探测距离，放在园区物流车、无人清扫车、巡检机器人这类场景里，基本属于“一步到位”的配置。我第一次拿到这颗雷达的时候，第一反应是它比想象中轻，第二反应是——这玩意儿没有USB口，也没有网口转接线，只有一根航插线缆甩出来，里面藏着电源和以太网。也就是说，你没法像插U盘一样把它怼到电脑上，必须先把网络这关过了，才能谈ROS驱动。
这个项目要干的事情很明确：在Ubuntu系统上，通过ROS把AT128P跑起来，让点云数据能在RViz里正常显示，并且把网络配置这个最容易卡住新手的环节彻底讲透。适合谁看？如果你刚接触激光雷达，手里正好有一台AT128P，或者你在做ROS小车、SLAM建图、目标检测相关的开发，需要把雷达数据接进ROS生态，那这篇内容基本能帮你省掉至少一个周末的折腾时间。
我见过太多人卡在“雷达通电了、灯也亮了、但ifconfig里看不到设备”这一步，然后开始怀疑是不是雷达坏了。其实十有八九是网络配置的问题。AT128P出厂默认IP是192.168.1.201，主机需要配一个同网段的静态IP，比如192.168.1.100，子网掩码255.255.255.0。听起来很简单对吧？但Ubuntu从20.04开始网络管理换成了Netplan，22.04又有了新的图形化配置方式，再加上如果你用的是虚拟机或者工控机，网卡命名可能是enp3s0、eth0、enx开头的USB网卡名，每一步都有坑。下面我就按实际操作的顺序，把整个流程拆开讲。
2. 网络配置：整个项目最容易翻车的地方
2.1 先搞清楚你的网卡叫什么名字
很多人上来就改/etc/network/interfaces，结果发现Ubuntu 20.04之后这个文件根本不存在，或者改了没生效。原因是从Ubuntu 18.04开始，网络配置默认由Netplan接管，配置文件在/etc/netplan/目录下，通常是00-installer-config.yaml或者01-network-manager-all.yaml这种名字。
第一步不是急着改配置，而是先确认你的网卡名称。打开终端，输入：
ip link show你会看到类似这样的输出：
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000 link/ether 00:1b:21:3c:4d:5e brd ff:ff:ff:ff:ff:ff 3: wlp2s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000 link/ether a4:5e:60:1f:2b:3c brd ff:ff:ff:ff:ff:ff这里enp3s0就是有线网卡，wlp2s0是无线网卡。你要连雷达的是有线口，所以记住enp3s0这个名字。如果你用的是USB转网口，名字可能是enx开头的长串，比如enx00e04c6801a2，这个也要记下来。
注意：如果你在虚拟机里跑Ubuntu，网卡名字可能是ens33、ens160这种。虚拟机还需要额外配置网络模式，这个后面单独说。
2.2 Netplan配置静态IP的完整写法
确认网卡名之后，进入/etc/netplan/目录，看看里面有什么文件：
ls /etc/netplan/通常会看到一个yaml文件。用sudo权限编辑它：
sudo nano /etc/netplan/01-network-manager-all.yaml如果你希望有线网卡用静态IP连雷达，无线网卡继续DHCP上网，配置大概长这样：
network: version: 2 renderer: NetworkManager ethernets: enp3s0: dhcp4: no addresses: - 192.168.1.100/24 routes: - to: 192.168.1.0/24 via: 192.168.1.1 metric: 100 nameservers: addresses: [8.8.8.8, 114.114.114.114] wifis: wlp2s0: dhcp4: yes access-points: "你的WiFi名称": password: "你的WiFi密码"这里有几个关键点。第一，renderer写NetworkManager还是networkd，取决于你系统里装了什么。桌面版Ubuntu一般用NetworkManager，服务器版可能用networkd。如果你不确定，可以先写NetworkManager，改完用netplan try测试，不行再换。
第二，addresses里的/24表示子网掩码255.255.255.0，这个必须和雷达的网段一致。AT128P默认是192.168.1.201，所以你的主机IP可以是192.168.1.100到192.168.1.254之间的任意一个，只要不跟雷达冲突就行。
第三，routes这一项其实可以省略，因为同网段通信不需要网关。但如果你同时要上网，保留默认路由指向WiFi的网关更稳妥。我一般会把有线口的metric设高一点（数值越大优先级越低），这样系统默认走WiFi上网，只有访问192.168.1.x的时候才走有线口。
改完之后执行：
sudo netplan try这个命令会应用配置并等待120秒，如果网络断了你没确认，它会自动回滚。确认没问题后按回车，然后：
sudo netplan apply2.3 验证网络通不通的三种方法
配置完先别急着插雷达，先自己ping一下自己的IP：
ping 192.168.1.100能通说明网卡起来了。然后插上雷达，等雷达启动完成（大概30秒到1分钟，听到风扇转起来或者看到指示灯闪烁），再ping雷达：
ping 192.168.1.201如果ping不通，按这个顺序排查：
| 排查项 | 检查方法 | 常见问题 |
|---|---|---|
| 网卡是否UP | ip link show enp3s0 | 显示DOWN说明网卡没启用 |
| IP是否配对 | ip addr show enp3s0 | 看有没有192.168.1.100 |
| 网线是否插好 | 看网口指示灯 | 灯不亮换根线试试 |
| 雷达是否启动 | 听风扇/看灯 | 电源功率不够会反复重启 |
| 防火墙是否拦截 | sudo ufw status | 临时关闭测试sudo ufw disable |
还有一个很多人忽略的点：如果你的电脑有多个网口，或者你之前配过其他静态IP，可能存在IP冲突。用arp-scan扫一下同网段：
sudo apt install arp-scan sudo arp-scan --interface=enp3s0 192.168.1.0/24这个命令会列出同网段所有活跃设备，你能看到192.168.1.201是不是被雷达占用了。
实操心得：我习惯把主机IP设成192.168.1.100，因为好记。但如果你同时调试多个雷达，建议按雷达编号分配，比如雷达1用.100，雷达2用.101，避免IP冲突。另外，有些工控机有两个网口，一个连雷达一个连外网，这时候一定要确认你改的是连雷达的那个口。
2.4 虚拟机环境下的特殊处理
如果你在VMware或VirtualBox里跑Ubuntu，网络配置会更绕一层。虚拟机的网卡是虚拟出来的，你需要先把物理网卡“桥接”给虚拟机，或者用NAT模式再做端口转发。
VMware下的推荐做法是：虚拟机设置里，网络适配器选“桥接模式”，并且勾选“复制物理网络连接状态”。这样虚拟机里的enp3s0就相当于直接连在物理网口上，雷达能直接ping通。
VirtualBox稍微麻烦一点，需要在“网络”设置里选“桥接网卡”，界面名称选你实际连雷达的那个物理网口。如果桥接后ping不通，检查一下VirtualBox的“混杂模式”是不是设成了“全部允许”。
还有一种情况是用WSL2跑ROS，这个我不推荐用来连雷达，因为WSL2的网络是NAT后的，虽然能通过端口转发收到部分数据，但组播和原始以太网帧支持不好，AT128P的数据流可能会丢包。老老实实用原生Ubuntu或者虚拟机。
3. ROS驱动安装与点云数据接收
3.1 ROS版本选择和基础环境准备
AT128P的官方ROS驱动对ROS1和ROS2都有支持，但ROS1 Noetic是最后一个ROS1版本，2025年5月已经停止维护了。如果你是新项目，我建议直接上ROS2 Humble或者Jazzy。但如果你手头有大量ROS1的代码要复用，Noetic也还能用，只是要注意安全更新问题。
Ubuntu 20.04对应Noetic，Ubuntu 22.04对应Humble，Ubuntu 24.04对应Jazzy。选哪个版本，先看你的Ubuntu版本，再看你的项目需求。
安装ROS本身，如果你觉得官方步骤太繁琐，可以用“鱼香ROS一键安装”脚本，这个在社区里口碑不错，能省掉配源、装依赖的很多步骤。但我要提醒一句：一键脚本方便是方便，但装完之后你最好还是知道ROS的安装路径、环境变量在哪配，不然出了问题不好排查。
wget http://fishros.com/install -O fishros && . fishros运行后按菜单提示选对应版本就行。装完记得：
source /opt/ros/noetic/setup.bash或者把它加到~/.bashrc里，省得每次开终端都要source。
3.2 禾赛官方驱动的获取和编译
禾赛的ROS驱动在GitHub上开源，仓库名叫HesaiLidar_General_ROS。ROS1和ROS2的代码在同一个仓库的不同分支里。
ROS1 Noetic的编译流程：
mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src git clone https://github.com/HesaiTechnology/HesaiLidar_General_ROS.git cd .. catkin_make source devel/setup.bashROS2 Humble的编译流程：
mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src git clone https://github.com/HesaiTechnology/HesaiLidar_General_ROS.git -b ros2 cd .. colcon build source install/setup.bash编译过程中如果报错找不到某个包，大概率是依赖没装全。ROS1下常见缺的是ros-noetic-pcl-ros和ros-noetic-pcl-conversions，ROS2下是ros-humble-pcl-ros和ros-humble-pcl-conversions。用apt装上就行。
注意：禾赛的驱动仓库更新比较频繁，不同版本对应的雷达型号支持不一样。AT128P需要确认你clone的分支里包含AT128的配置。如果编译完发现没有AT128的launch文件，去仓库的README里看看是不是需要切到特定tag。
3.3 配置文件的关键参数解读
禾赛驱动的配置文件在config/目录下，AT128P对应的文件通常是config.yaml或者AT128P_config.yaml。这个文件里几个参数必须改对：
lidar: - driver: udp_port: 2368 ptc_port: 9347 host_ip: 192.168.1.100 lidar_ip: 192.168.1.201 frame_id: hesai_lidar model: AT128P correction_file_path: "path/to/correction_file.csv"udp_port是数据端口，AT128P默认2368，这个一般不用改。ptc_port是控制端口，默认9347。host_ip是你主机的IP，lidar_ip是雷达的IP，这两个必须和实际配置一致。frame_id是点云在TF树里的坐标系名称，后面RViz里要对应上。
correction_file_path是角度校正文件，禾赛出厂时会提供，或者从官网下载。这个文件决定了点云的精度，如果路径不对或者文件缺失，点云可能会变形或者有分层。我遇到过有人忘了配这个，点云看起来像“两层楼”，就是校正文件没加载。
3.4 启动驱动并验证数据流
ROS1下启动：
roslaunch hesai_lidar hesai_lidar.launchROS2下启动：
ros2 launch hesai_lidar hesai_lidar_launch.py启动后，先看终端有没有报错。正常的话会打印雷达型号、固件版本、数据包接收状态。然后开一个新终端，ROS1下：
rostopic list你应该能看到/hesai_lidar/points_raw或者类似的话题。用rostopic hz看一下频率：
rostopic hz /hesai_lidar/points_rawAT128P的典型帧率是10Hz或20Hz，如果你看到频率远低于这个，或者时有时无，说明网络丢包了。ROS2下用：
ros2 topic hz /hesai_lidar/points_raw如果话题存在但没数据，检查防火墙和UDP端口。Linux默认的ufw可能会拦截UDP 2368，临时关掉测试：
sudo ufw disable如果关掉就有数据了，说明需要加规则放行：
sudo ufw allow 2368/udp sudo ufw allow 9347/udp4. RViz可视化与点云效果调优
4.1 RViz基础配置步骤
数据有了，接下来要在RViz里看到点云。启动RViz：
rviz第一步，把Fixed Frame改成hesai_lidar，这个要和配置文件里的frame_id一致。如果这里报错说frame不存在，检查驱动有没有正常发布TF。
第二步，左下角Add一个PointCloud2，Topic选/hesai_lidar/points_raw。
第三步，调整点云大小和颜色。PointCloud2的Style选Points，Size设成0.01到0.05之间，太大画面会糊，太小看不见。Color Transformer选Intensity或者AxisColor，Intensity能看出反射率差异，AxisColor按Z轴高度着色，看地面和障碍物更直观。
如果点云显示出来是“一坨”而不是清晰的环境轮廓，大概率是校正文件没加载，或者frame_id配错了导致点云叠加了错误的变换。
4.2 点云“飘”和“分层”的排查
“激光雷达建图飘”是热搜里经常出现的问题，但飘的原因分两种：一种是RViz里看着飘，一种是SLAM建图后地图飘。前者通常是显示问题，后者是里程计和雷达外参标定问题。
RViz里点云飘，先看Fixed Frame是不是设成了odom或者map，而雷达的frame_id是hesai_lidar，如果TF树里没有hesai_lidar到odom的变换，RViz就会用默认值，导致点云位置乱跳。解决办法是把Fixed Frame改成hesai_lidar，先确认雷达自身数据是稳的。
点云分层，就是同一面墙出现上下两层点，通常是校正文件的问题。AT128P每个激光器的角度都有微小差异，校正文件就是补偿这些差异的。如果文件路径写错，驱动会用默认角度，点云就会分层。检查launch文件里的correction_file_path，确保指向正确的CSV文件。
还有一种分层是安装问题。如果雷达装歪了，比如俯仰角有几度偏差，点云也会看起来分层。这时候需要在TF里加一个静态变换来补偿：
rosrun tf static_transform_publisher 0 0 0 0 0.05 0 base_link hesai_lidar 100这个命令的意思是，在base_link和hesai_lidar之间加一个绕Z轴旋转0.05弧度的变换，补偿安装偏差。具体数值需要根据实际安装角度调整。
4.3 点云数据录制和离线回放
调试阶段经常需要把数据录下来反复分析。ROS1下用rosbag：
rosbag record /hesai_lidar/points_raw -O at128p_test.bagROS2下用ros2 bag：
ros2 bag record /hesai_lidar/points_raw -o at128p_test录的时候注意磁盘空间，AT128P单帧点云大概几十MB，10Hz录一分钟就是几百MB到1GB。建议录短一点，或者用--duration限制时长。
回放的时候，ROS1：
rosbag play at128p_test.bag --loopROS2：
ros2 bag play at128p_test回放的同时开RViz，就能反复看同一段数据，方便调参和对比算法效果。
实操心得：我习惯在录bag的时候同时录一个
/tf和/tf_static，这样回放的时候TF树是完整的，RViz不会报frame错误。命令是rosbag record /hesai_lidar/points_raw /tf /tf_static -O test.bag。
5. 常见问题速查与避坑经验
5.1 网络类问题速查表
| 现象 | 可能原因 | 解决方法 |
|---|---|---|
| ping不通雷达 | 主机IP不在同网段 | 改主机IP为192.168.1.x |
| ping不通雷达 | 网卡没启用 | sudo ip link set enp3s0 up |
| ping不通雷达 | 防火墙拦截 | sudo ufw disable临时测试 |
| 能ping通但无数据 | UDP端口被占 | netstat -anu | grep 2368查占用 |
| 数据断断续续 | 网线质量差 | 换Cat6以上屏蔽线 |
| 虚拟机里ping不通 | 网络模式不对 | 改桥接模式，选对物理网口 |
| IP冲突 | 同网段有其他设备 | arp-scan扫描后改IP |
5.2 ROS驱动类问题速查表
| 现象 | 可能原因 | 解决方法 |
|---|---|---|
| 编译报错找不到pcl | 依赖缺失 | 装ros-*-pcl-ros |
| 启动后无点云话题 | 配置文件IP错 | 检查host_ip和lidar_ip |
| 点云分层 | 校正文件未加载 | 检查correction_file_path |
| 点云频率低 | 网络丢包 | 检查网线、关防火墙 |
| RViz报frame错误 | Fixed Frame不对 | 改成hesai_lidar |
| 点云位置乱跳 | TF树不完整 | 检查是否有odom到雷达的TF |
| 驱动启动即退出 | 端口被占用 | 杀掉占用2368的进程 |
5.3 那些文档里不会写的坑
第一个坑：AT128P的电源要求是9V到32V，典型功耗12W左右。如果你用USB供电或者劣质电源，雷达可能启动到一半就重启，表现是ping一会儿通一会儿不通。我建议用12V/2A以上的独立电源，别跟其他大功率设备共用。
第二个坑：网线。AT128P是千兆以太网，数据量很大，对网线质量敏感。我试过用一根便宜的扁平网线，ping通但点云丢包严重，换Cat6屏蔽线之后立刻稳定。如果你发现点云频率只有5Hz甚至更低，先换线。
第三个坑：主机IP不要设成192.168.1.1。有些路由器默认网关是.1，如果你主机也设.1，路由表会混乱。用.100之后的地址更安全。
第四个坑：如果你同时用多个雷达，每个雷达的IP要改成不同地址。禾赛提供了Web控制界面，浏览器输入雷达IP就能进配置页面改IP。但改完IP后，主机IP也要相应调整，或者加多个IP别名。
第五个坑：ROS2下启动驱动时，如果报“failed to create subscription”之类的错误，检查你的RMW实现。默认是FastDDS，但有些环境下CycloneDDS更稳定。切换方法：
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp然后重新启动驱动。
5.4 性能调优的几个实用参数
如果你发现点云数据量太大，RViz卡顿，可以在驱动配置里降采样。禾赛驱动支持设置publish_pointcloud_type，可以只发布部分点或者降低发布频率。
另外，ROS1下可以用nodelet方式加载驱动，减少进程间拷贝开销。禾赛的launch文件里通常有hesai_lidar_nodelet.launch，用这个启动比普通node方式CPU占用低一些。
对于SLAM建图，如果你用Cartographer，建议把点云先降采样再喂给SLAM。Cartographer的num_point_clouds参数控制每次处理的点云帧数，设成1到3之间比较平衡。太多会卡，太少会丢特征。
6. 从驱动到SLAM建图的衔接建议
雷达跑通之后，下一步通常是做SLAM建图。ROS2 Humble下用Cartographer的话，需要额外装ros-humble-cartographer和ros-humble-cartographer-ros。配置文件里要改几个关键参数：
TRAJECTORY_BUILDER_2D.num_accumulated_range_data = 1 TRAJECTORY_BUILDER_2D.min_range = 0.5 TRAJECTORY_BUILDER_2D.max_range = 50.0 TRAJECTORY_BUILDER_2D.voxel_filter_size = 0.05max_range设成50米就够了，AT128P虽然能测200米，但远距离点云稀疏，对建图帮助不大，反而增加计算量。voxel_filter_size设0.05到0.1之间，太小计算量大，太大丢细节。
建图飘的问题，除了前面说的校正文件和TF，还有一个常见原因是IMU和雷达的外参没标定。如果你有IMU，建议用lidar_align或者手动标定，把雷达和IMU的旋转平移关系测准。没有IMU的话，纯激光SLAM在长走廊或者空旷区域容易飘，这是原理决定的，不是配置能解决的。
保存地图，Cartographer提供了cartographer_pbstream_to_ros_map工具，能把pbstream转成pgm和yaml：
ros2 run cartographer_ros cartographer_pbstream_to_ros_map -pbstream_filename=map.pbstream -map_filestem=map生成的map.pgm和map.yaml可以直接给导航模块用。
最后分享一个我自己的习惯：每次调试雷达之前，先把网络配置和驱动启动步骤写成一个shell脚本，下次直接跑脚本，省得重新回忆。脚本里包含设置静态IP、source环境、启动驱动、启动RViz这几步。这样即使换电脑或者重装系统，也能快速恢复环境。
#!/bin/bash sudo ip addr add 192.168.1.100/24 dev enp3s0 source /opt/ros/noetic/setup.bash source ~/catkin_ws/devel/setup.bash roslaunch hesai_lidar hesai_lidar.launch & sleep 3 rviz -d ~/catkin_ws/src/HesaiLidar_General_ROS/rviz/hesai_lidar.rviz这个脚本不一定适合所有人，但思路你可以参考。把重复劳动脚本化，把精力留给真正需要思考的算法和调参，这是我做了这么多年感知开发最实在的一条经验。
