Skip to content

feat: support the original Pixel Buds Pro (Gen 1) — with CAP-081 and three draft ADRs - #76

Open
cpave3 wants to merge 5 commits into
tedsluis:mainfrom
cpave3:feat/gen1-support
Open

cpave3 wants to merge 5 commits into
tedsluis:mainfrom
cpave3:feat/gen1-support

Conversation

@cpave3

@cpave3 cpave3 commented Nov 2, 2026 •

Copy link
Copy Markdown

Summary

The below is AI generated, and should adhere to the contribution guidelines for this project. I've tested the change locally quite extensively with my own Pixel Bud Pro 1, and everything seems to work, and the payloads are essentially identical to those in the official Pixel Buds app.

Thank you for making this project, by the way. I was very happy to see this as an alternative to the official app, as I'm trying to de-google my life a bit.


Adds support for the original Pixel Buds Pro (Gen 1), firmware release_5.11_signed, next to the Pro 2. A Gen 1 is identified by its firmware and its
GetHardwareInfo device type (4); everything unknown stays in Safe Mode, and the Pro 2's behaviour is unchanged (plus one extra check, below).

This is a third-party contribution and it needs your decision: PROJECT.md lists other models as a non-goal "unless the protocol is demonstrably
identical — this must be separately verified". The evidence for that is a new capture, CAP-081. The three draft ADRs are below and in
ai-sessions/0102_FEATURE_RESULT_2026_11_02.md. They are not in DECISIONS.md, and nothing in PROTOCOL.md is promoted (AGENTS.md §6).

Evidence — CAP-081 (Group BQ, my own Gen 1, redacted)

  • Part 1, the official Pixel Buds app (1.0.996096625, Pixel 4 XL, Android 13): every Gen 1 setting changed and changed back.

    • 22 of its Maestro WriteSetting frames are byte for byte this app's encoder output, CRC included. They are the fixtures of the new
      Gen1OfficialAppWritesTest.
    • Settings covered: in-ear 2, touch 4, press-and-hold 7, hold list 12, Volume EQ 15, EQ 16/18, balance 17, mono 19, conversation detection 22.
    • Find left/right/stop uses the same Message Stream bytes as the Pro 2.
  • Part 2, this branch's build (Pixel 9 Pro, GrapheneOS, Android 17): the same actions.

    • 43 writes, 43 RESPONSE OK, only on fields 2, 4, 7, 11, 12, 13, 15, 16, 17, 19 and 22.
    • Never Adaptive, never 27/28/29, never Ring both. The negatives were checked with a positive control.
  • The Gen 1 has no settings 27, 28 or 29: the official app reads them and gets status 2.

  • Two settings the official app writes differently. For the noise-control mode and multipoint it sends signed Message Stream commands (08 12,
    07 12, with 16 trailing bytes that need the account key). This branch uses WriteSetting 4:{13:n} (ADR-067) and 4:{11:b} (ADR-053) instead.

    • The Gen 1 accepts both, and pushes the mode back on the settings stream.
    • After part 2, the official app on the other phone showed both values exactly as this app set them. That check was by eye and was not filmed.
    • Both are marked TODO(verify) in DeviceProfiles.kt. D-3 asks you to choose between accepting them and making them read-only.
  • Redaction (new scripts/redact_btsnoop.py; frame numbers are kept):

    • other devices' traffic and advertising removed;
    • Bluetooth addresses replaced with placeholders, link keys zeroed;
    • serial numbers, my name and my timezone replaced.

    The films, the bugreports and the unredacted logs stay with me; their hashes are in CAP-081-sha256sums.txt (ADR-066).

What changed in code

  • DeviceProfiles (new): a profile per model with its firmware, device type, Model ID, read sweep and allowed writes. SafeModeGate now checks the model and
    the write target.
  • A Gen 1 write waits until the device type has been read on that connection.
  • Gen 1 UI: no Adaptive mode, no head gestures, no case sounds, no "Ring both". The Info tab shows the model and its device type.
  • Press-and-hold goes one bud per write on both models, as the official app does it.
  • Pro 2 change: a Pro 2 firmware whose read device type is not 6 is now refused (Safe Mode).
  • Debug tab: "Read Fast Pair model ID" opens the shared channel and sends nothing.
  • scripts/pwrpc_decode.py: fixed a crash on a truncated fixed32/fixed64 field. It hit this on CAP-081.

Draft ADRs (proposed, not accepted; numbers are yours to assign)

  • D-1: support the Gen 1 as a second model.
    • PROJECT.md's non-goal gets a dated note.
    • Still one pair of Buds at a time.
    • The app name stays as it is. Whether the README names the Gen 1 is your call.
  • D-2: device profiles and Gen 1 identification; amends ADR-042.
    • Writes are allowed per model and per write target.
    • Gen 1 = release_5.11_signed and device type 4 read on the same connection. Find also needs Model ID 6edaf7.
    • Pro 2 = today's rules, plus device type 6 when read.
  • D-3: Gen 1 writes.
    • Allowed: settings 2, 4, 7, 11, 12 (three booleans), 15, 16, 17, 19, 22; the mode 1–3; ring left or right.
    • Never sent: Adaptive, 27, 28, 29, Ring both.
    • Decide the mode/multipoint caveat above: (a) accept, with a filmed read-back in the first Gen 1 hardware run; or (b) make both read-only on the Gen 1
      until then.

Not in this PR (in TODO.md §5)

  • README.md, PROJECT.md, ARCHITECTURE.md §5a and RELEASING.md are not updated. They depend on your decision on D-1.
  • The Assistant-channel (GSND) research. If you want it, it can come as a separate PR.

Checks

🤖 Generated with Claude Code

cpave3 and others added 5 commits November 2, 2026 12:47
parse() accepted a fixed32/fixed64 field that ran past the end of the
buffer, and fmt() then crashed in struct.unpack. A payload in the Gen 1
capture CAP-081 hit this, so the decoder could not list that log at all.
A truncated fixed field now makes parse() return None (not a message),
like a truncated length-delimited field already did.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
redact_btsnoop.py prepares a contributor's btsnoop log for publication
(CONTRIBUTING.md, "the PII exception") without changing any frame number:
other devices' ACL data and advertising reports become an empty vendor
event, addresses become placeholders, link keys are zeroed, and given
strings (serials, names) are replaced, also across ACL fragments. It
fails if anything it was told to remove is still present.

decode_maestro_frames.py decodes text dumps of pw_hdlc frames (used by
GEN1_SUPPORT_INVESTIGATION.md for PixelBudsMacOS's third-party frames).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…enControl

A third-party capture (Group BQ) of a Gen 1 on release_5.11_signed, so the
Gen 1 support can be judged on evidence (PROJECT.md: other models only
when "demonstrably identical", verified, never assumed).

Part 1, the official app on a Pixel 4 XL: every Gen 1 setting written.
22 of its Maestro WriteSetting frames equal this app's encoder output.
The mode and multipoint go over signed Message Stream commands instead.
Settings 27/28/29 answer status 2. Find left/right only.
Part 2, OpenControl on a Pixel 9 Pro: 43 writes, 43 OK; the official app
then read back the mode and multipoint this app set.

Logs redacted with scripts/redact_btsnoop.py; films, bugreports and the
unredacted logs stay local (hashes listed, ADR-066). PROTOCOL.md gets a
section 0.1 row and section 4.6, all HYPOTHESIS, proposed for FACT; no
promotion and no ADR here (AGENTS.md section 6).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gen 1 owners can use the app instead of being held in Safe Mode, with
only the writes CAP-081 shows the official app making the same way.

- DeviceProfiles: per model the firmware, device type (GetHardwareInfo
  field 1), Model ID, read sweep and allowed write targets. SafeModeGate
  checks the model and the target. Gen 1 = release_5.11_signed and device
  type 4 read on the same connection; Find also needs Model ID 6edaf7.
  A Pro 2 firmware with a read device type other than 6 is now refused.
- Gen 1 writes: settings 2, 4, 7, 11, 12 (three booleans), 15, 16, 17,
  19, 22, the mode 1-3, ring left/right. The mode and multipoint carry
  TODO(verify): the official app uses signed Message Stream commands.
- Press and hold is written one bud at a time, as the official app does.
- Gen 1 UI: no Adaptive, head gestures, case sounds or Ring both; the
  Info tab shows the model. Debug: "Read Fast Pair model ID".
- Tests: Gen1OfficialAppWritesTest compares 22 official-app frames of
  CAP-081 with the encoders byte for byte; the Gen 1 fixtures are CAP-081
  frames (serials redacted, CRC re-sealed).

Depends on the draft ADRs in the pull request; none is accepted yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GEN1_SUPPORT_INVESTIGATION.md is the 2026-11-01 analysis behind the
change, with a status note on what CAP-081 superseded and its external
references turned into links. CHANGELOG [Unreleased], TODO.md section 5
(the open Gen 1 items) and the session log 0102 with the three draft ADRs
for the maintainer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
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.

1 participant