Case study
bosectl: reconstructing Bose’s BMAP headphone protocol
Controls Bose headphones from Linux and macOS without the Bose app, account or cloud, through Python, Rust and C++ libraries and command-line tools that implement Bose’s BMAP protocol over Bluetooth RFCOMM. The author documents BMAP’s function blocks, operators, payload layouts and error codes in NOTES.md, reportedly worked out by probing RFCOMM channels, capturing Bluetooth traffic while changing settings in the Bose app and testing each operator, and the libraries cover noise cancellation, EQ, spatial audio, button remapping, profiles and device settings. Support is reported per model by the author and contributors.
- Targets
- Protocol
- Category
- Independent reconstruction cases
- Relationship
- Independent reconstruction project
- Sources reviewed
Requirements & limits
- The reviewed commit is the v0.5.0 release of 2026-09-28, which ships Linux x86_64 bmapctl binaries built from the Rust and C++ code with SHA256SUMS; the Rust crate is also on crates.io as bose-bmap 0.5.0, while the Python package installs from the repository through its install scripts or pipx. The README’s device table marks six models, led by the QC Ultra Headphones 2, as verified to differing extents and the Ultra Open Earbuds as partial from a device report; other cataloged BMAP products are recognized by product ID but have no tested configuration.
- Needs the user’s own paired Bose headphones and a Bluetooth adapter: BlueZ on Linux, or macOS 10.15+, where the Python library uses PyObjC’s IOBluetooth bindings. The Rust crate is Linux-only, and C++ builds on Linux need CMake, a C++17 compiler and the BlueZ development headers. No Bose software or files are needed at runtime.
- README reports probing RFCOMM channels, capturing Bluetooth HCI traffic while toggling settings in the Bose app and testing operators on each function block, and NOTES.md cites class names from the Bose Android app. The app, decompiled code and raw HCI or network captures are not in the repository: captures/ holds eight before-and-after setting snapshots from bmap-capture.py with the MAC address, serial number and other identifiers partly masked, and fixtures/ holds a packet used by the tests.
- README says the project uses only BMAP operations the headphones accept without authentication, and that no keys are extracted, no encryption is broken and no traffic is replayed; writes that the app performs after cloud-mediated authentication stay out of reach. USB control is not implemented, and NOTES.md treats the USB interface as being for firmware updates.
- CI runs the Python, Rust and C++ test targets on Ubuntu and macOS without headphones; integration tests that need a paired device run only when enabled. Device behavior was not reproduced in this review. MIT license; no REA use is established.
About this entry
The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.
Primary sources
- README.md GitHub · aaronsb/bosectl · Revision 70570b2
- NOTES.md GitHub · aaronsb/bosectl · Revision 70570b2
- docs/architecture.md GitHub · aaronsb/bosectl · Revision 70570b2
- docs/quietcomfort-headphones-prince.md GitHub · aaronsb/bosectl · Revision 70570b2
- captures GitHub · aaronsb/bosectl · Revision 70570b2
- bmap-capture.py GitHub · aaronsb/bosectl · Revision 70570b2
- fixtures/README.md GitHub · aaronsb/bosectl · Revision 70570b2
- python/pyproject.toml GitHub · aaronsb/bosectl · Revision 70570b2
- rust/README.md GitHub · aaronsb/bosectl · Revision 70570b2
- cpp/CMakeLists.txt GitHub · aaronsb/bosectl · Revision 70570b2
- python/tests/test_integration.py GitHub · aaronsb/bosectl · Revision 70570b2
- .github/workflows/test.yml GitHub · aaronsb/bosectl · Revision 70570b2
- LICENSE GitHub · aaronsb/bosectl · Revision 70570b2
- https://github.com/aaronsb/bosectl/releases/tag/v0.5.0
- https://crates.io/crates/bose-bmap/0.5.0