feat(protocol): multi-band support — WHOOP 5 (gen5) framing + records

[abdulsaheel]

Summary

Adds WHOOP 5 (gen5 / "fd4b") support to the pure-Dart protocol library. The key finding: WHOOP 5 is WHOOP 4 in a different envelope — only the outer frame header changes, so this is a small, well-bounded BandProfile abstraction rather than a second protocol.

	WHOOP 4 (gen4)	WHOOP 5 (gen5)
Frame header	4-byte [AA][u16 size][crc8]	8-byte [AA][01][u16 size][00][01][crc16-modbus]
Payload CRC	CRC32	CRC32 (same)
Command opcodes	—	shared, except HELLO → 0x91
GATT base	6108000x-…	fd4b000x-…
1 Hz record	rich R24	thin K24 (HR + timing)

Changes

• crc.dart — crc16Modbus (verified 0x71E6 on the gen5 hello header).
• band.dart (new) — DeviceType, BandProfile, GattProfile.
• framing.dart — buildFrame/parseFrame/FrameReassembler take a BandProfile, defaulting to gen4 → WHOOP 4 byte-identical.
• commands.dart — gen5ClientHello() (reproduces the canonical hello byte-for-byte), gen5 empty-payload offload helpers; profile threaded through command + history-result builders.
• records.dart — parseGen5Record: thin K24 (HR@17 + timing). Motion uses the existing R10 offsets; SpO2/temp/RR honest-null pending validated offsets (never fabricated).

Testing

dart test → 87 pass (16 new gen5 cases + all 2934 TS-parity cases). No WHOOP 4 regression. The gen5 decode path was additionally validated end-to-end against a real WHOOP 5.0 owned capture (HR/counter/timestamp decode correctly; CRC16+CRC32 both check out).

Notes

• SpO2 %, ECG, pulse-info, battery-pack telemetry are recognized but deferred.
• Clean-room / facts-only; corroborated against our own PROTOCOL_FINDINGS.md.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added support for Gen 5 band profiles, framing, GATT details, CRC validation, and command generation.
  • Added Gen 5 client handshake, data-range, historical-transfer, and record-decoding capabilities.
  • Preserved Gen 4 behavior while enabling profile-specific frame parsing and reassembly.
• Bug Fixes
  • Improved detection of invalid frame headers and implausible historical heart-rate values.
• Tests
  • Added comprehensive coverage for Gen 4 and Gen 5 framing, commands, CRCs, reassembly, and record decoding.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds gen5 support across GATT profiles, CRC16-Modbus framing, command builders, streaming reassembly, historical record decoding, public exports, and end-to-end protocol tests while preserving gen4 defaults.

Changes

Gen5 protocol support

Layer / File(s)	Summary
Generation profiles and CRC contracts lib/src/band.dart, lib/src/crc.dart, test/gen5_test.dart	Defines gen4/gen5 GATT and framing profiles, header layouts, generation-specific CRC validation, and CRC/profile tests.
Profile-driven frame parsing and reassembly lib/src/framing.dart, test/gen5_test.dart	Builds and parses profile-specific frames, validates header and trailing CRCs, and reassembles partial gen5 frames while retaining gen4 defaults.
Generation-aware commands and public exports lib/src/commands.dart, lib/openstrap_protocol.dart, test/gen5_test.dart	Adds profile-aware history commands, gen5 handshake/offload builders, public exports, and gen5 ACK validation.
Gen5 history decoding and public API lib/src/records.dart, lib/openstrap_protocol.dart, test/gen5_test.dart	Adds validated thin-history record decoding for supported gen5 versions and tests field extraction and rejection cases.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant BandProfile
  participant buildFrame
  participant FrameReassembler
  participant parseFrame
  BandProfile->>buildFrame: build a generation-specific header
  buildFrame-->>FrameReassembler: deliver framed command or history data
  FrameReassembler->>parseFrame: parse complete frame after buffering
  parseFrame->>BandProfile: validate profile header and declared length
  parseFrame-->>FrameReassembler: return validated inner payload

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding multi-band WHOOP 5 framing and record support to the protocol library.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/multiband-whoop5

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

lib/src/commands.dart (1)

18-30: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Align buildCommand with the named profile convention.
buildCommand is the only builder that makes profile positional, so callers have to pass payload first just to override the frame profile. Make it a named parameter like the other helpers, and update the buildHistoryResultFail call to use profile: too.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/src/commands.dart` around lines 18 - 30, Update buildCommand so profile
is a named parameter while preserving payload as the existing positional
optional argument and retaining the default BandProfile.gen4 value. Update the
buildHistoryResultFail call site to pass the selected profile using the profile:
named argument.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@lib/src/commands.dart`:
- Around line 18-30: Update buildCommand so profile is a named parameter while
preserving payload as the existing positional optional argument and retaining
the default BandProfile.gen4 value. Update the buildHistoryResultFail call site
to pass the selected profile using the profile: named argument.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4c916b9c-27bd-496a-8453-a7691ba41f90

📥 Commits

Reviewing files that changed from the base of the PR and between 02fc8e5 and 687aa46.

📒 Files selected for processing (7)

• lib/openstrap_protocol.dart
• lib/src/band.dart
• lib/src/commands.dart
• lib/src/crc.dart
• lib/src/framing.dart
• lib/src/records.dart
• test/gen5_test.dart

[dannymcc]

Cross-checked the gen5 framing here against two independent public WHOOP RE efforts (a WHOOP 4.0 findings write-up and a WHOOP 4.0/5.0 iOS+Rust decoder) and it lines up byte-for-byte. A few things I confirmed independently:

• CRC-16/Modbus header + CRC-32 payload — re-derived both over the CLIENT_HELLO frame aa0108000001e67123019101363e5c8d: header [0:6] → 0x71E6 (matches [6:8]) and crc32(inner) → 0x8d5c3e36 (matches the trailer). declared@[2:4] = 8, total = declared + 8 = 16. Exactly as implemented.
• GATT fd4b family + GET_HELLO = 0x91 — matches the other reference's service map and handshake.
• The honest-null parseGen5Record matches what those sources found too: the gen5 1 Hz record really is thin (HR only), motion rides separate K10/K21 streams with gen4-identical accel/gyro offsets, temperature comes via the TEMPERATURE_LEVEL event (id 17) rather than the record, and beat timing lives in the R17 optical stream, not RR in the 1 Hz record. Good call not fabricating those.

One future surface, not blocking: packet type 0x10 (R22) is WHOOP 5.0's realtime HR+battery path (battery u8 @ [1], hr_milli_bpm u16 LE @ [2:4] ÷ 10). Worth flagging that in the sources I checked it's only documented from a synthetic fixture — no owned-hardware capture — so keeping it out until there's a real WHOOP 5.0 trace to validate against looks like the right posture. Just noting it as the next realtime gap when one's available.

Nice work on this.