libstealthtech Architecture

Crate Dependency Graph

stealthtech (CLI) ──► libstealthtech-core ──► btleplug (platform BLE)
                           ├── ble::{Scanner, Connection, GATT}
                           └── device::StealthTechDevice
                                    │
                      libstealthtech-protocol  (shared, no native deps)
                           ├── characteristics (UUIDs, constants)
                           ├── commands (encode/decode)
                           └── state (DeviceState tracking)
                                    │
              ┌─────────────────────┼─────────────────────┐
              ▼                     ▼                     ▼
    libstealthtech-core   libstealthtech-wasm   libstealthtech-bridge
       (BLE transport)     (Web Bluetooth)       (Swift/Kotlin FFI)

• libstealthtech-protocol (rust/protocol/) -- WASM-compatible protocol types with zero native dependencies. GATT UUIDs, command encoding/decoding, device state tracking.
• libstealthtech-core (rust/core/) -- BLE transport layer and high-level device API. Depends on protocol crate and btleplug.
• stealthtech (rust/cli/) -- CLI binary with subcommands for end-user control (volume, input, mode) and reverse engineering (stealthtech sniff). Includes a web server with embedded Web Bluetooth UI.
• libstealthtech-wasm (rust/wasm/) -- WebAssembly bindings for the protocol crate, used by the standalone Web Bluetooth interface at stealthtech.app.
• libstealthtech-bridge (rust/bridge/) -- native FFI bindings via uniffi for Swift/Kotlin (future).
• btleplug -- cross-platform BLE library (CoreBluetooth on macOS, bluez on Linux, WinRT on Windows).

BLE Connection State Machine

stateDiagram-v2
    [*] --> Disconnected

    Disconnected --> Connecting : connect()
    Connecting --> Connected : GATT success
    Connecting --> Disconnected : timeout / error

    Connected --> Reconnecting : read/write failure
    Connected --> Disconnected : disconnect()

    Reconnecting --> Connected : reconnect success
    Reconnecting --> Disconnected : max attempts exceeded

States

Transitions

GATT Discovery Flow

sequenceDiagram
    participant App
    participant Scanner
    participant Connection
    participant GATT

    App->>Scanner: scan(duration)
    Scanner-->>App: Vec<DiscoveredDevice>

    App->>Connection: connect(device)
    Connection->>Connection: BLE connect (btleplug)
    Connection-->>App: Ok(Connection)

    App->>GATT: discover_services(connection)
    GATT->>GATT: enumerate services
    GATT->>GATT: enumerate characteristics per service
    GATT->>GATT: read values for each readable characteristic
    GATT-->>App: GattProfile { services, characteristics, values }

Discovery Steps

1. Scan -- Scanner::scan() listens for BLE advertisements matching known StealthTech device names for a configurable duration.
2. Connect -- Connection::connect() establishes a BLE connection to a discovered peripheral and performs initial GATT service discovery.
3. Discover Services -- GATT::discover_services() walks the full GATT attribute table: services, included services, characteristics, and descriptors.
4. Enumerate Characteristics -- For each service, all characteristics are recorded with their UUID, properties (Read/Write/Notify/etc.), and handle.
5. Read Values -- Every characteristic with the Read property is read and its current value is captured as raw bytes.
6. Return Profile -- The complete GattProfile struct is returned, containing all services, characteristics, and their current values.

Protocol Layer -- Characteristic Map

All characteristics have been fully mapped. They share a base UUID encoding "excelpoint.com" in ASCII (65786365-6c70-6f69-6e74-2e636f6d), with the last 2 bytes varying per characteristic. See rust/protocol/src/characteristics.rs.

Services

See protocol-mapping.html for the complete protocol specification and reverse-engineering.html for the RE methodology guide.