LiDAR Driver

The LiDAR driver produces 3D cone positions on the live path. Hesai UDP returns become a short list of centroids on /cones for point_to_pixel. Cameras do not create those positions.

On kumar, LiDAR UDP uses port 2368. A second process bound to that port starves or conflicts with the driver.

Pipeline

Receive and compute run on separate threads with a lock-free ring so packet intake is not blocked by clustering.

UDP packets land in the ring and are decoded to 3D returns (mm internally).
Points are binned into an angular-segment × range-bin grid (compile-time sizes; see table below).
As each angular segment completes, Grace & Conrad removes ground-like returns.
After the sweep cutoff, DBSCAN clusters the remaining cloud and emits one centroid per cluster.
Centroids publish on /cones in metres (interfaces/msg/Points).

Cutoffs and DBSCAN/GnC thresholds are the usual levers when /cones is empty or noisy. Correction (.dat on bags, PTC live) belongs upstream of clustering: bad angles look like sparse or skewed cones even when UDP is healthy.

Topics

Topic	Type / notes
`/cones`	`interfaces/msg/Points`, metres. Contract into point-to-pixel and planning
`/lidar/ground_filtered`	point cloud. Post-GnC viz; check here when filtering may have removed cones
`/lidar/log`	`LidarLog`. Drops, timing, health. Use `ros2 interface show` for fields
`/lidar/raw_points`	when published. Converted returns for debug
`/cone_array`	`ConeArray`. Same centroids, debug only; coloring still uses `/cones`

Parameters

Params file: package config/params.yaml. YAML values are metres; the node converts to millimetres internally.

Parameter	Effect
`x/y/z/radius_cutoff`	Bounding volume before / during processing. Too tight → sparse `/cones`
`height_threshold`, `upper_height_threshold`	GnC keep-band above the fitted ground line
`min_points`, `epsilon`	DBSCAN density. Too high `min_points` or too small `epsilon` → missed cones
`dbscan2_on`, `epsilon2`	Optional second pass on centroids (mostly lidar-dev)

	prod	lidar-dev
Angular segments	32	20
Range bins	10	25

Segment width is $180^\circ / N_{\text{segments}}$ . Finer grids change GnC locality and cost; they are compile-time, not ROS params.

Failure modes

Symptom	Likely cause
No `/cones`, no UDP	Port 2368, ethernet, driver not up
UDP ok, empty `/cones`, empty ground-filtered	Cutoffs, correction, or everything classified as ground
Ground-filtered still has cone-like blobs, empty `/cones`	DBSCAN (`min_points` / `epsilon`)
Steady hz but climbing drops in `/lidar/log`	CPU / ring overflow / competing binders
High process time	Loose cutoffs (too many points through GnC/DBSCAN)

Operator checklist: ops. Stack context: architecture.

Build

cd driverless_ws
colcon build --symlink-install --packages-select custom_ros_driver
source /opt/ros/humble/setup.bash && source install/setup.bash

On trees that renamed the package, select lidar_driver instead.