librepods-org / librepods-org/librepods
docs: battery example labels left/right backwards, contradicting the components table above it
Nobody has claimed this yet.
- Dominant language
- Kotlin
- Stars
- 29.9k
- Forks
- 1.7k
- PR merge metrics
- No merged PRs in 30d
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.)
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
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.
Assessment
- Domain
- documentation, reverse-engineering
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 92/100