react-native-sdk-ble

A comprehensive React Native library for Bluetooth Low Energy (BLE) communication, supporting both iOS and Android platforms. This library provides a clean, promise-based API for scanning, connecting, and interacting with BLE devices.

Features

• 🔍 Device Scanning: Scan for nearby BLE devices with filtering options
• 🔗 Connection Management: Connect to multiple devices simultaneously
• 🛠️ Service Discovery: Discover services and characteristics
• 📖 Read/Write Operations: Read from and write to characteristics
• 🔔 Notifications: Enable/disable characteristic notifications
• 📱 Cross Platform: Works on both iOS and Android
• 🔐 Permission Handling: Automatic permission management
• 📝 TypeScript Support: Full TypeScript definitions included
• 🎯 Event-Driven: React to BLE events with a clean event system

Installation

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

iOS Setup

Add the following to your ios/YourApp/Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to communicate with BLE devices</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to communicate with BLE devices</string>

Android Setup

The library automatically includes the required permissions in its manifest. For Android 6+ and 12+, runtime permissions will be handled automatically.

Required permissions (automatically included):

• BLUETOOTH
• BLUETOOTH_ADMIN
• ACCESS_FINE_LOCATION (Android 6-11)
• BLUETOOTH_SCAN (Android 12+)
• BLUETOOTH_CONNECT (Android 12+)

Quick Start

import bleManager from 'react-native-sdk-ble-v2';

// Request permissions (Android)
await bleManager.requestPermissions();

// Start scanning for devices
await bleManager.startScan({
  timeout: 10000, // Stop after 10 seconds
  allowDuplicates: false,
});

// Listen for discovered devices
bleManager.on('scanResult', ({ device }) => {
  console.log('Found device:', device.name, device.id);
});

// Connect to a device
await bleManager.connect(deviceId);

// Discover services
const services = await bleManager.discoverServices(deviceId);

// Read a characteristic
const value = await bleManager.readCharacteristic(
  deviceId,
  serviceUuid,
  characteristicUuid
);

// Write to a characteristic
await bleManager.writeCharacteristic(
  deviceId,
  serviceUuid, 
  characteristicUuid,
  'Hello BLE!'
);

// Enable notifications
await bleManager.setNotify(deviceId, serviceUuid, characteristicUuid, true);

// Listen for notifications
bleManager.on('characteristicChanged', ({ deviceId, value }) => {
  // console.log('Notification from', deviceId, ':', value);
});

API Reference

Scanning

startScan(options?: BleScanOptions): Promise<void>

Start scanning for BLE devices.

interface BleScanOptions {
  serviceUUIDs?: string[];        // Filter by service UUIDs
  allowDuplicates?: boolean;      // Allow duplicate discoveries
  scanMode?: 'lowPower' | 'balanced' | 'lowLatency'; // Android scan mode
  timeout?: number;               // Auto-stop after timeout (ms)
}

await bleManager.startScan({
  serviceUUIDs: ['180D'], // Heart Rate Service
  timeout: 10000,
  scanMode: 'balanced'
});

stopScan(): Promise<void>

Stop scanning for devices.

await bleManager.stopScan();

Connection Management

connect(deviceId: string): Promise<void>

Connect to a BLE device.

await bleManager.connect('AA:BB:CC:DD:EE:FF');

disconnect(deviceId: string): Promise<void>

Disconnect from a device.

await bleManager.disconnect(deviceId);

isConnected(deviceId: string): Promise<boolean>

Check if a device is connected.

const connected = await bleManager.isConnected(deviceId);

getConnectedDevices(): Promise<BleDevice[]>

Get all currently connected devices.

const devices = await bleManager.getConnectedDevices();

Service Discovery

discoverServices(deviceId: string): Promise<BleService[]>

Discover services and characteristics for a connected device.

const services = await bleManager.discoverServices(deviceId);
services.forEach(service => {
  console.log('Service:', service.uuid);
  service.characteristics.forEach(char => {
    console.log('  Characteristic:', char.uuid, char.properties);
  });
});

Characteristic Operations

readCharacteristic(deviceId: string, serviceUuid: string, characteristicUuid: string): Promise<string>

Read data from a characteristic. Returns hex string.

const data = await bleManager.readCharacteristic(
  deviceId,
  '180D', // Heart Rate Service  
  '2A37'  // Heart Rate Measurement
);
console.log('Heart rate data:', data);

writeCharacteristic(deviceId: string, serviceUuid: string, characteristicUuid: string, data: string, options?: BleWriteOptions): Promise<void>

Write data to a characteristic.

interface BleWriteOptions {
  withResponse?: boolean; // Default: true
}

// Write UTF-8 string
await bleManager.writeCharacteristic(
  deviceId, 
  serviceUuid, 
  characteristicUuid, 
  'Hello BLE!'
);

// Write hex data
await bleManager.writeCharacteristic(
  deviceId,
  serviceUuid, 
  characteristicUuid,
  '0x48656C6C6F', // "Hello" in hex
  { withResponse: false }
);

setNotify(deviceId: string, serviceUuid: string, characteristicUuid: string, enable: boolean): Promise<void>

Enable or disable notifications for a characteristic.

// Enable notifications
await bleManager.setNotify(deviceId, serviceUuid, characteristicUuid, true);

// Disable notifications  
await bleManager.setNotify(deviceId, serviceUuid, characteristicUuid, false);

State & Permissions

requestPermissions(): Promise<boolean>

Request necessary BLE permissions (Android).

const granted = await bleManager.requestPermissions();
if (!granted) {
  console.log('BLE permissions not granted');
}

isBluetoothEnabled(): Promise<boolean>

Check if Bluetooth is enabled.

const enabled = await bleManager.isBluetoothEnabled();

enableBluetooth(): Promise<void>

Request to enable Bluetooth (shows system dialog).

await bleManager.enableBluetooth();

Events

The library uses an event-driven architecture. Listen for events using the on() method:

Event Types

type BleEvent = 
  | 'scanResult'
  | 'connected' 
  | 'disconnected'
  | 'servicesDiscovered'
  | 'characteristicChanged'
  | 'error'
  | 'bluetoothStateChanged';

Event Listeners

on<T extends BleEvent>(event: T, listener: (data: BleEventData[T]) => void): void

Add an event listener.

off<T extends BleEvent>(event: T, listener?: (data: BleEventData[T]) => void): void

Remove an event listener.

removeAllListeners(): void

Remove all event listeners.

Event Examples

// Device discovered during scan
bleManager.on('scanResult', ({ device }) => {
  console.log(`Found: ${device.name} (${device.id})`);
  console.log(`RSSI: ${device.rssi}`);
  console.log(`Services: ${device.serviceUUIDs}`);
});

// Device connected
bleManager.on('connected', ({ deviceId }) => {
  console.log(`Connected to ${deviceId}`);
});

// Device disconnected
bleManager.on('disconnected', ({ deviceId, reason }) => {
  console.log(`Disconnected from ${deviceId}: ${reason}`);
});

// Services discovered
bleManager.on('servicesDiscovered', ({ deviceId, services }) => {
  console.log(`Found ${services.length} services for ${deviceId}`);
});

// Characteristic notification/indication
bleManager.on('characteristicChanged', ({ deviceId, serviceUuid, characteristicUuid, value }) => {
  console.log(`Notification: ${characteristicUuid} = ${value}`);
});

// Error occurred
bleManager.on('error', ({ code, message, deviceId }) => {
  console.error(`BLE Error ${code}: ${message}`, deviceId);
});

// Bluetooth state changed  
bleManager.on('bluetoothStateChanged', ({ state }) => {
  console.log(`Bluetooth state: ${state}`);
});

Data Types

interface BleDevice {
  id: string;                    // Device MAC address or UUID
  name?: string;                 // Device name
  rssi?: number;                 // Signal strength
  manufacturerData?: string;     // Manufacturer data (hex)
  serviceUUIDs?: string[];       // Advertised services
}

interface BleService {
  uuid: string;                  // Service UUID
  characteristics: BleCharacteristic[];
}

interface BleCharacteristic {
  uuid: string;                  // Characteristic UUID
  properties: string[];          // ['read', 'write', 'notify', 'indicate']
  descriptors?: BleDescriptor[];
}

Error Handling

All methods return promises that may reject with errors. Common error codes:

• BLUETOOTH_NOT_ENABLED - Bluetooth is turned off
• PERMISSIONS_NOT_GRANTED - Required permissions missing
• DEVICE_NOT_FOUND - Device not discovered or invalid ID
• DEVICE_NOT_CONNECTED - Operation requires connection
• SERVICE_NOT_FOUND - Service UUID not found on device
• CHARACTERISTIC_NOT_FOUND - Characteristic UUID not found
• OPERATION_FAILED - Generic operation failure

try {
  await bleManager.connect(deviceId);
} catch (error) {
  if (error.message.includes('DEVICE_NOT_FOUND')) {
    console.log('Device not in range or invalid ID');
  }
}

Example App

See the example directory for a complete demo app showing:

• Device scanning with real-time results
• Multi-device connection management
• Service and characteristic exploration
• Read/write operations with hex and text data
• Notification handling
• Error handling and logging
• Permission management

To run the example:

cd example
npm install

# iOS
npm run ios

# Android  
npm run android

Testing

Run the test suite:

npm test

The library includes comprehensive unit tests covering:

• All API methods
• Event handling
• Error scenarios
• Mock native module interactions

Platform Differences

iOS

• Uses CoreBluetooth framework
• No runtime permissions required (only Info.plist)
• Cannot programmatically enable Bluetooth
• UUID-based device identification

Android

• Uses BluetoothLE APIs
• Requires runtime permissions (automatically handled)
• Can request Bluetooth enable
• MAC address device identification
• Requires location permissions for scanning (Android 6-11)

Troubleshooting

Android Issues

Location permissions: On Android 6-11, location permissions are required for BLE scanning even if you don't use location features.

Android 12+ permissions: The library automatically handles the new BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions.

Scanning not working: Ensure Bluetooth and location (if required) are enabled.

iOS Issues

Info.plist: Ensure Bluetooth usage descriptions are added to Info.plist.

Background scanning: iOS restricts background BLE operations. The app should be in foreground for reliable operation.

General Issues

Connection failures: Ensure the device is in range and not connected to another app.

Service discovery: Wait for the servicesDiscovered event before accessing characteristics.

Notifications: Not all characteristics support notifications. Check the properties array.

Roadmap

• [ ] Background scanning support
• [ ] Peripheral (advertiser) mode
• [ ] Custom scan filters
• [ ] Connection priority settings
• [ ] MTU size negotiation
• [ ] Descriptor read/write operations

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

MIT

Credits

Made with create-react-native-library