Session-owned virtual BLE peripherals¶
blePeripheral is a plain daemon tool with session ownership enforced at ingress and at handle lookup. It requires a live session, defaults to that session’s device and refuses another device target. Multiple handles are supported. GATT state is ephemeral and excluded from device mutation journaling and plan recording.
BlePeripheralManager owns a BlePeripheralSidecar per handle. A start registers ownership before awaiting provisioning. Session release/unbind aborts pending starts and kills every owned sidecar; daemon child-process cleanup closes admission and kills all remaining sidecars. Cleanup failures retain ownership for retry. A successful stop removes its handle; a failed one keeps it for retry. When a start fails, the start error is the one reported. Its cleanup stop removes the entry only when the kill is confirmed; a cleanup failure is logged and the entry stays owned, so session release, unbind or daemon shutdown retries the kill. Released-session tombstones only fence calls that race the release, so the newest 256 are kept. Sidecar exit is confirmed through the shared child-process tracker, with bounded SIGKILL teardown. Request cancellation interrupts startup; successful peripherals remain until explicit stop or owner cleanup.
PythonEnvProvisioner uses the existing data-directory resolver, including AUTOMOBILE_DATA_DIR, under ble-peripheral/venv. An injected host command runner creates the venv and installs bumble==0.0.236, grpcio==1.85.1 and protobuf==7.36.2. Concurrent starts share provisioning. python3 --version must report 3.11 or newer before any venv work. The exact pin-set marker is written only after installation succeeds. A missing or stale marker means the venv may be half-built (interpreter without pip, interrupted install), so it is rebuilt with venv --clear before installing. Python packages stay outside the npm runtime graph. Missing Python and provisioning errors carry repair instructions; doctor warns because only BLE needs Python.
The checked-in Python asset is copied beside bundled TypeScript chunks into dist/src/ble-peripheral.py. The process client resolves either the source asset or that packaged sibling independently of the daemon’s working directory. Python runs with isolated imports and unbuffered output. The first stdin JSON line contains the GATT configuration; subsequent lines carry numbered notify/status/stop commands.
The sidecar watches stdin for EOF only after the transport opens, so open_transport has a 20 s timeout. A hung open cannot outlive a killed daemon by more than that, and the timeout error names the transport and the bound. Provisioning the shared venv holds a file lock on its directory, so two daemon processes cannot run venv --clear over each other. A process that waited re-checks the pins marker before rebuilding. Stdout contains JSON events and acknowledgements: ready, advertising, connected, disconnected, status, notified, stopped and error. Commands have deadlines through the injected Timer; process failure, malformed output and pipe closure reject outstanding requests. Status includes advertised configuration, readiness, connections and subscribed characteristic UUIDs.
BleTransportResolver always discovers the session device’s transport. An explicit transport must be android-netsim or android-netsim:localhost:<port> (no other Bumble scheme). It must equal the discovered one, so a session cannot reach another emulator’s netsim. Discovery uses the running-AVD advertisement reader to correlate the emulator serial with a live PID, and the host process-table reader to recover the launcher’s -packet-streamer-endpoint localhost:<port> argument. An explicit console port can identify a process without an advertisement. This works for a private netsimd retained across daemon restarts and avoids confusing the emulator’s own gRPC port with netsimd’s port. A valid private endpoint becomes android-netsim:localhost:<port>; no known private endpoint falls back to android-netsim, the host-wide shared instance.
Isolation is opt-in (AUTOMOBILE_EMULATOR_NETSIM_ISOLATION), so every result reports transportShared (true only for plain android-netsim) and a warning naming the variable. A private netsimd is owned by the launch that spawned its emulator, not by the daemon or the BLE manager. It stops when that emulator exits, and an emulator retained across a daemon stop keeps it. An emulator killed while no daemon observes it relies on netsimd’s own shutdown, since --no-shutdown is stripped. Unreadable or ambiguous identity is actionable rather than silently selecting the shared instance.
BatteryService reads from a mutable-level callback, including notification reads. Heart-rate measurements use the profile serializer and callback. Custom read/notify characteristics hold byte values. Advertising includes the local name and selected standard service UUIDs. A central connection pauses advertising; Bumble’s auto_restart=True resumes it after disconnect. Subscription state is tracked per connection and characteristic, and removed on disconnect. A crash clears runtime state; clients start a new handle rather than automatically replaying peripheral state.