Two weeks of field debugging, then a one-line fix in the protocol document. That is the usual ratio when a rangefinder integration goes wrong. The laser is rarely the problem — the bytes around it are.
Here are the five things that break integrations, in the order they usually bite.
1. Endianness, and the number that is silently wrong
A range value spans two or four bytes. If the document says "distance, 2 bytes" and stops, the host and the module can disagree about byte order and still produce a number — just a wrong one. 0x0B B8 is 3000 in big-endian and 0xB80B (47115) in little-endian. Both are legal integers. One is 3 metres, the other is 47 kilometres.
Symptom: ranges that jump by a factor of ~15.6 when the low byte happens to be large.
Fix: demand the byte order in writing, and test with a known short distance where the two readings differ.
2. Checksum coverage: which bytes, exactly
"Checksum over the message" is not a specification. It has to state:
- the algorithm (sum, XOR, CRC-8/16, which polynomial)
- the seed / initial value
- whether the checksum byte itself and the start bytes are covered
- whether it is computed before or after byte-stuffing, if stuffing exists
Off-by-one in coverage produces a link that works for one command length and fails for another — the worst kind of bug, because it looks like an intermittent hardware fault.
3. What happens mid-measurement
A command that arrives while the module is still integrating has three plausible behaviours: it is queued, it is dropped, or it aborts the measurement and replies with something. If the document does not say which, the host software will be written against the wrong one.
Related: the minimum interval between commands. Modules that need 200 ms of integration will not answer faster than that, and sending faster does not produce errors — it produces stale or missing answers.
4. Resynchronisation after a dropped byte
A UART link loses bytes. What does the host do when a frame arrives short? If the protocol has no reliable frame boundary (a start byte pair, or a length field plus terminator), the parser cannot tell a truncated frame from a valid short one, and the stream stays misaligned until the host is restarted.
The document must state the resync rule explicitly: flush until the next start marker, discard the partial frame, resume.
5. Error codes that nobody can act on
"Error 0x03" with no cause attached is not an error code, it is a puzzle. Useful error sets distinguish at least:
- no return detected
- return detected but ambiguous (two echoes, e.g. through glass or vegetation)
- target too close
- target too far
- supply out of range
- internal temperature out of range
The last two matter more than they look: a module that quietly returns garbage below −20 °C will be blamed for a positioning bug months later.
An example exchange, and why it belongs in the document
Nothing in a protocol document saves as much integration time as one complete transcript:
TX 55 AA 04 01 00 05 start, len, cmd=measure, arg=0, checksum
RX 55 AA 07 81 0B B8 00 12 start, len, cmd|0x80, distance=0x0BB8, status=0x00, checksum
Nine bytes of example explain more than three pages of prose, because it forces the author to state the frame layout unambiguously.
I put the full list of twelve items a protocol document must state into a checklist. Send it to any supplier before you write a driver — the ones who can answer all twelve have shipped to integrators before.
The general rule
Every ambiguity in a protocol document becomes an experiment in your lab. An experiment costs a day; a sentence in the document costs nothing. If a supplier cannot produce the sentence, treat that as information about how the rest of the project will go.
I keep an open dataset of rangefinder and single-point lidar modules at specs.erdilrf.com — 59 modules with the manufacturer's test conditions attached to every range figure, plus the interface and optics tables. JSON and CSV, CC BY 4.0, no signup. The answers section covers the buyer questions that keep coming up.
If any of the five above has bitten you with a specific module, I would like to hear which one — the failure modes are the interesting part.
Top comments (1)
Point 2 is the one I'd underline. "Checksum over the message" without the coverage is common in device protocols, and when all you have is captured frames you end up brute-forcing it: every algorithm over every start and end offset until one matches all the frames. I built a small browser tool for exactly that (crtdrops.mx/checksum), because the coverage question kept coming back with undocumented trackers.
On point 4, the resync rule matters on TCP too, not just UART: a read is not a frame, and a parser that assumes one read per frame stays misaligned the same way after a split or coalesced segment.
Which of the twelve items do suppliers miss most often in your dataset?