### Install via installer script Source: https://github.com/aaronsb/bosectl/blob/main/README.md Clones the repository and runs the platform-specific installer. The installer checks prerequisites (PyObjC on macOS, a Bluetooth-capable Python on Linux) and symlinks `bosectl` into `/usr/local/bin`. ```bash git clone https://github.com/aaronsb/bosectl.git cd bosectl ./linux_install.sh # or ./macOS_install.sh ``` -------------------------------- ### Install from crates.io (Rust, Linux) Source: https://github.com/aaronsb/bosectl/blob/main/README.md Installs the `bmapctl` binary via `cargo install bose-bmap`, or adds `bose-bmap` as a library dependency with `cargo add`. The import remains `use bmap::`. ```bash cargo install bose-bmap # installs the bmapctl binary cargo add bose-bmap # use as a library; the import is still `use bmap::` ``` -------------------------------- ### Install with pipx Source: https://github.com/aaronsb/bosectl/blob/main/README.md Installs `bosectl` into its own environment and puts it on your `PATH`. On macOS this also pulls in PyObjC. ```bash git clone https://github.com/aaronsb/bosectl.git pipx install ./bosectl/python ``` -------------------------------- ### START [31.9] Reset Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Resets audio modes. Accepts START with empty payload, returns InvalidData. ```APIDOC ## [START] [31.9] ### Description Resets audio modes. Accepts START with empty payload, returns InvalidData. ### Method START ### Endpoint Block 31, Function 9 (Reset) ### Response #### Success Response InvalidData with empty payload ``` -------------------------------- ### Quick Start Commands Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Run all test suites and build release binaries with checksums. ```bash make test # run all test suites (Python + Rust + C++) make artifacts # build release binaries + SHA256SUMS ``` -------------------------------- ### connect() usage examples Source: https://github.com/aaronsb/bosectl Shows auto-detection and explicit MAC/device_type usage. The first example prints battery status; the second sets CNC on a QC Ultra 2. ```python import pybmap with pybmap.connect() as dev: # auto-detect device print(dev.battery()) with pybmap.connect(mac="68:F2:1F:0D:F5:11", device_type="qc_ultra2") as dev: # explicit dev.set_cnc(8) ``` -------------------------------- ### bmapctl example commands Source: https://github.com/aaronsb/bosectl Example invocations showing environment variables and common commands: status, eq, buttons set, and raw hex. ```bash BMAP_MAC=68:F2:1F:0D:F5:11 BMAP_DEVICE=qc_ultra2 bmapctl status bmapctl eq 3 0 -2 bmapctl buttons set ANC bmapctl raw 1f 03 05 02 00 00 ``` -------------------------------- ### Install from release binaries (Linux) Source: https://github.com/aaronsb/bosectl/blob/main/README.md Downloads the release binary and checksum file, verifies the checksum, makes the binary executable, and copies it to `/usr/local/bin` as `bmapctl`. ```bash # Download from GitHub releases curl -LO https://github.com/aaronsb/bosectl/releases/latest/download/bmapctl-rust-linux-x86_64 curl -LO https://github.com/aaronsb/bosectl/releases/latest/download/SHA256SUMS sha256sum -c SHA256SUMS chmod +x bmapctl-rust-linux-x86_64 sudo cp bmapctl-rust-linux-x86_64 /usr/local/bin/bmapctl ``` -------------------------------- ### Install and run bmapctl Source: https://github.com/aaronsb/bosectl/blob/main/rust/README.md Install the bose-bmap crate with cargo, which also installs the bmapctl command-line tool. Then check headphone status with bmapctl status. ```bash cargo install bose-bmap # installs bmapctl bmapctl status ``` -------------------------------- ### Artifact Verification Commands Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Verify checksums and install the Rust binary. ```bash # Download and verify cd dist/ sha256sum -c SHA256SUMS # Install chmod +x bmapctl-rust-linux-x86_64 sudo cp bmapctl-rust-linux-x86_64 /usr/local/bin/bmapctl ``` -------------------------------- ### START [7.1] Control.GetAll Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Triggers a control state dump. Returns PROCESSING status. ```APIDOC ## [START] [7.1] ### Description Triggers a control state dump. Returns PROCESSING status. ### Method START ### Endpoint Block 7, Function 1 (Control.GetAll) ### Response #### Success Response PROCESSING - triggers control state dump ``` -------------------------------- ### START [31.1] GetAll Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Triggers a full state dump of all audio modes. Returns a PROCESSING status indicating the dump has been initiated. ```APIDOC ## [START] [31.1] ### Description Triggers a full state dump of all audio modes. Returns a PROCESSING status indicating the dump has been initiated. ### Method START ### Endpoint Block 31, Function 1 (GetAll) ### Response #### Success Response PROCESSING - triggers full state dump ``` -------------------------------- ### START [4.1] DevMgmt.Connect Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Initiates a Bluetooth connection to a device. Requires the device MAC address. Returns InvalidData if the MAC is not provided. ```APIDOC ## [START] [4.1] ### Description Initiates a Bluetooth connection to a device. Requires the device MAC address. Returns InvalidData if the MAC is not provided. ### Method START ### Endpoint Block 4, Function 1 (DevMgmt.Connect) ### Parameters #### Request Body - **device MAC** (string) - Required - MAC address of the device to connect to ### Response #### Success Response InvalidData - needs device MAC, may initiate BT connection ``` -------------------------------- ### START [31.6] ModeConfig Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Returns all mode configurations as STATUS messages. This command is unauthenticated. ```APIDOC ## [START] [31.6] ### Description Returns all mode configurations as STATUS messages. This command is unauthenticated. ### Method START ### Endpoint Block 31, Function 6 (ModeConfig) ### Response #### Success Response STATUS messages with all mode configs ``` -------------------------------- ### C++ exception handling example with bmap::connect() Source: https://github.com/aaronsb/bosectl Shows how to catch and handle the custom exceptions from the bmap library. The example connects to a device, sets CNC level to 8, and catches busy_error, desync_error, device_error, and std::exception. ```cpp #include "bmap.h" #include try { auto dev = bmap::connect(); dev->set_cnc(8); } catch (const bmap::busy_error& e) { std::cerr << "Headset busy: " << e.what() << "\n"; } catch (const bmap::desync_error& e) { std::cerr << "Out of sync — reopen: " << e.what() << "\n"; } catch (const bmap::device_error& e) { std::cerr << "Device error " << (int)e.code() << ": " << e.what() << "\n"; } catch (const std::exception& e) { std::cerr << e.what() << "\n"; } ``` -------------------------------- ### START endpoints Source: https://github.com/aaronsb/bosectl Initiates device operations. The response is either a RESULT or PROCESSING acknowledgment. ```APIDOC ## START endpoints ### Description Initiates device operations. The response is either a RESULT or PROCESSING acknowledgment. ### Method START ### Endpoint `[31.3]` current_mode ### Parameters #### Request Body - **[mode_idx, announce(0/1)]** - Mode index and announce flag ### High-level methods - `set_mode` ### Notes - prince/QC45 firmware may ack with PROCESSING, then emit a STATUS; the ack must be RESULT or PROCESSING --- ### Endpoint `[31.1]` get_all_modes ### Parameters #### Request Body - none ### High-level methods - `modes()` ### Notes - Drains N × `[31.6]` STATUS frames --- ### Endpoint `[4.8]` pairing ### Parameters #### Request Body - **[0x01]** - Pairing command ### High-level methods - `pair()` --- ### Endpoint `[4.12]` routing ### Parameters #### Request Body - **[0x82, ...6 MAC bytes]** - Routing command (0x82 = bit7 UP direction, bit1 device slot) ### High-level methods - `route(mac)` --- ### Endpoint `[7.4]` power ### Parameters #### Request Body - **[0x00]** - Power off command ### High-level methods - `power_off()` --- ### Endpoint `[31.1]` raw dump ### Parameters #### Request Body - none ### High-level methods - `send_raw`/CLI `dump` ``` -------------------------------- ### Current button configuration (QC Ultra 2) Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Example of the current configuration for the Shortcut button (0x80) on the QC Ultra 2. Shows the raw response and the supported actions. ```text Button 0x80 (Shortcut), long_press → Disabled Supported actions: SwitchDevice, TrackBack, unknown(22), unknown(25) Raw: 80090e00094002 ``` -------------------------------- ### pair Source: https://github.com/aaronsb/bosectl Start pairing mode. ```APIDOC ## pair ### Description Start pairing mode. ### Usage `bosectl pair` ``` -------------------------------- ### QC35 Block 3.2 START Payload Format (14 bytes) Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Describes the 14-byte payload format for the [3.2] START command on QC35 firmware 4.8.1. The currentState must match the [3.1] value, and targetState must be a valid transition target. Only the transition 01 → 02 is accepted; others return error 15 or InvalidData. ```text Offset Size Field 0 1 currentState — must match [3.1] value 1-3 3 reserved (zeros) 4 1 targetState — must be a valid transition target 5-13 9 reserved (zeros) ``` -------------------------------- ### START [4.12] DevMgmt.Routing Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Switches the active multipoint device. Returns a RESULT. ```APIDOC ## [START] [4.12] ### Description Switches the active multipoint device. Returns a RESULT. ### Method START ### Endpoint Block 4, Function 12 (DevMgmt.Routing) ### Response #### Success Response RESULT - switch active multipoint device ``` -------------------------------- ### Device catalog API with pybmap.lookup_device Source: https://github.com/aaronsb/bosectl/blob/main/README.md Look up Bose devices by product ID, get USB/Bluetooth IDs, modalias, and support status. Comments show example outputs and supported device codenames. ```python import pybmap # Look up any known Bose device by product ID dev = pybmap.lookup_device(0x4082) print(dev.name) # "QuietComfort Ultra Headphones (2nd Gen)" print(dev.codename) # "wolverine" # USB/Bluetooth identification pybmap.usb_ids(0x4082) # (0x05A7, 0x4082) pybmap.modalias(0x4082) # "bluetooth:v05A7p4082d0000" # Check support status pybmap.is_supported(0x4082) # True — has tested config pybmap.is_supported(0x4075) # True — QuietComfort Headphones (prince) pybmap.is_supported(0x4039) # True — QuietComfort 45 (duran) pybmap.supported_devices() # [wolfcastle, baywolf, duran, prince, wolverine, lando, edith, serena] pybmap.known_devices() # full catalog ``` -------------------------------- ### Discovery usage example Source: https://github.com/aaronsb/bosectl Shows how connect() uses find_bmap_device and lookup_device. ```python from pybmap.discovery import find_bmap_device from pybmap.catalog import lookup_device mac, device_type = find_bmap_device() print(mac, device_type) # "68:F2:1F:0D:F5:11", "qc_ultra2" if mac: entry = lookup_device(int("4082", 16)) print(entry.name) # "QuietComfort Ultra Headphones (2nd Gen)" ``` -------------------------------- ### START [7.4] Control.Power Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Powers the device on or off. This is an unauthenticated command that returns a RESULT. ```APIDOC ## [START] [7.4] ### Description Powers the device on or off. This is an unauthenticated command that returns a RESULT. ### Method START ### Endpoint Block 7, Function 4 (Control.Power) ### Parameters #### Request Body - **power** (integer) - Required - 0=power off, 1=power on ### Response #### Success Response RESULT ``` -------------------------------- ### bmapctl example commands Source: https://github.com/aaronsb/bosectl Example invocations showing status, CNC, button mapping, and raw packet commands. The raw command concatenates hex args and prints TX:/RX: lines. ```bash BMAP_MAC=68:F2:1F:0D:F5:11 BMAP_DEVICE=qc_ultra2 bmapctl status bmapctl cnc 7 bmapctl buttons set ANC bmapctl raw 1f 03 05 02 0000 ``` -------------------------------- ### dump Source: https://github.com/aaronsb/bosectl Sends raw START [31.1] (GetAll), prints every response via fmt_response and field-by-field ModeConfig dumps. ```APIDOC ## dump ### Description Sends raw START [31.1] (GetAll), prints every response via fmt_response and field-by-field ModeConfig dumps. ### Usage `bosectl dump` ``` -------------------------------- ### START [4.8] DevMgmt.PairingMode Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Enables or disables pairing mode on the device. Returns a RESULT. ```APIDOC ## [START] [4.8] ### Description Enables or disables pairing mode on the device. Returns a RESULT. ### Method START ### Endpoint Block 4, Function 8 (DevMgmt.PairingMode) ### Parameters #### Request Body - **enable** (integer) - Required - 0x01=enable, 0x00=disable ### Response #### Success Response RESULT ``` -------------------------------- ### firmware() Source: https://github.com/aaronsb/bosectl Returns the firmware string from GET `[0.5]`. ```APIDOC ## firmware() ### Description Returns the firmware string from GET `[0.5]`. ### Returns - `str` - Firmware string ``` -------------------------------- ### START [18.19] ValidatedDeviceIdentityKeypair Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Accepts a public key for the authentication flow. Returns PROCESSING status. ```APIDOC ## [START] [18.19] ### Description Accepts a public key for the authentication flow. Returns PROCESSING status. ### Method START ### Endpoint Block 18, Function 19 (ValidatedDeviceIdentityKeypair) ### Parameters #### Request Body - **public key** (string) - Required - Public key for auth flow ### Response #### Success Response PROCESSING ``` -------------------------------- ### Button remapping GET response format [1.9] Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Format of the GET response for the Buttons setting (function 1.9). The response contains the button ID, event type, configured action, a supported mask, and an optional unavailable mask. ```text [0] buttonId — which physical button [1] buttonEventType — what gesture triggers it [2] configuredAction — current assigned action [3:7] supportedMask — bitmask of supported ActionButtonMode values [7:] unavailableMask — bitmask of unavailable modes (optional) ``` -------------------------------- ### modes Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Retrieves all available modes from the device. Uses the START action pattern with drain to collect all mode data. ```APIDOC ## modes ### Description Retrieves all available modes from the device. Uses the START action pattern with drain to collect all mode data. ### Method START + drain ### Response #### Success Response - **modes** (array) - List of all available modes ### Request Example ``` modes() ``` ### Response Example ``` [Mode{...}, Mode{...}, ...] ``` ``` -------------------------------- ### Usage example: connect, create_profile, set_mode, delete_profile Source: https://github.com/aaronsb/bosectl Shows a typical workflow: connect to the device, create a profile named "Commute" with cnc=6 and spatial=0, set the mode, then delete the profile. ```cpp auto dev = bmap::connect(); uint8_t slot = dev->create_profile("Commute", /*cnc=*/6, /*spatial=*/0, true, true); dev->set_mode("Commute"); dev->delete_profile("Commute"); ``` -------------------------------- ### GET [5.1] AudioMgmt.Source Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Queries the active audio source. This is a GET-only operation. ```APIDOC ## [GET] [5.1] ### Description Queries the active audio source. This is a GET-only operation. ### Method GET ### Endpoint Block 5, Function 1 (AudioMgmt.Source) ### Response #### Success Response Returns the active audio source ``` -------------------------------- ### pair() Source: https://github.com/aaronsb/bosectl Sends START pairing [4.8] payload [0x01]. ```APIDOC ## pair() ### Description Sends START pairing `[4.8]` payload `[0x01]`. ``` -------------------------------- ### START [5.3] Transport Controls Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Sends transport control commands such as play, pause, stop, and track navigation. Uses a single-byte payload with values from AudioControlValue.java. ```APIDOC ## [START] [5.3] ### Description Sends transport control commands such as play, pause, stop, and track navigation. Uses a single-byte payload with values from AudioControlValue.java. ### Method START ### Endpoint [5.3] ### Parameters #### Request Body - **Command** (byte) - Transport control command value. ### Response #### Success Response (200) No response body specified. #### Request Example ``` 0x00 STOP 0x01 PLAY 0x02 PAUSE 0x03 TRACK_FORWARD 0x04 TRACK_BACK 0x05 FAST_FORWARD_PRESS 0x06 FAST_FORWARD_RELEASE 0x07 REWIND_PRESS 0x08 REWIND_RELEASE ``` ``` -------------------------------- ### bmap::connect() usage example Source: https://github.com/aaronsb/bosectl Shows how to call connect with auto-detection or explicit MAC and device type, then print the battery percentage. Requires including "bmap.h". ```cpp #include "bmap.h" auto dev = bmap::connect(); // auto-detect auto dev = bmap::connect("68:F2:1F:0D:F5:11", "qc_ultra2"); std::cout << (int)dev->battery() << "%\n"; ``` -------------------------------- ### START [5.3] AudioMgmt.Control Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Controls audio playback (play/pause/skip). Requires a payload with the AudioControlValue. Returns InvalidData if the payload is missing. ```APIDOC ## [START] [5.3] ### Description Controls audio playback (play/pause/skip). Requires a payload with the AudioControlValue. Returns InvalidData if the payload is missing. ### Method START ### Endpoint Block 5, Function 3 (AudioMgmt.Control) ### Parameters #### Request Body - **AudioControlValue** (unknown) - Required - play/pause/skip command ### Response #### Success Response InvalidData - needs payload ``` -------------------------------- ### GET endpoints Source: https://github.com/aaronsb/bosectl Retrieves device state and configuration values. Each endpoint returns a STATUS response with a payload that is parsed by the corresponding parser function. ```APIDOC ## GET endpoints ### Description Retrieves device state and configuration values. Each endpoint returns a STATUS response with a payload that is parsed by the corresponding parser function. ### Method GET ### Endpoint `[2.2]` battery ### Response #### Success Response - **level** - Battery level - **r** - Reserved byte - **component_id** - Component identifier (multi-cell devices only) ### High-level methods - `battery()` - `battery_status()` --- ### Endpoint `[0.5]` firmware ### Response #### Success Response - ASCII string containing firmware version ### High-level methods - `firmware()` --- ### Endpoint `[1.2]` name ### Response #### Success Response - **flag** - Flag byte - **utf8** - UTF-8 encoded name (32-byte field) ### High-level methods - `name()` - `set_name` (SETGET) --- ### Endpoint `[1.3]` voice prompts ### Response #### Success Response - **bits** - Bit5 enabled, bits4-0 language ### High-level methods - `prompts()` - `set_prompts` --- ### Endpoint `[1.5]` cnc ### Response #### Success Response - **max_related** - Maximum related value - **current** - Current value - Returns `(current, max)` ### High-level methods - `cnc()` --- ### Endpoint `[1.6]` anr ### Response #### Success Response - **level** - ANR level (0-3) - **capabilities** - Capability bits ### High-level methods - `anr()` - `set_anr` --- ### Endpoint `[1.7]` eq ### Response #### Success Response - **min** - Minimum EQ value - **max** - Maximum EQ value - **current** - Current EQ value - **band_id** - Band identifier ### High-level methods - `eq()` --- ### Endpoint `[1.9]` buttons ### Response #### Success Response - **bid** - Button identifier - **evt** - Event type - **action** - Action to perform - **capability bits** - Capability flags ### High-level methods - `buttons()` --- ### Endpoint `[1.10]` multipoint ### Response #### Success Response - **bits** - Bit1 = on ### High-level methods - `multipoint()` --- ### Endpoint `[1.11]` sidetone ### Response #### Success Response - **persist** - Persistence flag - **level** - Sidetone level - Returns `payload[1]` ### High-level methods - `sidetone()` --- ### Endpoint `[1.24]` auto_pause / `[1.27]` auto_answer ### Response #### Success Response - **0/1** - Boolean value ### High-level methods - `auto_pause()` / `auto_answer()` --- ### Endpoint `[5.1]` source ### Response #### Success Response - **supported_hi** - High supported bits - **supported_lo** - Low supported bits - **active_type** - Active source type - **MAC bytes** - 6 MAC address bytes at `[3:9]` (bluetooth only) ### High-level methods - `source()` --- ### Endpoint `[31.3]` current_mode ### Response #### Success Response - **mode_idx** - Mode index ### High-level methods - `mode_idx()` --- ### Endpoint `[31.10]` audio_settings ### Response #### Success Response - **cnc** - CNC value - **auto_cnc** - Auto CNC value - **spatial** - Spatial audio value - **wind** - Wind reduction value - **anc** - ANC value ### High-level methods - `audio_settings()` --- ### Endpoint `[31.6]` mode_config (STATUS Async) ### Response #### Success Response - ModeConfig STATUS frame (44/47/48 bytes) - One per slot after `get_all_modes` START ### High-level methods - `modes()` ``` -------------------------------- ### eq / eq flat / eq get Source: https://github.com/aaronsb/bosectl Set EQ bands (each -10 to +10), reset to 0/0/0, or just print bands. No args prints too. ```APIDOC ## eq / eq flat / eq get ### Description Set EQ bands (each -10 to +10), reset to 0/0/0, or just print bands. No args prints too. ### Usage `bosectl eq 5 -3 2` `bosectl eq flat` `bosectl eq get` `bosectl eq` ### Parameters - `B` (integer -10 to +10) - Required for set - Bass band - `M` (integer -10 to +10) - Required for set - Mid band - `T` (integer -10 to +10) - Required for set - Treble band ``` -------------------------------- ### Rust feature dispatch example (anr method) Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Method-based feature dispatch in Rust. Reads the config field for the ANR feature, returns Unsupported error if None, then gets and parses the payload. ```rust pub fn anr(&self) -> BmapResult<&'static str> { let addr = self.addr(self.config.anr)?; // None → Unsupported error let payload = self.get(addr)?; Ok(parse_anr(&payload)) } ``` -------------------------------- ### Iterate device modes with pybmap.connect() Source: https://github.com/aaronsb/bosectl Example usage of the modes() method inside a context manager. Returns a dict keyed by mode_idx with ModeConfig values. ```python with pybmap.connect() as dev: for idx, mc in dev.modes().items(): print(idx, mc.name, mc.editable, mc.cnc_level) ``` -------------------------------- ### Operator enum (Rust) Source: https://github.com/aaronsb/bosectl Rust enum representing BMAP operators with values Set, Get, SetGet, Status, Error, Start, Result, and Processing. Python encodes the same set as pybmap.constants.OP_SET … OP_PROCESSING (ints 0–7). ```rust #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[repr(u8)] pub enum Operator { Set = 0, Get = 1, SetGet = 2, Status = 3, Error = 4, Start = 5, Result = 6, Processing = 7 } ``` -------------------------------- ### set_prompts Source: https://github.com/aaronsb/bosectl Enables or disables voice prompts. Gets the current language, preserves it, and sets the prompts setting. ```APIDOC ## set_prompts ### Description Enables or disables voice prompts. Gets the current language, preserves it, and sets the prompts setting. ### Method void set_prompts(bool enabled); ### Parameters - **enabled** (bool) - Required - Whether to enable voice prompts. ``` -------------------------------- ### GET [5.1] Query Active Source Source: https://github.com/aaronsb/bosectl/blob/main/NOTES.md Queries the currently active audio source. Returns a bitset of supported sources, the active source type, and source-specific data such as a Bluetooth MAC address. ```APIDOC ## [GET] [5.1] ### Description Queries the currently active audio source. Returns a bitset of supported sources, the active source type, and source-specific data such as a Bluetooth MAC address. ### Method GET ### Endpoint [5.1] ### Response #### Success Response (200) - **Supported sources** (bitset, 2 bytes) - Bitmask of supported source types. - **Active source type** (byte) - 0=NONE, 1=BLUETOOTH, 2=AUXILIARY. - **Source-specific data** (variable) - For BLUETOOTH: 6-byte MAC address; for AUXILIARY: none. #### Response Example ``` [0-1] Supported sources (bitset, 2 bytes) [2] Active source type: 0=NONE, 1=BLUETOOTH, 2=AUXILIARY [3+] Source-specific data (BLUETOOTH: 6 bytes MAC address) ``` ``` -------------------------------- ### RfcommTransport usage example Source: https://github.com/aaronsb/bosectl Connects to a device over RFCOMM and sends a Get request for function 5 on fblock 0. Requires the bmap transport and protocol modules; the transport uses Linux Bluetooth sockets. ```rust use bmap::transport::{RfcommTransport, Transport}; use bmap::protocol::{bmap_packet, Operator}; let t = RfcommTransport::connect("68:F2:1F:0D:F5:11", 2)?; let data = t.send_recv(&bmap_packet(0, 5, Operator::Get, &[]))?; ``` -------------------------------- ### Release Process Commands Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Steps to run tests, build artifacts, and create a tagged release with binaries. ```bash # 1. Ensure all tests pass and artifacts build make test make artifacts # 2. Create a tagged release with binaries make release VERSION=v0.2.0 # This runs: test → artifacts → gh release create # Binaries are named: bmapctl-{rust,cpp}-linux-{arch} # SHA256SUMS is included for verification ``` -------------------------------- ### bmap::catalog usage example: lookup_device, is_supported, modalias Source: https://github.com/aaronsb/bosectl Shows how to use the catalog functions: lookup_device(0x4082) returns a device with codename "wolverine", and is_supported(0x4075) returns true. ```rust use bmap::catalog::{lookup_device, is_supported, modalias}; let dev = lookup_device(0x4082).unwrap(); assert_eq!(dev.codename, "wolverine"); assert!(is_supported(0x4075)); ``` -------------------------------- ### modes() Source: https://github.com/aaronsb/bosectl Starts `get_all_modes` (`[31.1]` START) with drain, collects every `[31.6]` STATUS with a payload ≥ 6 bytes, keyed by `mode_idx`. ```APIDOC ## modes() ### Description Starts `get_all_modes` (`[31.1]` START) with drain, collects every `[31.6]` STATUS with a payload ≥ 6 bytes, keyed by `mode_idx`. ### Returns - `dict[int, ModeConfig]` - Mode configurations keyed by mode index ### Example ```python with pybmap.connect() as dev: for idx, mc in dev.modes().items(): print(idx, mc.name, mc.editable, mc.cnc_level) ``` ``` -------------------------------- ### Build from source Source: https://github.com/aaronsb/bosectl/blob/main/README.md Clones the repository and runs `make test` to run all tests (Python + Rust + C++), or `make artifacts` to build release binaries and SHA256SUMS. Requires BlueZ development headers, CMake, and a Rust toolchain. ```bash git clone https://github.com/aaronsb/bosectl.git cd bosectl make test # Run all tests (Python + Rust + C++; automatically installs macOS test deps and handles missing toolchains) make artifacts # Build release binaries + SHA256SUMS ``` -------------------------------- ### pybmap.connect() Source: https://github.com/aaronsb/bosectl/blob/main/README.md Establishes a connection to a Bose device and returns a device object for interacting with the device. ```APIDOC ## pybmap.connect() ### Description Establishes a connection to a Bose device and returns a device object for interacting with the device. ### Method connect() ### Parameters None ### Returns Device object with methods: battery(), name(), set_anr(), set_cnc(), set_eq(), set_buttons() ### Example ```python import pybmap with pybmap.connect() as dev: print(dev.battery()) # 80 print(dev.name()) # "Obsidian Countess" dev.set_anr("high") # QC35: full noise cancellation dev.set_cnc(8) # CNC level 0-10 (0=max ANC) dev.set_eq(3, 0, -2) # Bass +3, mid flat, treble -2 dev.set_buttons(0x10, 4, 2) # Remap Action button to ANC ``` ``` -------------------------------- ### Language-Specific Build Commands Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Build and test each language independently: Python, Rust, and C++. ```bash # Python — virtualenv auto-created make python-setup # create venv, install deps make python-test # run pytest make python-build # sdist + wheel in python/dist/ # Rust make rust-build # cargo build --release make rust-test # cargo test # C++ make cpp-build # cmake + make (Debug) make cpp-test # build + run bmap_tests ``` -------------------------------- ### pybmap.supported_devices() Source: https://github.com/aaronsb/bosectl/blob/main/README.md Returns a list of codenames for all supported devices. ```APIDOC ## pybmap.supported_devices() ### Description Returns a list of codenames for all supported devices. ### Method supported_devices() ### Parameters None ### Returns List of strings - Codenames of supported devices ### Example ```python pybmap.supported_devices() # [wolfcastle, baywolf, duran, prince, wolverine, lando, edith, serena] ``` ``` -------------------------------- ### Build Flow Diagram (Mermaid) Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Visualizes the build and release pipeline, including test and artifact stages. ```mermaid graph LR subgraph test PT[python-test] --> T[test] RT[rust-test] --> T CT[cpp-test] --> T end subgraph artifacts RB[rust-build
cargo build --release] --> A[artifacts] CB[cpp-build
cmake Release] --> A A --> STRIP[strip binaries] STRIP --> SHA[SHA256SUMS] end T --> REL[release] SHA --> REL REL --> GH[gh release create] style T fill:#26de81,stroke:#333,color:#fff style A fill:#4a9eff,stroke:#333,color:#fff style REL fill:#ff9f43,stroke:#333,color:#fff style GH fill:#a55eea,stroke:#333,color:#fff ``` -------------------------------- ### Project structure tree Source: https://github.com/aaronsb/bosectl/blob/main/README.md Shows the top-level layout of the repository, including the Python, Rust, and C++ libraries, docs, notes, Makefile, and fixtures directory. ```text ├── python/pybmap/ # Python library + bosectl CLI ├── rust/src/ # Rust library + bmapctl CLI ├── cpp/src/ # C++ library + bmapctl CLI ├── docs/ # Architecture guide, device docs ├── NOTES.md # Protocol reverse engineering notes ├── Makefile # Build, test, release across all languages └── fixtures/ # Captured protocol data ``` -------------------------------- ### power_off() Source: https://github.com/aaronsb/bosectl Sends START [7.4] payload [0x00]. ```APIDOC ## power_off() ### Description Sends START `[7.4]` payload `[0x00]`. ``` -------------------------------- ### Makefile build and release commands Source: https://github.com/aaronsb/bosectl/blob/main/README.md Lists the primary Makefile targets for testing, building artifacts, creating a release, and cleaning build outputs. ```bash make test # All tests (Python, Rust, C++) make artifacts # Build + strip + SHA256SUMS in dist/ make release VERSION=vX.Y.Z # Test → build → gh release create make clean # Remove all build artifacts ``` -------------------------------- ### mode_idx() Source: https://github.com/aaronsb/bosectl Returns the raw mode index (GET `[31.3]`). ```APIDOC ## mode_idx() ### Description Returns the raw mode index (GET `[31.3]`). ### Returns - `int` - Raw mode index ``` -------------------------------- ### require() helper for unsupported features Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Converts std::nullopt to an unsupported_error exception when a feature is missing on the device. Throws with a message including the feature name. ```cpp static Addr require(const std::optional& opt, const char* name) { if (!opt) throw unsupported_error(std::string(name) + " not supported on this device"); return *opt; } ``` -------------------------------- ### parse_product_name Source: https://github.com/aaronsb/bosectl Parses the product name from a payload, starting from the second byte. ```APIDOC ## parse_product_name ### Description Parses the product name from a payload, starting from the second byte. ### Signature `fn parse_product_name(payload: &[u8]) -> String` ### Parameters - **payload** (`&[u8]`) - Required - The raw payload bytes. ### Returns - `String` - The product name string. ``` -------------------------------- ### Python package layout (pybmap/) Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Directory tree of the Python implementation under python/pybmap/. Shows module responsibilities and device config modules. ```text pybmap/ ├── __init__.py # connect() entry point, public API re-exports ├── catalog.py # Device catalog (PIDs, codenames, USB/Modalias IDs) ├── protocol.py # Packet codec (bmap_packet, parse_response) ├── transport.py # RfcommTransport (AF_BLUETOOTH socket) ├── connection.py # BmapConnection class ├── cli.py # bosectl command-line interface ├── discovery.py # find_bmap_device() via bluetoothctl ├── constants.py # Operators, error codes, button/action/language tables ├── types.py # NamedTuples (BmapResponse, ModeConfig, ButtonMapping, etc.) ├── errors.py # Exception hierarchy └── devices/ ├── __init__.py # Device registry (DEVICES dict, get_device()) ├── parsers.py # Shared parser/builder functions ├── qc_ultra2.py # QC Ultra 2 config (module-level constants) ├── qc_ultra2_earbuds.py # QC Ultra 2 Earbuds config (shared layout) ├── qc_prince.py # QuietComfort Headphones / prince config ├── qc45.py # QC45 config ├── qc_earbuds.py # QuietComfort Earbuds config ├── ultra_open.py # Ultra Open Earbuds partial config └── qc35.py # QC35 config (module-level constants) ``` -------------------------------- ### start_drain Source: https://github.com/aaronsb/bosectl Low-level method to start a drain operation with a given address and payload. ```APIDOC ## start_drain ### Description Low-level method to start a drain operation with a given address and payload. ### Method Low-level Operation ### Parameters - `addr` (Addr) - Required - Address - `payload` (&[u8]) - Required - Payload bytes ### Returns BmapResult> - List of responses ``` -------------------------------- ### source Source: https://github.com/aaronsb/bosectl Prints bluetooth (MAC), auxiliary, or none. ```APIDOC ## source ### Description Prints bluetooth (MAC), auxiliary, or none. ### Usage `bosectl source` ``` -------------------------------- ### build_audio_settings(cnc_level=0, auto_cnc=False, spatial=0, wind_block=True, anc_toggle=True) Source: https://github.com/aaronsb/bosectl Builds a 5-byte audio settings payload with configurable parameters. ```APIDOC ## build_audio_settings(cnc_level=0, auto_cnc=False, spatial=0, wind_block=True, anc_toggle=True) ### Description Builds a 5-byte audio settings payload with configurable parameters. ### Method Function ### Parameters - **cnc_level** (int, optional) - Default 0 - CNC level. - **auto_cnc** (bool, optional) - Default False - Auto CNC flag. - **spatial** (int, optional) - Default 0 - Spatial audio setting. - **wind_block** (bool, optional) - Default True - Wind block flag. - **anc_toggle** (bool, optional) - Default True - ANC toggle flag. ### Returns - **bytes** - 5-byte payload. ``` -------------------------------- ### LinuxRfcommTransport usage example Source: https://github.com/aaronsb/bosectl Connects to a device and sends a BMAP packet with drain=True. ```python from pybmap.transport import LinuxRfcommTransport, RfcommTransport with LinuxRfcommTransport("68:F2:1F:0D:F5:11", channel=2) as t: data = t.send_recv(bytes([0x1f, 0x03, 0x05, 0x02, 0x00, 0x00]), drain=True) ``` -------------------------------- ### Create, set mode, and delete profile Source: https://github.com/aaronsb/bosectl Shows the typical workflow for managing a profile: create a profile with settings, set its mode, then delete it. The create_profile call returns the slot index and may fail with Device("No free profile slot available") when full. ```rust let slot = dev.create_profile("Commute", 6, 0, true, true)?; dev.set_mode("Commute", false)?; dev.delete_profile("Commute")?; ``` -------------------------------- ### Python library usage with pybmap.connect Source: https://github.com/aaronsb/bosectl/blob/main/README.md Connect to a Bose device and control battery, name, ANC, CNC, EQ, and buttons. Comments show expected values and valid ranges (e.g., CNC 0-10, 0=max ANC). ```python import pybmap with pybmap.connect() as dev: print(dev.battery()) # 80 print(dev.name()) # "Obsidian Countess" dev.set_anr("high") # QC35: full noise cancellation dev.set_cnc(8) # CNC level 0-10 (0=max ANC) dev.set_eq(3, 0, -2) # Bass +3, mid flat, treble -2 dev.set_buttons(0x10, 4, 2) # Remap Action button to ANC ``` -------------------------------- ### set_prompts(enabled) Source: https://github.com/aaronsb/bosectl Writes with the device's builder via SETGET. Reads the current language and preserves it. ```APIDOC ## set_prompts(enabled) ### Description Writes with the device's builder via SETGET. Reads the current language and preserves it. ### Parameters - **enabled** (bool) - Required - Enable or disable voice prompts ``` -------------------------------- ### name [TEXT] Source: https://github.com/aaronsb/bosectl Set and print the device name. ```APIDOC ## name [TEXT] ### Description Set and print the device name. ### Usage `bosectl name MyHeadphones` `bosectl name` ### Parameters - `TEXT` (string) - Optional - New device name ``` -------------------------------- ### Rust source layout (rust/src/) Source: https://github.com/aaronsb/bosectl/blob/main/docs/architecture.md Directory tree of the Rust implementation under rust/src/. Shows module responsibilities and device config factory functions. ```text rust/src/ ├── lib.rs # connect() entry point, public re-exports ├── catalog.rs # Device catalog (PIDs, codenames, USB/Modalias IDs) ├── protocol.rs # Packet codec, BmapResponse struct ├── transport.rs # Transport trait + RfcommTransport (libc sockets) ├── connection.rs # BmapConnection generic struct ├── discovery.rs # find_bmap_device() via bluetoothctl ├── device.rs # DeviceConfig struct, all parsers/builders ├── devices.rs # qc_ultra2() / qc_ultra2_earbuds() / qc35() ├── error.rs # BmapError enum, BmapResult type alias └── main.rs # CLI binary (bmapctl) ``` -------------------------------- ### switch Source: https://github.com/aaronsb/bosectl Switch to a preset or custom profile mode. ```APIDOC ## switch ### Description Switch to a preset or custom profile mode. ### Usage `bosectl switch ` ### Parameters - `name` (string) - Required - The preset or custom profile name ### Behavior - Calls `dev.set_mode(name)` ``` -------------------------------- ### route(mac) Source: https://github.com/aaronsb/bosectl Sends DeviceManagement ROUTING [4.12] START with build_routing(mac) payload ([0x82] + 6 MAC bytes). ```APIDOC ## route(mac) ### Description Sends DeviceManagement ROUTING `[4.12]` START with `build_routing(mac)` payload (`[0x82] + 6 MAC bytes`). ### Parameters - **mac** (string) - Required - MAC address ``` -------------------------------- ### Read battery percentage with pybmap.connect() Source: https://github.com/aaronsb/bosectl Example usage of the battery() method inside a context manager. Returns an integer battery percentage (aggregate). ```python with pybmap.connect() as dev: level = dev.battery() # 80 ``` -------------------------------- ### current Source: https://github.com/aaronsb/bosectl Prints the current mode name. ```APIDOC ## current ### Description Prints the current mode name. ### Usage `bosectl current` ```