docs: battery example labels left/right backwards, contradicting the components table above it

Open Beginner friendly
#771 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
92/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Domain
documentation, reverse-engineering

Research direction

Open docs/AAP Definitions.md and compare the Battery components table with the worked packet example immediately below it. Swap the 8th-byte and 13th-byte component labels so they match the table, then verify that the case label and battery levels remain unchanged.

Written by the indexing model from the issue text.

Description

Summary

In docs/AAP Definitions.md, the Battery section's components table and its worked example disagree about which byte is which earbud. The table is correct; the example's byte-by-byte commentary is wrong.

Anyone implementing from the walkthrough rather than the table gets left and right silently swapped — a bug with no visible symptom until the two pods are at different levels and someone notices the sides are backwards.

The contradiction

The table says:

Components Byte value
Case 08
Left 04
Right 02

The example packet directly below it:

04 00 04 00 04 00 03 02 01 64 02 01 04 01 63 01 01 08 01 11 02 01

...is annotated as:

Byte Doc says Table says that byte is
8th (0x02) "Battery type - Left" Right
13th (0x04) "Battery type - Right" Left
18th (0x08) "Battery type - Case" Case (agrees)

Only the component labels conflict — the levels in the same example (0x64 = 100%, 0x63 = 99%, 0x11 = 17%) all check out, so the packet itself is fine.

Which one is right

The table. Verified physically rather than by inference: with both earbuds out and reporting, the left earbud was placed in the charging case, and the component reporting charging was 0x04. Repeated with the case row present and absent; consistent both times.

  • device: AirPods Pro 2, model A2698, firmware 81.2675000075000000.6877
  • read over direct L2CAP on PSM 0x1001, stdlib Python, no library in the path
Suggested fix

Correct the walkthrough's 8th- and 13th-byte rows to "Battery type - Right" and "Battery type - Left" respectively, so it matches the table above it.

Worth doing even though the table is right there — the walkthrough is the part people transcribe, because it is the part that explains the layout.

Happy to send a PR if useful. (Separate from #770, which is about the notification-request packet in the same document.)

Dominant language
Kotlin
Stars
29.9k
Forks
1.7k
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from librepods-org/librepods

All issues in librepods-org/librepods

Similar issues

More Kotlin issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.