Skip to content

Device: Improve debug logs for AirPods info packets#488

Merged
d4rken merged 1 commit into
mainfrom
feat/aap-engraving-discovery-log
Apr 8, 2026
Merged

Device: Improve debug logs for AirPods info packets#488
d4rken merged 1 commit into
mainfrom
feat/aap-engraving-discovery-log

Conversation

@d4rken

@d4rken d4rken commented Apr 8, 2026

Copy link
Copy Markdown
Member

What changed

No user-facing behavior change.

Groundwork for #173 (engraving message). When a debug recording is active, capod now dumps the structured contents of the AirPods info packet (the one sent right after a connection is established) into the log file. This includes non-ASCII bytes, so emoji or non-Latin engravings would be visible. The intent is that testers with engraved AirPods can attach a debug log so the protocol can be analyzed for where (or whether) Apple's engraving message lives.

Technical Context

  • Why diagnostic-only: no public reverse-engineering of the engraving exists (checked librepods, MagicPodsCore-style references, capod itself), and no engraved device is available for testing. Most likely the engraving lives only in iCloud and is looked up by serial — but we cannot confirm without a real capture. Shipping a UI field would be premature; a logger lets us crowdsource the discovery.
  • Why a separate parser instead of extending parseNullTerminatedStrings: the production parser is ASCII-only (0x20..0x7E) and would silently drop emoji or non-Latin engravings. The diagnostic helper uses strict UTF-8 with a hex fallback so any encoding survives. The production decode path is intentionally untouched — no widening of protocol assumptions for a debug-only purpose.
  • Why unconditional on 0x1D: the dump fires regardless of whether decodeDeviceInfo succeeds — an engraving-shaped packet that the strict decoder rejects still needs to be captured.
  • Privacy: the dump contains device serials, left/right bud serials, manufacturing IDs and an encrypted blob. Anyone sharing a log file should redact serials before pasting publicly.
  • Verified on hardware: tested on a real AirPods Pro 2 USB-C — emits 13 segments with the expected slot labels (name, modelNumber, manufacturer, serialNumber, firmwareVersion, then unknown). The encrypted blob lands as a 44-byte non-UTF-8 segment because there is no NUL between it and the following manufacturing-date string on the wire.
  • Tests: a real-capture happy path, a synthetic emoji payload (regression for the ASCII-only drop), and a malformed-short payload (regression for "must not gate dump on decodeDeviceInfo success").

Refs #173.

Diagnostic-only NUL-delimited UTF-8 segmentation of the 0x1D INFORMATION packet, logged at INFO so it lands in debug recordings via the existing FileLogger pipeline. The production decode path stays untouched — this only adds visibility, no behavior change. Refs #173.
@d4rken d4rken added coms/AAP Uses Apples AirPod Protocol. Requires Android ROM with fixed L2CAP support on the Bluetooth sockets. changelog-ignore and removed changelog-ignore labels Apr 8, 2026
@d4rken d4rken merged commit 2d38db5 into main Apr 8, 2026
10 checks passed
@d4rken d4rken deleted the feat/aap-engraving-discovery-log branch April 8, 2026 09:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

coms/AAP Uses Apples AirPod Protocol. Requires Android ROM with fixed L2CAP support on the Bluetooth sockets.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant