Skip to content

DEV-1251: HIL saves each run's Bluetooth bytes as a replayable trace (-CaptureBytes) - #131

Merged
JongChern merged 4 commits into
DEV-1242_android_hilfrom
DEV-1251_hil_byte_capture
Oct 23, 2026
Merged

JongChern merged 4 commits into
DEV-1242_android_hilfrom
DEV-1251_hil_byte_capture

Conversation

@JongChern

Copy link
Copy Markdown
Contributor

Stacked on #128 (base DEV-1242_android_hil). After #128 merges, retarget this to master before deleting DEV-1242_android_hil: deleting a PR's base branch closes the PR.

Why

The HIL finds defects that only real hardware shows. A finding stays fixed only once its bytes are a byte-level test that runs anywhere, without a phone or a unit, such as shimmer-logandstream's replay traces. This adds the step that captures those bytes.

What

run-android-hil.ps1 -CaptureBytes saves the bytes exchanged with each unit in each run as <unit>_<transport>_<scenario>.bytes.log. That is shimmer-logandstream's trace format (tests/data/*.bytes.log, read by load_session):

15:00:16.200  TX h14 [0x03]
15:00:16.241  RX h14 [0xFF 0x04 0x80 0x02]
  • BLE: ATT writes (TX) and notifications (RX). The write that turns notifications on is left out, as in the recorded traces.
  • Classic: RFCOMM payloads, kept as the radio delivered them, so a bug that depends on how bytes arrive replays the same way. L2CAP fragments are reassembled.

How it works:

  • Source: the phone's Bluetooth HCI snoop log. It is switched on once in Developer options, followed by a Bluetooth restart; adb can do neither. The runner asks the Bluetooth service which mode it started with (mSnoopLogSettingAtEnable), and refuses to start unless that is full. On Android 11 adb can't read the setting itself.
  • Collection: after the runs, one bug report brings the log out, because adb can't read it any other way on an unrooted phone. Only btsnoop_hci.log is kept; the bug report is deleted from the PC and the phone.
  • Extraction: tools/hil/btsnoop_to_trace.py (standard-library Python) cuts out each run's bytes, by the unit's MAC and the run's time window. Android stamps the snoop log in local time, which it allows for.
  • Reuse: summary.json keeps each run's window and the phone's UTC offset, so the bytes can be cut out again later.
  • No effect on verdicts: if capturing fails, the runner says so and carries on.

Documented in tools/hil/README.md under "Capturing the bytes".

Tested

  • python -m unittest test_btsnoop_to_trace: 5 of 5 pass, on a synthetic snoop log. It covers:
    • a BLE session with a notification split across ACL fragments;
    • the notification-subscription write, which is dropped;
    • another device's traffic, which is filtered out;
    • Classic RFCOMM with a 2-byte length and a credit byte, plus a control-channel frame that is dropped;
    • time windows;
    • logs stamped in local time and in UTC.
  • On the bench: Xiaomi M2101K6G (Android 11), Shimmer3R EC:06:D8:0D:86:F8 over BLE, streamRest and midStreamSet. Every sample the Android API delivered is a CRC-valid packet in the captured bytes, in the same order: 7607 of 7607 and 5273 of 5273.
  • That capture also showed that the DEV-1245 out-of-order timestamps come from the firmware itself. The raw ticks are on DEV-1245.
  • Not yet tested over Classic: the bench Shimmer3 is hung (DEV-1246). The Classic path has only the unit tests.

Limits

  • Android keeps only the current snoop log and the one before it, so capture a few runs at a time (-Unit, -Scenario).
  • A bug report adds about 3 minutes.
  • btsnoop/ holds all the phone's Bluetooth traffic. It stays in the gitignored run folder.

🤖 Generated with Claude Code

JongChern and others added 2 commits October 20, 2026 14:06
…ytes)

A HIL finding is only fixed for good once its bytes are a byte-level test.
With -CaptureBytes the runner notes the phone's clock around each run, takes
one bug report at the end (the only way adb can read the HCI snoop log on an
unrooted phone), keeps btsnoop_hci.log, deletes the bug report from the PC and
the phone, and cuts out each run's bytes by the unit's MAC and time window.

btsnoop_to_trace.py writes shimmer-logandstream's trace format
(tests/data/*.bytes.log): BLE ATT writes and notifications, and Classic RFCOMM
payloads as the radio delivered them, with L2CAP fragments reassembled. It is
standard-library Python with unit tests on a synthetic snoop log. Capturing
is diagnostic only and never changes a verdict.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
… force

Found on the first real capture (Xiaomi, Android 11):
- Android stamps btsnoop_hci.log in the phone's local time, so every run's
  window missed its bytes by the UTC offset. The extractor now takes the log
  as local time by default (--snoop-clock utc for one that isn't).
- adb cannot read persist.bluetooth.btsnooplogmode on Android 11, so the
  runner asks the Bluetooth service which mode it started with
  (mSnoopLogSettingAtEnable), which is also the one actually in force.
- summary.json keeps each run's capture window and the phone's UTC offset,
  so the bytes can be cut out of btsnoop/ again later.

Verified on a Shimmer3R over BLE: every sample the API delivered in
streamRest (7607) and midStreamSet (5273) is a CRC-valid packet in the
captured bytes, in the same order.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Copilot AI lite review requested due to automatic review settings October 20, 2026 07:13

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved moderate issues affect trace correctness, metadata persistence, failure handling, and test coverage.

2 open issues
What changed in this PR

Adds optional Android HIL Bluetooth snoop capture and conversion into replayable BLE and Classic trace files.

Changes:

  • Adds HCI parsing, run-window extraction, and capture orchestration.
  • Records metadata and documents replay workflows.
  • Adds synthetic parser tests and Python cache exclusions.
File Summary
tools/​hil/​test_btsnoop_to_trace.py Adds parser coverage; one time-window assertion does not test the intended boundary.
tools/​hil/​run-android-hil.ps1 Integrates capture and extraction; metadata properties and archive failures need corrective handling.
tools/​hil/​README.md Documents capture setup, output, and replay usage.
tools/​hil/​btsnoop_to_trace.py Parses BLE and Classic traffic; notification-handle detection must be scoped per connection.
.gitignore Ignores Python cache files.

Review effort: Lite

Comment thread tools/hil/btsnoop_to_trace.py Resolved
Comment thread tools/hil/run-android-hil.ps1 Resolved
…e bug report

- The notification-on write is matched only against notifications on the
  same connection: ATT handles belong to one connection, so after a
  reconnect a real 2-byte command could be dropped (new test; it fails on
  the old filter).
- If the bug report can't be read, say so and still delete it from the PC
  and the phone; it holds the phone's whole state.
- The time-window test now checks both ends at the record that completes
  the notification.
- summary.json's extra fields use Add-Member's named parameters (the
  positional form worked; this is for readability).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Copilot AI lite review requested due to automatic review settings October 20, 2026 07:26

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Four unresolved moderate findings affect RFCOMM parsing, filtering, test coverage, and Python 3 selection.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Medium severity Decode RFCOMM extended length with the EA bit shifted

tools/​hil/​btsnoop_to_trace.py:209

The extended RFCOMM length is decoded incorrectly: the second length octet includes the EA bit in bit 0, so it must be shifted right before combining. With a standard frame carrying 130 bytes, this computes 386 instead of 130 and the slice at line 212 includes the trailing FCS byte in the replay payload (the test helper uses the same non-standard encoding, so it does not catch this). Decode the high length bits as pdu[3] >> 1 and add a standard extended-length fixture.

Medium severity Encode standard RFCOMM extended length in the test fixture

tools/​hil/​test_btsnoop_to_trace.py:57

This fixture encodes the extended RFCOMM length with n >> 7 directly, but the second octet's low bit is the EA bit and the high length bits start at bit 1. As a result the 130-byte test frame uses a non-standard [0x04, 0x01] length and cannot expose the decoder bug; encode the standard EA-bearing octet and assert that the FCS is excluded.

2 resolved since last review

Review effort: Lite

A review read the second length octet as carrying an EA bit. It doesn't:
Linux sends a long length as len << 1, little-endian over two octets
(__len16), so 130 is [0x04, 0x01] and the high octet is len >> 7 whole, as
the extractor decodes it. Comments now say so, and the test builds the
length the way Linux does. No change in behaviour.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Copilot AI lite review requested due to automatic review settings October 20, 2026 07:32

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Four moderate review findings remain unresolved.

No open issues 🎉

Review effort: Lite

@JongChern
JongChern merged commit e067a85 into DEV-1242_android_hil Oct 23, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants