Ops

Bring-up and failure checks for the live LiDAR-first stack. Graph and topics: architecture.

Bring-up

1. Source ROS and the workspace. Confirm UDP 2368 is free.
2. Start custom_ros_driver (prod package name) with its params file.
3. Health checks:
   • ros2 topic hz /cones non-zero near the configured frame rate
   • ros2 topic echo /lidar/log --once (drop counters not climbing rapidly)
   • /lidar/ground_filtered shows ground removed and cone-like returns remaining
4. Confirm /filter/twist is publishing.
5. Start point_to_pixel with src/point_to_pixel/config/params.yaml.
6. Confirm /associated_colored_cones. For history debug, set publish_pre_cone_history_debug=true to also publish /colored_cones.

Typical viz set: /cones, /lidar/ground_filtered, /associated_colored_cones, camera images (with projection overlay when available).

Missing or sparse /cones

Classifier checks are useless until /cones is healthy.

Check	Pass	Fail direction
LiDAR power / ethernet / port	packets arriving	free UDP 2368; check link
ros2 topic hz /cones	steady	driver down or all points filtered
/lidar/ground_filtered density	cone-like clusters remain	GnC thresholds or range cutoffs
x/y/z/radius_cutoff	cones inside box	widen box (YAML values are meters)
min_points / epsilon	clusters form	lower min_points; inspect DBSCAN
Correction	angles sane	load .dat for bags; PTC TCP 9347 live

Wrong colors

1. Verify positions on /lidar/ground_filtered.
2. Compare /colored_cones (pre-history) and /associated_colored_cones (post-history).
3. Systematic projection miss: matrices / calibration (physical calibration).
4. Projection on cones but wrong class: YOLO class map, confidence, lighting; HSV ranges only on HSV builds.
5. One camera wrong: that side’s matrix, undistort YAML, or right-camera 180° rotate.
6. Correct at rest, wrong in motion: /filter/twist or imu_to_lidar.

History / flicker

Enable publish_pre_cone_history_debug. Pre-history flicker implicates projection or classification. Stable pre-history with unstable post-history implicates history.

On prod, history votes colors, associates tracks, and orders cones. It does not republish unseen cones across gaps. Gap-fill is on feature/perc/propagate_history. See cone history.

Latency and drops (/lidar/log)

Monitor /lidar/log during drive or replay.

Symptom	Likely causes
Rising packet drops	CPU contention, ring overflow, UDP conflict, network
High processing time	Loose cutoffs (too many points through GnC/DBSCAN)
Sporadic empty frames	Sequence gaps, sync, correction

Field names follow the built LidarLog.msg. Use ros2 interface show on the installed type.

Projection offset

Pattern	Likely cause
Constant offset while stopped	Extrinsics, wrong params.yaml, wrong camera YAML
Offset only when moving / yawing	Twist gap, empty image deque, imu_to_lidar
Distortion near image edges	Intrinsics or YAML size ≠ 1920×1200

Procedure: physical calibration. Extrinsic gather scripts subscribe to sensor_msgs/PointCloud2 on /lidar_points (vendor Hesai or bridge). The live cone driver publishes interfaces/msg/Points on /cones / /lidar/raw_points and does not satisfy that subscription.

Harness reference drift

Available on feature/perc/bag-extractor only.

Exit	Meaning
0	Pass
1	Metric or reference drift. Inspect run.json; re-run; update the reference only after intentional review.
2	Scenario or config error
3	Extraction, replay, or readiness failure (infrastructure)

See regression harness.