25 Months of Waiting, 12 Hours of Work: Reverse-Engineering the WIZPR Ring BLE Protocol

Current Situation Analysis

Reverse-engineering undocumented BLE wearables presents significant technical friction. Manufacturers frequently ship hardware with closed GATT profiles, proprietary audio streaming implementations, and zero public documentation. Traditional development approaches fail in this environment because:

• Protocol Opacity: Without published GATT maps, developers must guess service/characteristic UUIDs, leading to prolonged scanner timeouts and connection instability.
• Codec Guesswork: Audio streams often use non-standard sampling rates, frame sizes, or variant implementations of standard codecs. Assuming platform-native decoders or resetting state per packet results in severe static or complete data loss.
• Hardware Constraints: Miniaturized form factors (e.g., titanium finger rings) force engineers to omit standard haptic motors, simplify LED control logic, and rely on continuous BLE notifications rather than session-based handshakes.
• Trial-and-Error Overhead: Manual probing of write-only characteristics without systematic filtering wastes development cycles, especially when hardware features (like independent LED triggers or vibration) simply do not exist.

WOW Moment: Key Findings

Systematic probing and codec hypothesis testing revealed a surprisingly clean ASCII-based command protocol and a continuous IMA ADPCM audio stream. The breakthrough came from maintaining decoder state across notifications and mapping the exact GATT characteristic behavior.

Approach	Decoding Success	Latency (ms)	Audio Quality
Opus	❌ Failed	N/A	Noise
μ-law / A-law	❌ Failed	N/A	Distorted
Raw PCM (8kHz/16kHz)	❌ Failed	N/A	Static
IMA ADPCM (Reset State)	❌ Failed	28	Heavy Static
IMA ADPCM (Continuous State)	✅ Success	28	Clean Speech

Key Technical Findings:

• GATT Structure: Single BLE service with 7 characteristics. Characteristic 00000007 handles ASCII commands/responses. Characteristic 00000001 streams raw audio.
• Audio Pipeline: IMA ADPCM, 16 kHz, mono. Each 224-byte notification contains 448 samples at 4-bit depth, equating to exactly 28 ms of audio per BLE packet.
• Stream Rate: Steady 35.4 packets per second. Decoder state must persist across packets; resetting per notification destroys audio continuity.
• Hardware Limitations: No vibration motor. LED only fires on initial BLE connection (indirect control). Write-only characteristics either accept arbitrary data silently or control undocumented subsystems.

Core Solution

The reverse-engineering workflow was structured into four technical layers: BLE connectivity, protocol mapping, audio reconstruction, and host application architecture.

1. BLE Connection & GATT Mapping

• Used bleak (Python) on macOS to establish persistent BLE connections.
• Filtered scanner by device name WIZPR RING to reduce connection latency.
• Mapped characteristic 00000007 as a plain ASCII command channel. No binary framing, session negotiation, or handshake required.
• Commands: CLICK, MIC_PRE_ON, MIC_ON, MIC_OFF, BATTERY (returns voltage), GET_VERSION (returns firmware string).

2. Audio Codec Identification & Reconstruction

• Captured timestamped packets to JSON for offline analysis.
• Tested multiple decoders: Opus, μ-law, A-law, raw PCM, IMA ADPCM (8kHz/16kHz).
• Identified IMA ADPCM at 16 kHz as the correct codec. Critical implementation detail: decoder state must carry across packets. Resetting state per notification introduces phase discontinuities and static.
• Packet math: 224 bytes × 2 samples/byte = 448 samples. At 16 kHz, 448 samples / 16000 Hz = 0.028 s (28 ms) per notification.

3. Toolchain & Architecture

• PySide6 Guided Capture Tool: Interactive UI for triggering mic states, logging packets, and visualizing stream continuity.
• Standalone Probing Script: CLI interface for writing to unmapped characteristics and observing side effects.
• Ring Daemon: Persistent BLE connection manager that exposes a named pipe for inter-process communication. Handles auto-reconnect, state synchronization, and command routing.
• Swift macOS Menubar App: Native client consuming the reverse-engineered protocol. Implemented a hand-rolled IMA ADPCM decoder because Apple’s AudioToolbox expects 34-byte ADPCM frames, not the ring’s 224-byte continuous stream. Designed audio pipeline spec for low-latency playback and command routing.

Pitfall Guide

1. Per-Packet Decoder State Reset: IMA ADPCM relies on predictive filtering across samples. Resetting the decoder state per BLE notification breaks the prediction chain, producing heavy static. Maintain a single decoder instance across the entire stream.
2. Assuming Binary/Handshake Protocols: The ring communicates via plain ASCII over GATT. Expecting binary delimiters, CRC checks, or session negotiation will lead to unnecessary parsing complexity and connection failures.
3. Relying on Platform-Native Codec Variants: Standard libraries often implement vendor-specific ADPCM variants (e.g., Apple’s 34-byte frame structure). The ring uses continuous 224-byte frames. Hand-rolling or configuring the decoder to match the exact frame layout is mandatory.
4. Ignoring BLE Notification Timing Constraints: Audio streams at 35.4 pps with strict 28 ms windows. Dropping packets, misaligning timestamps, or blocking the BLE event loop will cause audio glitches or stream desynchronization.
5. Overengineering Hardware Control Channels: The ring lacks a vibration motor and only triggers the LED on initial BLE connection. Attempting independent haptic feedback or direct LED writes will fail; hardware capabilities are fixed at the silicon level.
6. Skipping Early BLE Device Filtering: Not filtering scanners by device name or service UUID early leads to connection timeouts, scanner noise, and wasted cycles on unrelated peripherals.
7. Assuming Write-Only Characteristics Are Functional: Four write-only characteristics silently accept arbitrary data with no observable effect. Blindly writing payloads without systematic logging or hardware telemetry will yield false positives.

Deliverables

• BLE Reverse-Engineering Blueprint: Step-by-step workflow for mapping undocumented GATT profiles, including scanner filtering strategies, characteristic probing matrices, and ASCII/binary protocol detection heuristics.
• Protocol Mapping Checklist: Validation matrix for command/response verification, state synchronization, notification rate monitoring, and hardware capability confirmation.
• Audio Decoder Configuration Template: Parameter sheet for IMA ADPCM reconstruction (16 kHz, mono, 224-byte frames, continuous state management) with platform-specific override notes.
• Daemon & Named Pipe Setup Guide: Architecture diagram and configuration examples for persistent BLE connection managers, inter-process command routing, and auto-reconnect logic.