Integrating Third-Party Wearables

​

The Integration Workflow

1. Reverse Engineering: Understanding how the device communicates. This typically means capturing and analyzing its Bluetooth Low Energy (BLE) traffic to decode its protocol for commands and data streaming.
2. Software Integration: Writing code within the Omi mobile app to manage the connection, communication, and data processing for the new device.

​

Prerequisites

• The Hardware: The third-party device you want to integrate.
• An Android Phone: Highly recommended for its superior BLE traffic capturing capabilities.
• Wireshark: The essential tool for analyzing captured network traffic.
• Omi App Codebase: A local development setup of the Omi app.
• Technical Knowledge:
  • Basic understanding of Bluetooth Low Energy (BLE) concepts (Services, Characteristics, UUIDs).
  • Familiarity with Dart/Flutter.
  • (Optional) Python for writing verification scripts.

​

Part 1: Reverse Engineering the Device Protocol

​

Step 1.1: Capture BLE Traffic

​

Using Android (Recommended)

1. Enable Developer Options: Go to Settings > About phone and tap Build number seven times.
2. Enable ADB & Snoop Log: Go to Settings > System > Developer options. Enable USB debugging and Enable Bluetooth HCI snoop log.
3. Restart Bluetooth: Turn Bluetooth off and on again for the change to take effect.
4. Generate Traffic: Use the official vendor app to connect to your device. Perform key operations like starting and stopping a recording, changing settings, etc.

Pro Tip: Record a video of your phone’s screen while you perform actions in the vendor app. This will be invaluable later when you’re in Wireshark, as you can match the timestamps from your video to the packet timestamps to see exactly which action generated which BLE command.

5. Retrieve the Log: After capturing, disable the snoop log.
   • Non-Rooted Devices: Generate a bug report from Developer options. The log file, btsnoop_hci.log, will be in the resulting ZIP archive under FS/data/misc/bluetooth/logs/.
   • Rooted Devices: Pull the file directly using ADB: adb pull /data/misc/bluetooth/logs/btsnoop_hci.log
6. Analyze: Open the btsnoop_hci.log file in Wireshark.

Tip: To find your device’s address and other details, you can run: adb shell dumpsys bluetooth_manager

​

Using iOS

​

Step 1.2: Analyze Traffic in Wireshark

• Filter by Device: Find your device’s address and apply a display filter (e.g., btle.master_bd_addr == your_phone_addr and btle.slave_bd_addr == your_device_addr) to isolate its traffic.
• Look for Patterns: If the device streams audio, you should see a large number of packets of a similar size being sent rapidly from the device to the phone.
• Inspect Packet Details: Click on a packet to see its details. Look for the GATT Service UUID, Characteristic UUID, and the raw data payload (Opcode: ATT_HANDLE_VALUE_NTF).

​

Key Information to Find

Your goal is to create a “map” of the device’s BLE services. You are looking for:

• Service UUIDs: The high-level containers for functionality (e.g., “Audio Service”, “Device Information Service”).
• Characteristic UUIDs: The specific endpoints for data (e.g., “Audio Stream Data”, “Battery Level”, “Button Press”).
• Data Format: The encoding of the data payload (e.g., Opus, PCM, simple byte commands).

​

Step 1.3: Decode the Data Payload

​

Example: Identifying Opus Frames

​

Step 1.4: Verify Your Findings

​

Part 2: Integrating with the Omi App

​

Understanding Omi’s Device Architecture

• DeviceConnection: An abstract class in .../device_connection.dart that defines the standard interface for all devices (e.g., connect(), getAudioCodec(), retrieveBatteryLevel()). Your new class will extend this.
• DeviceTransport: A low-level communication handler. For BLE devices, you’ll use BleTransport (.../transports/ble_transport.dart), which handles the raw reading and writing to characteristics. You typically don’t need to modify this.
• DeviceConnectionFactory: A class in .../device_connection.dart that constructs the correct DeviceConnection object based on the DeviceType. You will register your new device here.

​

Step 2.1: Add a New DeviceType

// app/lib/backend/schema/bt_device/bt_device.dart
enum DeviceType {
  omi,
  openglass,
  frame,
  appleWatch,
  xor,
  xyz, // Add your new device type here
}

​

Step 2.2: Create Your Device Connection Class

// app/lib/services/devices/xyz_connection.dart
import 'dart:async';
import 'package:omi/backend/schema/bt_device/bt_device.dart';
import 'package:omi/services/devices/device_connection.dart';
import 'package:omi/services/devices/models.dart';

// Define your device's specific UUIDs here
const String xyzAudioServiceUuid = '0000...';
const String xyzAudioStreamUuid = '0000...';
const String xyzButtonUuid = '0000...';

class XyzConnection extends DeviceConnection {
  XyzConnection(super.device, super.transport);

  @override
  Future<BleAudioCodec> performGetAudioCodec() async {
    // Return the audio codec your device uses.
    // If it's fixed, just return it. If you need to read it from a
    // characteristic, do that here using `transport.readCharacteristic(...)`.
    return BleAudioCodec.opus;
  }

  @override
  Future<StreamSubscription?> performGetBleAudioBytesListener({
    required void Function(List<int> p1) onAudioBytesReceived,
  }) async {
    // Subscribe to your device's audio characteristic and forward the data.
    final stream = transport.getCharacteristicStream(xyzAudioServiceUuid, xyzAudioStreamUuid);
    return stream.listen(onAudioBytesReceived);
  }

  @override
  Future<int> performRetrieveBatteryLevel() async {
    // Implement battery level reading. Most devices use the standard BLE
    // Battery Service, so you can often call the superclass method.
    return super.performRetrieveBatteryLevel();
  }

  // --- Optional Features ---

  @override
  Future<StreamSubscription?> performGetBleButtonListener({
    required void Function(List<int> p1) onButtonReceived,
  }) async {
    // If your device has a button, subscribe to its characteristic here.
    throw UnimplementedError();
  }

  @override
  Future<List<int>> performGetButtonState() async {
    // If your device has a button, implement its state retrieval here.
    throw UnimplementedError();
  }

  // If a feature is not supported, you can simply throw an UnimplementedError
  // or return a default value.
}

​

Step 2.3: Implement the Core perform... Methods

​

Step 2.4: Register Your Device in the Factory

// app/lib/services/devices/device_connection.dart
class DeviceConnectionFactory {
  static DeviceConnection? create(BtDevice device) {
    // ... existing code ...

    switch (device.type) {
      // ... other cases
      case DeviceType.appleWatch:
        return AppleWatchDeviceConnection(device, transport);
      
      // Add your new case
      case DeviceType.xyz:
        return XyzConnection(device, transport);
    }
  }
}

​

Part 3: Testing and Contribution

​

Testing Your Integration

• Can you successfully discover and connect to the device?
• Does live transcription work as expected?
• Is the battery level displayed correctly?
• Is the connection stable? Does it handle reconnection gracefully?

​

Troubleshooting Common Issues

• Connection Fails: Double-check your Service and Characteristic UUIDs. Ensure the device is not connected to its official app or another phone.
• Audio is Garbled: Your BleAudioCodec in performGetAudioCodec is likely incorrect. Verify the codec and its parameters (sample rate, bit depth).
• No Data Received: Confirm you are subscribing to the correct characteristic for notifications. Check in Wireshark if the device is actually sending data after you connect.

​

Contributing Your Work

1. Check our Contribution Guide.
2. Open a Pull Request on the Omi GitHub repository.
3. Join our Discord to discuss your integration with the team and community.