At a glance
7 of 124
Profiles that can send commands
1 verified, 6 experimental, 117 scan-only in src-tauri/catalog/models
2
Wire framings
Bare AA/BA, and 789C with a length field and a CRC-16
166 + 49
Rust and frontend tests
Last full run recorded in CHANGELOG 0.1.3; one hardware test is ignored
5
Interface languages
English, Vietnamese, Simplified Chinese, Spanish, Brazilian Portuguese
✎ Key Insights in 30 Seconds
Build log: A build log of an unofficial desktop app for Baseus earbuds: two wire framings (bare AA/BA and a 789C frame with CRC-16), a Rust session model that refuses stale state, 124 catalog profiles of which 7 can send commands, and an honest list of what is still unverified.
Problem Context
Baseus earbuds have a phone app and no documented protocol. To control them from a PC I had to work out the GATT service, two frame formats and a pile of opcodes, without breaking earbuds I own or claiming support for models I never touched.
Architecture & Design
A SolidJS UI inside Tauri 2 talks to a Rust backend through 24 commands and versioned events. The backend resolves each scanned device to a reviewed JSON profile, picks one of two codecs (bare AA/BA or 789C with CRC-16), drives btleplug under a session token, and publishes confirmed state as snapshots carrying a session ID and revision. The UI trusts snapshots, never write acknowledgements.
Key Technical Decisions
- 1Authorize writes from reviewed profiles only, matching names and aliases exactly. Consequence: 117 of 124 catalog models show a name and picture but no controls, and a model gains buttons only after someone traces its transport.
- 2Give each wire family its own codec and refuse to fall back to BP1 decoding. Consequence: adding a model with a new format means a new codec plus test vectors, which is slower but cannot silently misread a frame.
- 3Treat a state notification in the same session as the only confirmation. Consequence: every setter waits for a readback or fails, and a feature with no readback (Pro spatial mode) shows unknown instead of a guess.
- 4Tag every snapshot with a session ID and revision and drop anything older. Consequence: a late reply from before a reconnect cannot repaint the UI, at the cost of extra bookkeeping on both sides of the bridge.
- 5Keep Windows as the tested platform and say so. Consequence: the macOS and Linux paths compile but are unproven, and the README wording needs to match.
The itch: a control app that lives on the phone
Baseus ships its control app for phones. The README says what I wanted instead: switch noise cancelling (ANC), transparency and adaptive modes, change the EQ, toggle spatial audio and game mode, and read battery levels from a PC, without the phone app. B4S is that tool, an independent and unofficial desktop app (Tauri 2, Rust, SolidJS) that the README describes as running on Windows, macOS and Linux. Windows is the only platform I have tested on.
The Android app pulls its model list and per-model parameters from the vendor's servers (my notes on APK 2.17.0.1 list the getModelParams endpoint). B4S embeds a snapshot of the public catalog instead: 124 headphone identities from a 174-product snapshot fetched on 2026-10-05. The README's privacy section says B4S needs no account and sends no device or personal data anywhere; the network is used for the update check and for links I click.
I did not write down why I picked Tauri over Electron, so I will not invent a reason. What the repo does record is the rule that came out of the reverse-engineering: a name match alone never switches a control on. That rule is most of this article.
How I worked out the protocol
There was no vendor documentation, so the protocol came from three sources, and the repo keeps them apart.
1. A predecessor. The header comment of protocol/mod.rs says the codec was reverse-engineered from the official app plus "live BLE captures on Bass BP1 Pro ANC", and cites elaxptr/baseus-desktop (MIT) as the source of those captures. The repo does not say how much of the early BP1 Pro work I took from it, so I will not guess; the credit belongs here either way.
2. The official Android app. Versions 2.14.1 and 2.17.0.1, decompiled locally with jadx 1.5.6 for personal interoperability. The 2.17.0.1 run gave 42,724 classes and 508 reported errors, so I treat it as a map with holes. A DEX string scan found 180 literal BA command candidates and 84 UUID candidates, including other device families. The APKs and decompiled output are gitignored; the repo keeps only short findings.
3. The earbuds. On 2026-10-06 I exercised a BP1 Ultra on Windows 11 with btleplug and a debug build; firmware unknown. For each feature I compared the Android source with a query, changed a setting, read it back and restored it.
Things the notes record as surprises:
- I had assumed
AA43was EQ state. The Android consumer showsAA42is spatial-audio state andAA43is only an acknowledgement. EQ selection isBA30/AA30. A decoder test still carries the scar: an early version forced opcode0x33to mean ANC, andanc_no_false_aa33now asserts thatAA 33alone decodes to nothing on the Pro. - On the Ultra, ANC state arrives on
AA33, notAA34. - LDAC is an inverted flag (
BA75 00means enabled), and two Android call sites disagree on polarity, so I kept the one I read back on hardware. - The Ultra advertised its name from two BLE addresses, and only one advertised the vendor service. One discovery attempt returned
NotConnected; a retry worked. Reading the notify characteristic returned nothing, but enabling notifications produced valid frames immediately, with no handshake write.
! careful
The jadx run reported 508 errors, so a method I read in decompiled output is a lead, not a fact. Anything that matters was then checked against the earbuds, or is labelled unverified below.
The wire format and the commands
All seven reviewed profiles use the same GATT service and characteristic UUIDs (service 53527aa4-…, write ee684b1a-…, notify 654b749c-…). What differs is the framing. There are two.
Bare AA/BA (BP1 Pro, EP10 Pro, M3s)
No length field and no checksum. A write is BA <cmd> <payload…>; a notification is AA <cmd> <payload…>. My Frame type in framing.rs is exactly that: magic, command, the rest.
789C wrapped (BP1 Ultra, EP10 Ultra, M4s, MS1)
| Offset | Bytes | Meaning |
|---|---|---|
| 0–1 | 78 9C | Magic |
| 2–3 | u16 big-endian | Total frame length, header and CRC included |
| 4 | 02 | Constant in every captured frame |
| 5 | 00 / 01 / 03 | Type byte, chosen from the opcode |
| 6 | u8 | Length of the opcode and payload |
| 7… | opcode, payload | The same bytes a bare frame would carry after BA |
| last 2 | u16 big-endian | CRC |
The type byte comes from a table in the Android app: 03 for set opcodes (0x34, 0x24, 0x43, 0x54, 0x75, 0x94), 01 for queries (0x02, 0x23, 0x27, 0x33, 0x42, 0x53, 0x74, 0x93), and a shorter layout with no type byte for the rest. I once had it partly wrong (BA42, BA74, BA3F are type 01; BA43, BA75 are type 03), so the CRC tests now use frames captured from the device, not only frames my encoder produced.
// src-tauri/src/protocol/wrap_v2.rs (trimmed)
pub fn crc16(data: &[u8]) -> u16 {
let mut i2: u32 = 65535;
for &b in data {
let i4 = CRC_TABLE[((b as u32) ^ i2) as usize & 0xFF] as u32;
i2 = ((i2 ^ i4) >> 8).wrapping_add((i4 & 0xFF) << 8);
}
(i2 & 0xFFFF) as u16
}
// ...inside wrap_ba_command, for type 01/03:
let length = substring2.len() as u16;
body.extend_from_slice(&(length + 9).to_be_bytes());
body.push(0x02);
body.push(ty);
body.push(length as u8);
body.extend_from_slice(&substring2);
let c = crc16(&body);
The table comes from the app's CRC helper. Recomputing four frames from bp1-ultra-ble.md, I found it equals standard CRC-16/MODBUS (init 0xFFFF, reflected 0xA001) sent high byte first. The repo's comments do not say "Modbus"; that is my reading.
One captured exchange: the battery query is 78 9C 00 0A 02 01 01 02 A8 52 (length 10, type 01, one body byte, opcode 02). The reply is 78 9C 00 0E 02 01 05 02 64 00 64 01 2C 56. Unwrap it, prefix AA, and it is AA 02 64 00 64 01: left 100%, right 100%. The case battery is a separate query, BA 27.
Commands I implemented
| Command | Write | State reply | Notes |
|---|---|---|---|
| Battery | BA 02 | AA 02 <L%> 00 <R%> 01 | Zero is a value; the decoder also strips a 0x80 charging bit |
| ANC / transparency | BA 34 <mode> <param> | AA 34 (Pro), AA 33 (Ultra) | Mode and parameter both count |
| Game mode | BA 24 <00|01> | AA 23 <flag> after BA 23 | |
| Spatial audio | BA 43 <mode> | AA 42 after BA 42 | AA 43 is an ACK only |
| Bass boost | BA 54 <level> (Pro), BA 54 <on> <level> (Ultra) | AA 53 after BA 53 | Levels 1–5 in the Ultra source |
| EQ select / custom | BA 31 <slot> <filters…> | AA 30 <index> after BA 30 | Index only, no coefficients |
| Find buds | BA 10 02 01 / … 00 | none confirmed | Behind a safety dialog |
How EQ bands are encoded
Each filter is eight bytes: frequency, gain, Q and filter type, each a little-endian u16. Gain is gain × 10 + 120 (so −12 dB is 0); Q is Q × 10, truncated, as in the Android code.
// src-tauri/src/protocol/families/bp1.rs
pub fn cmd_set_eq_filters(index: u8, filters: &[EqBand]) -> Vec<u8> {
let mut payload = vec![index];
for filter in filters {
payload.extend_from_slice(&filter.frequency.to_le_bytes());
payload.extend_from_slice(&((filter.gain * 10.0 + 120.0) as u16).to_le_bytes());
payload.extend_from_slice(&((filter.q_value * 10.0) as u16).to_le_bytes());
payload.extend_from_slice(&(filter.filter as u16).to_le_bytes());
}
Frame::write(0x31, &payload).encode_write()
}
// test vector: 190 Hz, -5.8 dB, Q 0.64, type 1
// -> BA 31 00 | BE 00 3E 00 06 00 01 00
A Q of 0.64 goes over the wire as 6. The BP1 Pro's custom EQ has eight bands (100, 200, 400, 800, 1000, 3000, 6000, 10000 Hz), ±12 dB, Q fixed at 1, written to slot 101. Its seven presets are not eight-band curves; each is six or seven parametric filters, so the UI no longer draws preview curves for them.
The Rust BLE layer: sessions, writes and confirmation
The BLE layer is btleplug 0.13.4 (locked) on Tokio: separate discovery, scanning, connection, transport and commands modules around one owner of mutable state, runtime.rs. The connect path in connection.rs:
- A
try_lockallows one connect attempt at a time. It refuses before touching the radio unless the profile declares BLE GATT and a known protocol family. - Stop scanning. If another device is connected, disconnect it and pause 400 ms. Reset link state.
connect(), then a 250 ms sleep; the comment says "Windows needs this after reconnect". No measurement sits behind that number.discover_services()and log every service and characteristic of this OS entry. If the profile's service is absent, the error suggests the audio entry and the other scan row.- Check the write and notify characteristics. Create the notification stream before subscribing, so the Ultra's immediate battery reports are buffered; if subscribe fails, rediscover once and retry.
- Write the profile's handshake bytes:
BA 05 00for the BP1 Pro, nothing for the other six profiles. A#InitState:write exists, but none of the seven profiles turns it on. - Run the profile's startup queries, 80 ms apart, then publish the device and start a battery poller.
// src-tauri/src/device/session.rs
pub fn invalidate(&mut self) {
self.generation = self.generation.checked_add(1).expect("session epoch exhausted");
self.changes.send_replace(self.generation);
}
pub fn accepts(&self, token: SessionToken) -> bool { self.token() == token }
The session token is the idea that took longest to get right. A reconnect to the same earbuds is a new session, and work still in flight from the old one has to die quietly. Every task holds a lease on its token, every await that can outlive a disconnect re-checks accepts, and disconnect() invalidates first and cleans up the OS handle afterwards. Notifications go through a NotificationReceiver. For 789C it reassembles frames split or coalesced across notifications (a test splits a valid frame at every byte offset), caps a frame at 4096 bytes and drops a half-built frame after two seconds. For bare AA/BA it assumes one notification is one frame; I never saw otherwise, but nothing enforces it.
Writes are serialised. A CommandExecutor admits at most 16 queued commands, gives each a five-second deadline and runs them one at a time. A completed write is not a success: AA/BA has no request ID, so confirmation.rs subscribes first, writes, then waits for a same-session state notification matching the expected value. Its header comment states the limit: this proves observed state, not that this write caused it. On the Pro I have no spatial-mode readback, so the UI leaves the mode unknown.
Several models, one rule: reviewed profiles
The Android app talks to dozens of Baseus products; I can verify almost none. src-tauri/catalog/models/ holds 124 JSON profiles, embedded by build.rs and validated at load (duplicate IDs, unregistered families, bad capabilities or inconsistent EQ fail).
| Support level | Profiles | Meaning in the app |
|---|---|---|
verified | 1 (BP1 Pro) | Controls enabled |
experimental | 6 (BP1 Ultra, EP10 Ultra, M4s, MS1, EP10 Pro, M3s) | Controls only with Settings → Experimental mode |
scanOnly | 117 | Name and image, no controls |
Two codecs back the controllable profiles: bp1 (bare) for Pro, EP10 Pro and M3s, and bp1Ultra (789C) for Ultra, EP10 Ultra, M4s and MS1. The Android source has an exact-name table of 57 models with a framing flag, 25 of them wrapped. The framing in my seven controllable profiles matches that table.
// src-tauri/catalog/models/bowie-m3s.json (trimmed)
"support": "experimental",
"protocolFamily": "bp1",
"capabilities": { "anc": true, "eq": false, "customEq": false,
"gameMode": true, "bassBoost": true, "spatial": true,
"gesture": true, "windNoise": true, "findBuds": false,
"inEar": false, "multipoint": false, "ldac": false, ... }
A profile records what a button may send: fifteen capability flags plus per-model constraints (ANC environments 101, 102, 103 and 108, a maximum custom level of 5, EQ bands and gain limits, gesture layouts). authorize_control refuses a write unless the profile is verified, or experimental with the global Experimental switch on. Six features (gesture, in-ear, multipoint, restore defaults, adaptive L/R, wind-noise reduction) need that switch even on the Pro.
The four rules I enforce, all from CLAUDE.md:
- Identity is an exact name or alias match, never a substring, and never inherited from a similar model.
- An unknown protocol family cannot fall back to BP1 decoding. A new family needs its own codec, catalog registration and test vectors.
- Transport uses only the selected OS entry and the profile's declared UUIDs, handshake and framing. No generic characteristic probing.
- Hardware verification is recorded per feature, model, firmware, transport and platform; replaying a synthetic capture never promotes anything to "verified".
Five of the six experimental profiles come from exact-name evidence in the Android app and were never run on hardware. The Ultra is the only experimental one I have driven.
✎ note
A catalog entry that only names a device is not a profile. Recognition and permission to send bytes are separate facts in the code, and the support level of a model can only go up with hardware evidence.
The Tauri and SolidJS bridge, and the platforms
The Rust side exposes 24 Tauri commands and a handful of events (ble://scan-status, ble://connection, ble://link, ble://connecting, device://snapshot). The scan, connection and link DTOs carry a contract version, and the TypeScript adapters in src/lib/ble.ts and src/bridge/deviceSnapshot.ts reject versions they do not know, so a payload change has to land on both sides in one commit.
State on the frontend follows the same distrust of acknowledgements as the backend. A snapshot carries a session ID and a revision, and a small SolidJS-independent store orders them:
// src/stores/deviceSession.ts (trimmed)
accept(next: DeviceSnapshot) {
if (!deviceId || next.deviceId !== deviceId || next.schemaVersion !== 2
|| next.sessionId < minimumSession) return;
if (snapshot && (next.sessionId < snapshot.sessionId ||
(next.sessionId === snapshot.sessionId && next.revision <= snapshot.revision))) return;
if (snapshot && next.sessionId !== snapshot.sessionId) { generation++; onSnapshot(null); }
snapshot = next;
minimumSession = next.sessionId;
onSnapshot(next);
}
Each feature (listening, EQ, gestures, spatial, game mode, find buds) has a controller under src/features/ that runs a confirmed operation: the button stays pending until a fresh snapshot confirms, and a stale completion from an old session is discarded. The EQ controller also knows that EQ cannot be edited while spatial audio is on, and asks first.
One bug came from live UI testing: the DeviceCommand enum renamed its variants to camelCase but not its struct fields, so transparencyMode and dictSort were rejected before reaching BLE. rename_all_fields = "camelCase" fixed it, and tests now parse representative requests.
The UI ships five locales (English, Vietnamese, Simplified Chinese, Spanish, Brazilian Portuguese) via i18next, with check:i18n in CI. Settings live in a tauri-plugin-store file. The Tauri capability file is short (core:default, log, store, updater, and opener limited to the repo URL), but security.csp is null, which I should tighten.
Windows, macOS and Linux
Windows is where this was built and tested; the macOS and Linux claims rest on btleplug's backends and a build matrix, not on my using them.
- Windows. The same earbuds usually appear twice: an audio endpoint and an LE control entry. Only the control entry exposes the vendor service, so the other fails with the "audio entry" error. The scan list tags the entry advertising the service as Control and sorts it first. A Windows-only module (
ble/audio.rs,windowscrate 0.62) matches the default playback device's container ID against known BLE interfaces for "Quick connect"; names never establish identity, only a matching non-zero container ID does. - Linux. CI builds on ubuntu-24.04 with
libdbus-1-dev,libudev-devand WebKitGTK 4.1. I have not paired a headset on Linux. - macOS. The release workflow has a universal macOS job; the CI matrix has it commented out ("slower/costlier"). I found no Bluetooth usage-description string in the repo, which I believe CoreBluetooth needs. I have not built it on a Mac.
- Off Windows,
current_target()returnsNone, so users scan manually.
"Windows, macOS and Linux" in the README means where the app compiles; I should word it that way.
Tests, releases and what is still rough
CHANGELOG 0.1.3 records the last full run: 166 Rust tests (one hardware test ignored), 49 frontend tests, 7 catalog-parser tests and 15 extraction tests. The Rust tests need no Bluetooth; they cover command vectors, malformed frames, ACK versus state, old-session rejection and executor deadlines. They run with --test-threads=1 because the Experimental switch is process-global. My own grep finds 169 test attributes, which does not match the changelog exactly, so I trust the CI run over either number.
CI on Windows and Ubuntu runs the type-check, locale check, build, six Bun test groups, two Python tests, a generated support matrix that must not drift from docs/model-support-matrix.md, cargo check, cargo test --lib and an unsigned Tauri build. Releases are tag-driven (v*) with signed updater artifacts. The docs record one mistake I would rather tell than hide: the updater signing key was lost and replaced on 2026-10-07, so users on 0.1.1 or 0.1.2 must install 0.1.3 by hand once. Release CI now runs check-updater-key.mjs to reject a signature whose key ID differs from the configured public key.
Rough edges and what I would check next
This is the list I would work through next.
- "Verified" is stronger than my evidence. The BP1 Pro profile says
verified, but its own evidence matrix says no capture ID or firmware manifest is linked, and the profile's provenance line reads "firmware scope not yet captured". The Pro features are implemented and replay-tested. Most are not hardware-accepted. I should relabel it or capture the evidence. - Docs disagree with each other.
docs/protocol/overview.mdandmodels-catalog.mdstill say the BP1 Ultra is scan-only;bp1-ultra-ble.md, the README and the profile JSON say it is experimental. - Unresolved on hardware: Pro spatial mode readback, find-buds start and stop behaviour, restore defaults, the real LDAC codec switch on Windows, and whether
BA25,BA57andBA3Fdo anything on the Ultra (they got no reply). Ultra EQ stays off: anAA30index cannot read back coefficients, and writing slot 101 would overwrite a curve I cannot restore. - A transport puzzle. The Android guard table lists these model names under its Classic-Bluetooth dispatch, yet the GATT service answers on Windows. My notes do not reconcile that.
- Handshake state machine is half-wired.
handshake.rsmodels connect phases and a 30 s timeout, butconnection.rscalls only the first three transitions. The timeout is never evaluated. - Battery polling ends. The poller runs 40 iterations, every 2 s for the first five and every 10 s after, so about six minutes. Notifications keep updating state, but I have not checked whether the cutoff is intended.
- Not implemented: Gesture V2, the Classic-Bluetooth transport, SoundFit, OTA, any cloud feature. No latency or battery figures exist; I never measured them.
! careful
The BP1 Pro profile is labelled verified while its own evidence matrix links no capture or firmware manifest. Treat that label as stronger than the evidence until I fix one or the other.
Verified repository evidence
systems · direct
Built an unofficial desktop companion for Baseus earbuds with Tauri v2, Rust (btleplug) and SolidJS: local Bluetooth LE control, two wire framings (bare AA/BA and a 789C frame with CRC-16), and a catalog of 124 profiles of which 7 can send commands (1 verified, 6 experimental). Tested on Windows.
↳ Session model over btleplug that only exposes device-confirmed state; codecs live in src-tauri/src/protocol/ (wrap_v2.rs for the 789C frame) and profiles in src-tauri/catalog/models/.
hoan02/b4s ↗
Key Engineering Takeaways
- A reverse-engineered protocol is a pile of leads. Check each one against the device, and write down the ones you could not check.
- Without a request ID, a write acknowledgement proves little. Confirmation has to come from observed state in the right session.
- A label such as verified is a claim about evidence, so it has to point at evidence a reader can find.