A LiDAR driver update should pass a regression check on point fields and timestamp semantics before it reaches a robot fleet. A cloud that still looks plausible can hide a changed time unit, missing channel field, different scan boundary, or incompatible consumer assumption. Compare an identified baseline with an identified candidate at the message boundary and in the application.
Start with a written contract: which fields each consumer requires, what their values mean, which clock supplies each timestamp, and how a published cloud relates to acquisition. Then collect comparable evidence from both builds. A release note helps identify where to look, but it does not replace measurements from the sensor and configuration being deployed.
This workflow differs from diagnosing a single distorted map. The FAST-LIO timestamp-unit guide addresses one consumer symptom. Here the goal is a repeatable acceptance record for a driver revision, including changes that do not immediately produce visible distortion.
Freeze the baseline and identify the changed layer
Record sensor model, firmware, SDK revision, driver commit, local patches, compiler and build options, ROS distribution, middleware, launch arguments, network configuration, and consumers. Include calibration and filtering parameters. Save the effective configuration, not just a copy of a template that may not have been loaded.
Keep the previous build available in a separate reproducible workspace or deployment artifact. Avoid installing over the only known working baseline. Record whether the candidate changes the SDK, message definitions, firmware, dependencies, or launch defaults as well as the driver. If these move together, describe the test as a combined change rather than attributing every result to one commit.
Read the official Livox ROS Driver 2 changelog as an example of revision context. Match entries to the actual commits under review. An entry mentioning a fix is not proof that your fleet experienced that defect, and a short changelog does not establish that every downstream contract is unchanged.
Describe the message contract before comparing values
For each output topic, record message type, frame identifier, expected consumer, publication grouping, and required point attributes. The official driver documentation describes its output options and configuration. Select the format applicable to the installed device; do not assume that every driver exports equivalent fields or meanings.
Separate binary layout from semantic interpretation. The PointCloud2 definition describes a binary point array with field descriptors, point and row strides, dimensions, and endianness. It does not define one universal custom per-point time field or guarantee that two differently named timing fields are interchangeable.
| Contract item | Baseline and candidate evidence | Reason to stop deployment |
|---|---|---|
| Field layout | Name, offset, datatype, count, point stride | A required consumer reads the wrong bytes or type |
| Field meaning | Units, reference frame, missing-value convention | Values remain parseable but change interpretation |
| Time | Clock domain, units, origin, header relationship | Unexplained offset, scaling, reset, or boundary change |
| Grouping | Points and acquisition span per cloud | Consumer assumptions no longer match scan construction |
| Consumer output | Same input and settings, comparable application result | Unexplained rejection, drift, stale output, or instability |
Make intentional changes explicit in a migration note. If a field is removed or renamed, specify which consumers require an adapter and how that adapter was checked. A layout difference can be acceptable when every affected consumer is updated and validated; an unexplained difference remains an open regression.
Check field layout with representative messages
Inspect representative outputs from both builds rather than comparing only topic names. Preserve the complete field descriptor list, dimensions, strides, endianness, frame identifier, and sample decoded values. The PointField definition supplies the name, byte offset, datatype, and count used to describe each field.
Check that decoding uses those descriptors rather than a hard-coded structure copied from another driver. Examine valid points, invalid or filtered points, channel identifiers when present, and intensity-related attributes required by the application. Do not assume identical numerical intensity across sensors or configurations without an established contract.
Include more than a convenient stationary wall. Select data containing the ranges, return patterns, and operating modes relevant to the deployment. Keep the scene and sensor settings controlled for live comparisons, and preserve a fixed dataset for consumer comparisons. The point-cloud processing guide provides context for documenting filters and transformations that could otherwise conceal a driver-level change.
Trace timestamp semantics through each conversion
Write down whether each time value is an absolute timestamp or an offset, its unit, its clock domain, and its origin within a scan. Record the relationship between header time, first point, last point, and any acquisition counter. Check reset and restart behavior separately from ordinary continuous operation.
Inspect the installed consumer implementation. For example, the FAST-LIO preprocessing source has distinct handling paths and time conversion logic. That code is evidence about that implementation and revision, not a specification for every LiDAR driver. Pin the source used by the deployed application before comparing its assumptions with the candidate output.
Compare time increments, point ordering, and acquisition span across representative clouds. Interpret apparent discontinuities in the context of packetization, dropped inputs, sensor restarts, and documented wrap behavior. Avoid treating a sorted cloud as proof that the original acquisition order was correct; sorting may hide evidence a consumer needs.
Use the LiDAR and IMU recording checklist to preserve the information needed to inspect timing later. A recording of only the final transformed cloud may omit the upstream evidence needed to distinguish a driver conversion from a consumer conversion.
Test publication behavior and consumers independently
Compare packet reception, driver emission, subscriber receipt, and application output as separate observations. A candidate can publish the expected average frequency while changing cloud grouping or creating bursts. The publish-rate diagnostic helps identify the layer at which the behavior diverges.
Use fixed recorded inputs where the driver supports a documented replay path. If only processed messages are available, replay can check consumers but cannot retest the driver’s packet decoding. State that limitation. Keep playback rate, clock settings, calibration, and application parameters identical between baseline and candidate comparisons.
Then validate live acquisition, including the restart and reconnect conditions the project requires. If clouds appear to flicker, inspect acquisition grouping using the scan-batching workflow. Do not resolve a regression by changing visualization persistence without determining whether required consumers still receive coherent data.
Keep failing examples alongside successful ones. Record the first boundary that differs and the exact artifact used to demonstrate it. This allows a later fix to be tested against the original failure instead of a newly chosen, easier dataset.
Close the update with a decision record
Retain revision identities, input datasets, contract snapshots, test conditions, expected outcomes, observed differences, and the acceptance decision. Define project-specific tolerances before inspecting candidate results. Keep unresolved differences visible, including those that appear harmless in one scene. Pilot the accepted build under the team’s deployment process before expanding it across the fleet.
Must every field be numerically identical?
No. Live scenes differ, and deliberate corrections can change values. The requirement is that the format and meaning remain compatible or have a documented, tested migration, while application results satisfy the agreed criteria.
Can a changelog and a clean build replace regression data?
No. They establish useful provenance and build evidence. Preserve representative messages and consumer results so another engineer can inspect what changed and reproduce the acceptance decision.
