Onboarding new contributors

[undefinedactive]

First and foremost thank you for the awesome work that you did creating this project.

Would be maybe possible that READMEor CONTRIBUTING.md file contains some simple steps how to go about reverse engineering protocol that bluetooth headphones use or maybe what steps you took? Is there any hardware needed?

[can1357]

Thanks for the kind words!

Here's a quick overview of how I reverse engineered the AirPods protocol - no special hardware needed:

1. Find Where the Protocol Lives

On macOS, the Bluetooth stack is in /usr/sbin/bluetoothd, I figured this out by grepping for AirPods.

MacBook-Pro:System root# strings /usr/sbin/bluetoothd | grep -i "airpod\|aap"
apple_airpods_case
AAP Client Connect failure %u
BT_AACP_CLIENT_fastConnectCreateChannel: Error creating AAP
AACP: aapConnectCb  result = %d
ConnectComplete result %d handle %u -- disconnecting AAP
AAP Handle %d is not valid!
void aapDataRecv(BT_AAP_HANDLE, uint8_t *, uint16_t)
Unknown AACP opcode: 0x%04x (AAP len %u)
BT_AAP_Client_SendUnstallableData failed due to %u
BT_AAP_Client_Connect
AAP_Client: L2CAP connected, beginning AAP connection
AAP_CLIENT_Connect initiating SDP
BT_AAP_Client_SendUnstallableData channel not found: addr=%: cid=%d sid=%d len=%d
BT_AAP_Client_FastConnect error creating AAP signaling
BT_AAP_Client_cleanFastConnect cid=%d
BT_AAP_Client_cleanFastConnectAAP NULL Handle
AAP Client
AAPConnectSetTimeout: No AAP connection associated with handle %d
AAPConnectSetTimeout: Error registering timeout handler for handle %d status %d
AAP connection timeout for cmd %d, handle %d
False AAP connection timeout for handle %d state %d
AAP connection timeout for unknown handle %d
AAPConnectCancelTimeout: No AAP connection associated with handle %d
/AppleInternal/Library/BuildRoots/bad1ce41-1f88-11f0-be1f-0a5c80dde946/Library/Caches/com.apple.xbs/Sources/MobileBluetooth/Stack/profiles/aap/aap_client.c
l2capRecvDataInd: BT_AAP_CONNECT_RSP connection accepted sid=%u cid=%u
l2capRecvDataInd: BT_AAP_CONNECT_RSP connection in unhandled state sid=%u cid=%u state=%u
l2capRecvDataInd: BT_AAP_DISCONNECT_REQ
BT_AAP_DISCONNECT_RSP from l2capRecvDataInd for cid=%d
Didn't find what we were looking for, zap PSM's to prevent AAP connections when SDP disconnect completes
Couldn't connect SDP for AAP!
l2capWriteCfm: BT_AAP_DISCONNECT_REQ
BT_AAP_DISCONNECT_RSP from l2capWriteCfm for cid=%d, result=%d
l2capDisconnectInd from aap_client cid=%d reason=%d
AapServer
AapService
AapClient
BT_AAP_DISCONNECT
Cannot Verify AirPods
These headphones could not be verified as genuine Apple AirPods. Would you like to connect anyway?
AirPods Case
AIRPODS_CASE
AirpodsTimeSinceBoot
kBTAudioMsgPropertyIsGenuineAirPods
com.teslamotors.TeslaApp
EnhancedAirPodsVoice
Airpods Connection Stats: 
AirPodsConnectionStats
kCBMsgIdDeviceIsGenuineAirPodsMsg
AirPods
AIRPODS
AirPods Pro
AirPods Max
kCBAdvDataAppearance
kCBAdvDataAppleMfgData
kCBAdvDataAppleBeaconKey
parseAACPSetupComplete FC_AACP_AIRPODS_INFO received
updateAirpodsConnectionMetricDevice FastConnect for device %s
BTDeviceMsgHandler::handleBTDeviceIsGenuineAirPodsMsg device:%llx
BTDeviceMsgHandler::handleBTDeviceIsGenuineAirPodsMsg device:%llx genuine:%u (%s)
DeregisterScoDataApplication failed with %{bluetooth:OI_STATUS}u

2. Trace What Happens When You Toggle ANC

I looked for strings like "listening mode" in IDA Pro and found the main command handler at sub_100250E30. Here's the actual code for opcode 0x0D (listening mode):

case 0x0Du:  // Listening Mode opcode
  // ... validation code ...
  sub_1004490AC(a2, v5);  // Call the actual setter

Following sub_1004490AC shows how the command is formatted:

__int64 __fastcall sub_1004490AC(__int64 device, int mode)
{
  // ...
  *(_DWORD *)(device + 808) = mode;  // Store mode in device struct
  
  // Log the change
  _os_log_impl(..., "Listening Mode is set to %d for Device %{public}s", ...);
  
  // ... The actual packet construction ... 
  buf[1] = mode;       // Mode value (2 or 4)
  // ... send packet ...
}

Alternative: Just Log the Packets!

If you're not comfortable with reverse engineering, you can simply capture the Bluetooth packets directly:

macOS:
Use PacketLogger from Xcode's Additional Tools

Android:
Enable HCI snoop log in Developer Options

By comparing packets when you toggle different features, you can figure out the protocol without any RE experience.

So no hardware necessary, Just:

• A device that controls whatever headset you're interested in
• • the binaries controlling it and a decompiler: IDA Pro, Ghidra (free), Binary Ninja, etc.
• • OR just packet logging tools (no RE experience needed!)

This same approach works for most headphones - find the vendor-specific protocol handler (usually in the OS Bluetooth daemon or companion app), locate the command switch statement, extract the opcodes, and trace how packets are constructed.

The beauty is that most vendors use simple command+value protocols over standard Bluetooth channels!

[undefinedactive]

Thank you for a quick and quality reply :)