Skip to content

ReactNative.mdx

Latest commit

 

History

History
289 lines (237 loc) · 7.62 KB

ReactNative.mdx

File metadata and controls

289 lines (237 loc) · 7.62 KB
Raw
title React Native SDK
icon react
description Cross-platform mobile SDK for connecting to Omi devices via Bluetooth Low Energy

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.

iOS and Android support Bluetooth Low Energy 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`: 
```xml
<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>
```
Add to your `AndroidManifest.xml`: 
```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" />
```

Development Setup

```bash git clone https://github.com/BasedHardware/omi.git cd sdks/react-native npm install ``` ```bash cd example npm install ``` ```bash cd ios pod install ``` 
<Note>
This step is crucial. Without it, the app will fail to build with native module errors.
</Note>
```bash cd example/ios open OmiSDKExample.xcworkspace ``` 
    <Warning>
    Open the `.xcworkspace` file, NOT the `.xcodeproj` file.
    </Warning>

    Select your target device and build. Bluetooth doesn't work in simulators - use a physical device.
  </Tab>
  <Tab title="Android">
    ```bash
    cd example
    npm run android
    ```

    Make sure USB debugging is enabled on your connected Android device.
  </Tab>
</Tabs>

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

Method Description Returns
scanForDevices(onDeviceFound, timeoutMs) Scan for nearby Omi devices Function to stop scanning
connect(deviceId, onConnectionStateChanged) Connect to an Omi device Promise<boolean>
disconnect() Disconnect from current device Promise<void>
isConnected() Check connection status boolean
getAudioCodec() Get device audio codec Promise<BleAudioCodec>
startAudioBytesListener(callback) Start receiving audio bytes Promise<Subscription>
stopAudioBytesListener(subscription) Stop receiving audio bytes Promise<void>
getBatteryLevel() Get battery percentage Promise<number>

Types

```typescript interface OmiDevice { id: string; name: string; rssi: number; } ``` ```typescript enum DeviceConnectionState { CONNECTED = 'connected', DISCONNECTED = 'disconnected' } ``` ```typescript enum BleAudioCodec { PCM16 = 'pcm16', PCM8 = 'pcm8', OPUS = 'opus', UNKNOWN = 'unknown' } ```

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

Related

Compare all available SDKs View source code and contribute