UWB firmware logs tell you what happened at the application layer. They don’t tell you why.
A session that failed to establish, a ranging distance that’s consistently 30 cm off, a session that runs for exactly twelve exchanges before dropping. Each of these looks like a different problem from the application layer. At the protocol layer, visible only in an over-the-air packet capture from a UWB sniffer, each has a distinct, diagnosable cause.
The UWB Alliance promotes interoperability across the UWB ecosystem, but interoperability problems are exactly the class of bug that logs from a single device can’t catch: the issue lives in the exchange between devices, in the protocol state machine, in the timing between frames. Six of those bugs appear repeatedly across FiRa, CCC Digital Key, and IEEE 802.15.4z development programmes. All six are invisible without a protocol capture. All six are diagnosable in minutes once the frames are visible.
How to use this article
The checklist table below maps each bug to its observable symptom (what engineers see in logs and test outputs) and what the protocol capture reveals. Read across the row to identify bugs that match what you’re currently seeing, then read the detailed section for diagnosis and resolution guidance.
Score your current UWB programme: how many of these symptoms are active, unresolved, or have been resolved by workaround rather than root cause?
| # | Bug | What logs and test outputs show | What the UWB sniffer reveals |
|---|---|---|---|
| 1 | OOB parameter mismatch | Session init never completes; first UWB exchange never happens | Which BLE characteristic carried the wrong preamble code, channel, or STS key |
| 2 | TWR round timing offset | Ranging distance consistently 20–50 cm off across all conditions | Treply timestamp mismatch between Initiator and Responder in MAC headers |
| 3 | FiRa session mode conflict | Ranging round timeout; no distance output despite active radio | Ranging mode mismatch in MAC header: DS-TWR frames answered as SS-TWR, or vice versa |
| 4 | CCC frame hopping break | Session drops after a fixed number of ranging exchanges | Device on wrong channel after key rotation; hop-sequence derivation error visible in frame sequence |
| 5 | STS counter desynchronisation | Ranging output becomes zero or wildly inconsistent after reset or key rollover | STS integrity flag fails in captured frames; counter divergence visible against expected sequence |
| 6 | First-path vs strongest-path selection error | Ranging error 1–3 m in reflective indoor environments; error worsens with surface proximity | CIR data shows secondary multipath peak being selected over first-arriving path |
Bug 1: Out-of-band parameter mismatch
What you see without a sniffer: The UWB session init command returns success on both devices. The BLE exchange appears to complete normally. No UWB ranging data arrives. The application reports “session established, no ranging response” or a ranging timeout on the first round. Rebooting one device sometimes resolves it; power-cycling both devices together always resolves it, which suggests a synchronisation issue without indicating where.
What the protocol capture reveals: FiRa, CCC Digital Key, and Aliro all exchange UWB session parameters out-of-band before the first UWB packet. A BLE companion observing that exchange (capturing the BLE characteristics that carry channel, preamble code, STS mode, STS key seed, and session ID) makes the mismatch immediately visible. Common findings: one device reads the preamble code from a BLE characteristic before it’s been written by the other device (race condition on session parameter distribution); the channel field is written in a different byte order by the two stacks; the STS key is truncated to the wrong length.
Resolution path: Without the capture, this bug typically costs 2–4 days of log correlation across two devices and hypothesised parameter logging added to both stacks. With the BLE companion in the UWB sniffer, the exact characteristic and byte sequence are visible in seconds.
Protocol detail: FiRa session setup uses BLE GATT services to distribute the RangingParameters object. The object contains at minimum the session ID, ranging method, channel, preamble code, STS configuration, and slot duration. Any of these fields being read before write, truncated, or byte-swapped produces silent failures at the UWB layer: the UWB MAC receives parameters that don’t match the peer’s expectations, and the session never produces a ranging round.
Bug 2: TWR round timing offset
What you see without a sniffer: Ranging output is stable and consistent, but biased: consistently 25 cm too far, or consistently 18 cm too close, across all test distances and both devices. The offset doesn’t change with distance, environment, or antenna orientation. It looks like a hardware calibration issue. The silicon vendor’s calibration tool says the antenna delay is correct.
What the protocol capture reveals: In Double-Sided Two-Way Ranging (DS-TWR), the ranging calculation uses four timestamps: T₁ (Initiator transmit), T₂ (Responder receive), T₃ (Responder transmit), T₄ (Initiator receive). The Responder’s reply time (the time from T₂ to T₃, called Treply) is encoded in the Final frame that the Initiator receives. If the Responder calculates Treply using a clock domain that’s offset from the radio timestamp domain, the ranging formula produces a systematic bias proportional to the error.
A Wireshark capture with a FiRa dissector shows T₃ and T₂ in named fields. fira.treply_responder is human-readable in the frame detail pane. Comparing this against the actual T₂ and T₃ timestamps decoded from the Initiator’s corresponding Response and Final frames immediately shows whether the encoded Treply matches the actual elapsed time. A difference of 1 µs in Treply produces approximately 15 cm of systematic ranging error.
Resolution path: This bug is frequently attributed to antenna delay calibration because the symptom looks identical to a delay constant error. The capture distinguishes them: an antenna delay error produces an offset proportional to the two-way time of flight (and therefore scales slightly with distance); a Treply encoding error is a fixed offset independent of distance. Checking the MAC header fields takes five minutes once the frames are visible.
Protocol detail: DS-TWR in 802.15.4z sends three frames per ranging round: Poll, Response, and Final. The Final frame carries Treply_Initiator (time from sending Poll to receiving Response) and the Responder’s reply time (from receiving Poll to sending Response). If the firmware computes Treply from application timestamps rather than radio hardware timestamps, the offset introduced by API call latency becomes a systematic ranging error.
Bug 3: FiRa session mode conflict
What you see without a sniffer: The UWB session init succeeds. Both devices report active sessions. The radio is transmitting, confirmed by the fact that one device sees power on the expected channel. No ranging distance is produced. The application reports “ranging round timeout” on every attempt. Incrementally enabling FiRa parameters (channel, STS mode, slot count) doesn’t isolate the issue.
What the protocol capture reveals: FiRa defines multiple ranging modes: SS-TWR (Single-Sided Two-Way Ranging), DS-TWR, OWR for AoA (One-Way Ranging for Angle of Arrival), DL-TDoA, and UL-TDoA. The ranging mode is negotiated during session setup. If the Controller configures DS-TWR but the Controllee’s firmware defaults to SS-TWR, the session runs but frames are mismatched: the Controllee responds to Poll frames as though expecting an SS-TWR Response, not a DS-TWR Response, so the Final frame that completes the DS-TWR exchange never arrives at the Controller.
The UWB sniffer shows the MAC header Ranging Mode field in the Poll frame (sent by the Initiator) and whether the Responder replies with the correct frame type. A DS-TWR session should produce three frames per round: Poll → Response → Final. An SS-TWR session produces two: Poll → Response. Seeing two frames where three are expected in a session configured for DS-TWR identifies the mismatch immediately.
Protocol detail: The FiRa MAC specification defines RangingRound structures that differ between modes. Mismatches occur most often when one stack is updated to support DS-TWR and the corresponding peer stack hasn’t been updated. Apple’s Nearby Interaction framework uses FiRa-compatible UWB sessions, so a session mode mismatch between a host device and an accessory produces the same ranging timeout on production consumer hardware as it does in the lab.
Bug 4: CCC Digital Key frame hopping break
What you see without a sniffer: A CCC Digital Key session starts correctly and produces valid ranging distances for a fixed number of exchanges (typically 10 to 30) and then drops without warning. The application log shows “session terminated: no response” on what appears to be a normal ranging round. Restarting the session from BLE produces the same failure at approximately the same exchange count.
What the protocol capture reveals: CCC Digital Key uses frame channel hopping for security: each ranging round occurs on a different UWB channel, with the hopping sequence derived from the session keys. If the device under test’s hopping sequence derivation diverges from its peer’s (typically after a key rotation event, a counter overflow, or a rounding error in the hopping function), subsequent frames are sent on a channel the peer isn’t monitoring.
With the UWB sniffer set to follow-the-hop mode (using the session key to compute the expected sequence), the capture shows exactly where the hop sequence diverges: the last successfully received frame is on channel X, the next expected channel is Y, and the device transmits on Z. The failure is pinpointed to a specific exchange number and associated with the key material in use at that round.
Protocol detail: The CCC Digital Key Phase 2 specification defines the hopping sequence as a function of the session ID, the round counter, and the UWB Configuration Parameters (UCP) exchanged during the BLE setup phase. The sniffer’s CAN adapter extracts the session key from the vehicle network; the BLE companion captures the UCP. Together they allow the expected hop sequence to be computed and compared against the observed sequence in real time.
Bug 5: STS counter desynchronisation and the IEEE 802.15.4z ranging failure that looks like a radio fault
What you see without a sniffer: Ranging output degrades or goes to zero after a device reset, a power cycle that didn’t reset both devices simultaneously, or after a defined number of ranging rounds that corresponds roughly to a counter overflow boundary. The session remains active. The radio is transmitting. The application receives no valid ranging data.
What the protocol capture reveals: In IEEE 802.15.4z STS modes 1, 2, and 3, the Scrambled Timestamp Sequence is seeded by an AES-128 key and an STS counter that both devices must increment in lockstep. If the counter diverges (because one device was reset without resynchronising the counter, because a counter overflow is handled differently by the two stacks, or because a key rotation did not complete atomically), the receiving device’s STS correlator produces no valid output.
A UWB sniffer with STS integrity detection shows this as a stream of frames with failed STS validation. The sniffer can flag STS integrity failures without holding the decryption key: the STS correlator simply fails to lock, and the sniffer reports the failure rate. With key injection, the expected STS sequence is visible alongside the received sequence, and the exact counter value at divergence is readable in the frame detail.
Protocol detail: The IEEE 802.15.4z STS counter is a 32-bit value that increments per ranging round. A counter reset to zero while the peer is at counter value N means subsequent frames are generated with counter N+1, N+2… while the peer expects counter 1, 2…. The frames arrive correctly at the RF layer: timing looks fine, signal strength is normal, but the STS validation fails silently, producing no ranging output. Without a capture that shows the STS integrity flag, this looks identical to a total radio failure.
Bug 6: First-path vs strongest-path selection error
What you see without a sniffer: Ranging output is consistent in an open-field test environment but degrades in a real deployment: errors of 1–3 m in a warehouse, an office with glass partitions, or an automotive interior. The error worsens as the device moves closer to reflective surfaces. The silicon vendor’s antenna delay calibration is correct. The firmware team concludes this is a physics problem and adjusts their accuracy specification.
What the protocol capture reveals: UWB ranging accuracy depends on measuring the time of arrival of the first-arriving signal path, which is the direct line-of-sight signal from transmitter to receiver. In reflective environments, later-arriving signal components reflected off walls, floors, and objects arrive after the first path but often with higher energy. If the receiver’s leading-edge detection algorithm selects the strongest arriving component rather than the earliest arriving component, the measured time of arrival is later than the actual time of flight, typically 1–5 ns, corresponding to 30 cm to 1.5 m of ranging error.
Channel Impulse Response (CIR) data (the time-domain representation of all received signal components) is not available through vendor firmware logs. A UWB sniffer with per-frame CIR capture outputs the full multipath profile for each ranging round. Plotting the CIR shows the first-path peak (at the correct time of arrival) and the stronger reflected peak (later) that the algorithm selected. The firmware team can then tune the leading-edge threshold or apply a first-path detection algorithm calibrated against the deployment environment.
Protocol detail: First-path vs strongest-path selection is controlled by the receiver’s CIR analysis algorithm, which is typically implemented in firmware running on or alongside the UWB transceiver. The capture provides the per-frame CIR data that makes calibration possible without building a custom test jig.
needCode’s Modular UWB Sniffer captures FiRa, CCC Digital Key, Aliro, and IEEE 802.15.4z traffic with BLE and CAN out-of-band session capture, STS decryption, per-frame CIR data, and Wireshark integration with named protocol fields. The tool was built across eight years of production UWB firmware work inside Qorvo, which is why it decodes the bugs described above rather than just capturing raw frames. If any of the six bugs in this article are currently active on your programme, or if your team is approaching pre-certification testing and wants to know what a packet capture session would reveal, we are happy to talk.
Book a free discovery call or get in touch
Frequently asked questions
A ranging failure means no distance output is produced: the session doesn’t complete, the ranging round times out, or the output is zero. A ranging error means a distance is produced but it’s wrong. The debugging approach differs: failures are usually protocol-layer issues (session setup, frame exchange, STS validation), while errors are often timing or signal-processing issues (Treply bias, first-path selection, antenna delay). Bugs 1, 3, 4, and 5 in this article are failure-class bugs; bugs 2 and 6 are error-class bugs.
For IEEE 802.15.4z STS debugging, two sniffer capabilities are essential. First, STS integrity detection: the ability to flag frames where the STS correlator fails to lock, even without the session key. This identifies counter desynchronisation (Bug 5) as a pattern without key injection. Second, key injection: providing the AES-128 session key to the UWB sniffer so it can generate the expected STS sequence and show the exact counter value at divergence. Bugs 4 (frame hopping break) and 5 (STS counter desync) both require key injection for full diagnosis. Bugs 1, 2, 3, and 6 are diagnosable without it, because the relevant data is in the MAC header or CIR data rather than the encrypted STS payload.
Some can, some can’t. OOB parameter mismatches (Bug 1) and TWR timing offsets (Bug 2) are reliably reproducible in any test configuration. Frame hopping breaks (Bug 4) depend on reaching the key rotation event, which may take minutes of continuous ranging. First-path vs strongest-path errors (Bug 6) require a reflective environment; they’re invisible in an anechoic chamber or open-field test. STS counter desynchronisation (Bug 5) requires deliberately resetting one device without synchronising the other. A UWB sniffer is the only way to confirm root cause regardless of reproducibility.
No. Four of the six bugs (OOB mismatch (1), TWR timing offset (2), FiRa mode conflict (3), and first-path error (6)) are diagnosable without decrypting the STS, because the diagnostic information is in the MAC header or the CIR data. CCC frame hopping break (Bug 4) requires key injection to compute the expected hop sequence. STS desynchronisation (Bug 5) can be flagged as a pattern by integrity detection without keys, but the exact counter value at divergence requires key injection.
CIR data from UWB transceivers is not a standard output in vendor SDKs. It requires access to the baseband processing layer, which is implementation-specific. A UWB sniffer that supports per-frame CIR capture does so by integrating directly with the UWB hardware at a level below the application firmware interface. This is a hardware-level capability, not a software feature that can be added to a generic SDR.
The bugs are protocol-layer issues, not chipset bugs. OOB parameter mismatch is a stack integration issue that appears regardless of silicon vendor. TWR timing offset occurs when application-layer timestamps are used for Treply rather than hardware radio timestamps, a firmware architecture decision. FiRa mode conflict depends on implementation compliance. CCC frame hopping is defined entirely by the CCC specification. STS desynchronisation is a counter management issue at the firmware level. First-path selection is an algorithm choice implemented in firmware. All six can appear on Qorvo, NXP, Samsung LSI, or any other UWB silicon.
Further reading
- UWB Sniffer Buyer’s Guide (2026): Comparing Protocol Analyzers for FiRa, CCC, and IEEE 802.15.4z Development: the evaluation guide for choosing a UWB protocol analyzer, covering criteria, option comparison, and use case mapping for each bug type in this article.
- Basics of UWB Indoor Location Systems (Indoor RTLS): system-level context for UWB RTLS, covering TWR vs TDoA, anchor placement, and accuracy budgets. Relevant for understanding Bug 6 in positioning deployments.
- IEEE 802.15.4ab vs IEEE 802.15.4z: What’s Changing in Ultra-Wideband: protocol changes in the 802.15.4ab amendment that affect sniffer requirements.
- Automated Testing and CI/CD for Embedded Wireless: how protocol capture integrates into HIL and CI pipelines, turning the sniffer from a bench tool into an automated regression gate.
