Skip to main content

Overview

A React Native SDK for connecting to and interacting with Omi devices via Bluetooth Low Energy (BLE). Build cross-platform mobile apps for iOS and Android.

Cross-Platform

iOS and Android support

BLE Connection

Bluetooth Low Energy

Real-time Audio

Stream and transcribe

Features

  • Scan for nearby Omi devices
  • Connect to Omi devices
  • Get device audio codec information
  • Stream audio data from the device
  • Monitor battery levels
  • Handle connection state changes
  • Real-time audio transcription using Deepgram

Installation

In Your Project

npm install @omiai/omi-react-native
# or
yarn add @omiai/omi-react-native
This SDK relies on react-native-ble-plx for BLE communication:
npm install react-native-ble-plx
For iOS projects, you must run pod install after installing dependencies:
cd ios && pod install

Platform-Specific Setup

Add to your Info.plist:
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to connect to Omi devices</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to connect to Omi devices</string>

Development Setup

1

Clone and Install

git clone https://github.com/BasedHardware/omi.git
cd sdks/react-native
npm install
2

Set Up Example App

cd example
npm install
3

Install iOS Pods

cd ios
pod install
This step is crucial. Without it, the app will fail to build with native module errors.
4

Run the App

cd example/ios
open OmiSDKExample.xcworkspace
Open the .xcworkspace file, NOT the .xcodeproj file.
Select your target device and build. Bluetooth doesn’t work in simulators - use a physical device.

Quick Start

import { OmiConnection, DeviceConnectionState, BleAudioCodec } from '@omiai/omi-react-native';

// Create an instance of OmiConnection
const omiConnection = new OmiConnection();

// Scan for devices
const stopScan = omiConnection.scanForDevices((device) => {
  console.log('Found device:', device.name, device.id);
}, 10000); // Scan for 10 seconds

// Connect to a device
async function connectToDevice(deviceId) {
  const success = await omiConnection.connect(deviceId, (id, state) => {
    console.log(`Device ${id} connection state changed to: ${state}`);
  });

  if (success) {
    console.log('Connected successfully!');

    // Get the audio codec
    const codec = await omiConnection.getAudioCodec();
    console.log('Device audio codec:', codec);

    // Start listening for audio data
    const subscription = await omiConnection.startAudioBytesListener((bytes) => {
      console.log('Received audio bytes:', bytes.length);
    });

    // Get battery level
    const batteryLevel = await omiConnection.getBatteryLevel();
    console.log('Battery level:', batteryLevel);

    // Later, stop listening for audio
    await omiConnection.stopAudioBytesListener(subscription);

    // Disconnect when done
    await omiConnection.disconnect();
  }
}

API Reference

OmiConnection Methods

MethodDescriptionReturns
scanForDevices(onDeviceFound, timeoutMs)Scan for nearby Omi devicesFunction to stop scanning
connect(deviceId, onConnectionStateChanged)Connect to an Omi devicePromise<boolean>
disconnect()Disconnect from current devicePromise<void>
isConnected()Check connection statusboolean
getAudioCodec()Get device audio codecPromise<BleAudioCodec>
startAudioBytesListener(callback)Start receiving audio bytesPromise<Subscription>
stopAudioBytesListener(subscription)Stop receiving audio bytesPromise<void>
getBatteryLevel()Get battery percentagePromise<number>

Types

interface OmiDevice {
  id: string;
  name: string;
  rssi: number;
}

Troubleshooting

  • Ensure you’ve run pod install in the ios directory
  • Try cleaning the build folder: Product → Clean Build Folder
  • Make sure you’re opening the .xcworkspace file, not .xcodeproj
  • Ensure Bluetooth is enabled on your device
  • Check that you have the necessary permissions
  • Make sure the Omi device is powered on and in range
  • Bluetooth scanning doesn’t work in iOS simulators - use a physical device
  • Try restarting the Omi device
  • Ensure the device is not connected to another application
  • Check the battery level of the Omi device
  • Verify that the device supports the audio service
  • Check that you’re properly handling the audio bytes in your callback
  • Ensure you have a valid Deepgram API key
  • Check that the audio listener is started before enabling transcription
  • Verify your internet connection is stable
The example app includes padding at the bottom of the ScrollView to ensure input fields remain visible when the keyboard is open.

License

MIT License