​
Omi SDK for React Native

A React Native SDK for connecting to and interacting with Omi devices via Bluetooth Low Energy (BLE).

​
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

​
Development Setup

​
Prerequisites

  • Node.js and npm installed
  • Xcode (for iOS development)
  • Android Studio (for Android development)
  • CocoaPods (for iOS development)

​
Installation

  1. Clone the repository and navigate to the react-native directory:
git clone https://github.com/BasedHardware/omi.git

cd sdks/react-native
  1. Install dependencies:
npm install
  1. Navigate to the example app directory and install its dependencies:
cd example
npm install
  1. For iOS development, install CocoaPods dependencies:
cd ios
pod install

Note: The pod install step is crucial and must not be skipped for iOS development. Without it, the app will fail to build with native module errors.

​
Running the Example App

​
iOS

  1. Make sure you’ve completed all installation steps above
  2. Open the example app’s workspace in Xcode:
cd example/ios
open OmiSDKExample.xcworkspace  # Do NOT open the .xcodeproj file
  1. Select your target device (Note: Bluetooth functionality is not available in simulators)
  2. Build and run the project

​
Android

  1. Connect your Android device via USB
  2. Enable USB debugging on your device
  3. Run the app:
cd example
npm run android

​
Installation in Your Project

npm install @omiai/omi-react-native
# or
yarn add @omiai/omi-react-native

​
Dependencies

This SDK relies on react-native-ble-plx for BLE communication.

npm install react-native-ble-plx
# or
yarn add react-native-ble-plx

After installing the dependencies, for iOS projects you MUST run:

cd ios
pod install

​
Platform-Specific Setup

For iOS, add the following 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>

For Android, add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<!-- For Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

​
Usage

​
Basic Example

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);
      // Process audio bytes here
    });
    
    // 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

The main class for interacting with Omi devices.

​
Methods

scanForDevices(onDeviceFound, timeoutMs = 10000)

Scans for nearby Omi devices.

  • onDeviceFound: Callback function that receives an OmiDevice object when a device is found
  • timeoutMs: Scan timeout in milliseconds (default: 10000)
  • Returns: A function to stop scanning
connect(deviceId, onConnectionStateChanged)

Connects to an Omi device.

  • deviceId: The ID of the device to connect to
  • onConnectionStateChanged: Optional callback for connection state changes
  • Returns: Promise that resolves to a boolean indicating success
disconnect()

Disconnects from the currently connected device.

  • Returns: Promise that resolves when disconnected
isConnected()

Checks if connected to a device.

  • Returns: Boolean indicating if connected
getAudioCodec()

Gets the audio codec used by the device.

  • Returns: Promise that resolves with the audio codec (BleAudioCodec enum)
startAudioBytesListener(onAudioBytesReceived)

Starts listening for audio bytes from the device.

  • onAudioBytesReceived: Callback function that receives audio bytes as a number array
  • Returns: Promise that resolves with a subscription that can be used to stop listening
stopAudioBytesListener(subscription)

Stops listening for audio bytes.

  • subscription: The subscription returned by startAudioBytesListener
  • Returns: Promise that resolves when stopped
getBatteryLevel()

Gets the current battery level from the device.

  • Returns: Promise that resolves with the battery level percentage (0-100)

​
Types

​
OmiDevice

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

​
DeviceConnectionState

enum DeviceConnectionState {
  CONNECTED = 'connected',
  DISCONNECTED = 'disconnected'
}

​
BleAudioCodec

enum BleAudioCodec {
  PCM16 = 'pcm16',
  PCM8 = 'pcm8',
  OPUS = 'opus',
  UNKNOWN = 'unknown'
}

​
Troubleshooting

​
Common Issues

  1. Build fails with native module errors on iOS

    • Ensure you’ve run pod install in the ios directory
    • Try cleaning the build folder in Xcode (Product → Clean Build Folder)
    • Make sure you’re opening the .xcworkspace file, not the .xcodeproj file

  2. Device not found during scanning

    • 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
    • Note: Bluetooth scanning does not work in iOS simulators, use a physical device

  3. Connection fails

    • Try restarting the Omi device
    • Ensure the device is not connected to another application
    • Check battery level of the Omi device

  4. Audio data not received

    • Verify that the device supports the audio service
    • Check that you’re properly handling the audio bytes in your callback

  5. Transcription not working

    • Ensure you have a valid Deepgram API key
    • Check that the audio listener is started before enabling transcription
    • Verify your internet connection is stable

  6. Keyboard overlaps input fields

    • The example app includes padding at the bottom of the ScrollView to ensure input fields remain visible when the keyboard is open

​
License

MIT