Case study
BudsPro-Headtracking: streaming Galaxy Buds Pro head tracking over Samsung’s serial protocol
Reimplements the Samsung Galaxy Buds Pro’s proprietary spatial-audio messages in a small Python script so that a PC can stream the earbuds’ head-tracking data in real time. It connects to the earbuds’ GEARMANAGER (or FACTORY) RFCOMM serial service, frames packets with start and end markers and a CRC16-CCITT checksum, enables the sensor stream with attach and two-second keep-alive messages, and decodes the rotation quaternion from the data events. A contributed script converts the quaternion to Euler angles and forwards it over local UDP to a Unity receiver; results are shown only as author-provided sample output.
Requirements & limits
- The reviewed master commit 63b321a (2024-12-30) merges a contributor change that also accepts the FACTORY service name reported for Galaxy Buds2; the README covers only the Galaxy Buds Pro, and the project has no releases, tests or list of tested earbud firmware. Headtracking.py prints the raw x, y, z, w quaternion (four signed 16-bit values divided by 10,000) or, with -b, frame-timing statistics, and reports gyro-bias and stuck-sensor events only in verbose mode.
- It needs the user’s own paired Galaxy Buds Pro, addressed by its Bluetooth MAC address; no Samsung app or firmware is used at runtime or included in the repository. The repository does not document how the message IDs and framing were derived; code comments point to the author’s separate Galaxy Buds desktop client for the full parser and quaternion conversion, which this record does not cover.
- Python 3 with PyBluez on Windows or Linux; the README requires PyBluez 0.22 on Windows because 0.23 fails to enumerate Bluetooth devices. buds_to_unity.py also needs NumPy, hardcodes a device address and sends to 127.0.0.1:12562, and getBudsUDP.cs is a Unity MonoBehaviour adapted from a receiver credited to KAIST UVR Lab.
- The README shows sample quaternion output, and benchmark mode reports the average, minimum and maximum time between motion frames, but no captures, tests or recorded benchmark results are published. In the reviewed SpatialSensorManager.py the command payloads are built with Python’s bytes(n), which yields n zero bytes rather than the value n, so the bytes sent may differ from what the constant names suggest; this collection did not run the scripts.
- LICENSE grants MIT (2021, Tim Schneeberger); the Unity script carries an attribution to its original author but no separate license. Galaxy Buds and its services belong to Samsung. The reviewed sources establish no AI or REA use.
About this entry
- Type
- Case study
- Category
- Independent reconstruction cases
- Relationship
- Independent reconstruction project
- Targets
- Protocol
Sources reviewed
The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.
Primary sources
- README.md GitHub · timschneeb/BudsPro-Headtracking · Revision 63b321a
- Headtracking.py GitHub · timschneeb/BudsPro-Headtracking · Revision 63b321a
- SpatialSensorManager.py GitHub · timschneeb/BudsPro-Headtracking · Revision 63b321a
- BluetoothService.py GitHub · timschneeb/BudsPro-Headtracking · Revision 63b321a
- Crc16.py GitHub · timschneeb/BudsPro-Headtracking · Revision 63b321a
- buds_to_unity.py GitHub · timschneeb/BudsPro-Headtracking · Revision 63b321a
- getBudsUDP.cs GitHub · timschneeb/BudsPro-Headtracking · Revision 63b321a
- LICENSE GitHub · timschneeb/BudsPro-Headtracking · Revision 63b321a
More in Protocols
- Even G2 protocol: reverse-engineering Even Realities G2 smart-glasses BLE traffic · Case study
- Wireshark · Tool
- Netzob · Tool
- Scapy · Tool
- Universal Radio Hacker (URH) · Tool
- SavvyCAN · Tool