react-native-ble-nitro 1.0.0-beta.8 → 1.0.0

package/BleNitro.podspec

@@ -0,0 +1,39 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "BleNitro"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
+  s.source       = { :git => "https://github.com/zykeco/react-native-ble-nitro.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/**/*.{swift}",
+    # Autolinking/Registration (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Implementation (C++ objects)
+    "cpp/**/*.{hpp,cpp}",
+  ]
+  
+  # iOS frameworks
+  s.frameworks = "CoreBluetooth"
+  
+  s.user_target_xcconfig = {
+    'OTHER_LDFLAGS' => '-lc++'
+  }
+
+  # Apply Nitro autolinking
+  load 'nitrogen/generated/ios/BleNitro+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Zyke (https://zyke.co)
+Copyright (c) 2025 Zyke (https://zyke.co) presented by Phil Schaffarzyk
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,20 +3,20 @@
 [![npm version](https://badge.fury.io/js/react-native-ble-nitro.svg)](https://badge.fury.io/js/react-native-ble-nitro)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A high-performance React Native BLE library built on [Nitro Modules](https://nitro.margelo.com/) - **drop-in replacement** for `react-native-ble-plx` with significantly better performance and stability.
+A high-performance React Native BLE library built on [Nitro Modules](https://nitro.margelo.com/).
 
 Originally developed for [Zyke Band](https://zykeband.com) - a fitness and health tracker created by a small team.
 
 ## ✨ Features
 
 - 🚀 **High Performance**: Built on Nitro Modules with JSI for zero-overhead native communication
-- 🔄 **100% Compatible**: Drop-in replacement for `react-native-ble-plx@3.5.0`
-- 📱 **Cross-Platform**: iOS and Android support with platform-specific optimizations
+- 📱 **iOS Support**: Complete iOS implementation with Swift and Core Bluetooth
+- 🤖 **Android Support**: Currently in development - iOS fully functional
 - 🎯 **Type-Safe**: Full TypeScript support with comprehensive type definitions
 - 🔧 **Expo Ready**: Built-in Expo config plugin for easy setup
 - 🏗️ **New Architecture**: Full support for React Native's new architecture
 - ⚡ **Zero Bridge**: Direct JSI communication eliminates bridge bottlenecks
-- 🛡️ **Reliable**: Swift/Kotlin native implementations for maximum stability
+- 🛡️ **Reliable**: Swift native implementation for maximum stability
 
 ## 🚀 Quick Start
 
@@ -66,55 +66,286 @@ npx pod-install # iOS only
 
 ## 📖 Usage
 
-The API is 100% identical to `react-native-ble-plx`:
+> **📱 Platform Support**: Currently iOS only. Android implementation is in development.
+
+### Basic Setup
 
 ```typescript
-import { BleManager, State } from 'react-native-ble-nitro';
+import { BleNitro, BLEState, type BLEDevice } from 'react-native-ble-nitro';
 
-const manager = new BleManager();
+// Get the singleton instance
+const ble = BleNitro.instance();
+```
 
-// Check Bluetooth state
-const state = await manager.state();
-if (state === State.PoweredOn) {
-  console.log('Bluetooth is ready!');
-}
+### Complete API Reference
 
-// Scan for devices
-manager.startDeviceScan(null, null, (error, device) => {
-  if (error) {
-    console.error(error);
-    return;
-  }
-  
-  console.log('Found device:', device.name || 'Unknown');
-  
-  if (device.name === 'MyDevice') {
-    manager.stopDeviceScan();
-    
-    // Connect to device
-    device.connect()
-      .then(() => device.discoverAllServicesAndCharacteristics())
-      .then(() => {
-        // Your BLE operations here
-        console.log('Connected and ready!');
-      })
-      .catch(console.error);
+#### 🔌 Bluetooth State Management
+
+```typescript
+// Check if Bluetooth is enabled
+const isEnabled = await ble.isBluetoothEnabled();
+
+// Get current Bluetooth state
+const state = await ble.state();
+// Returns: BLEState.PoweredOn, BLEState.PoweredOff, etc.
+
+// Request to enable Bluetooth (Android only)
+await ble.requestBluetoothEnable();
+
+// Subscribe to state changes
+const subscription = await ble.subscribeToStateChange((state) => {
+  console.log('Bluetooth state changed:', state);
+}, true); // true = emit initial state
+
+// Unsubscribe from state changes
+await subscription.remove();
+
+// Open Bluetooth settings
+await ble.openSettings();
+```
+
+#### 🔍 Device Scanning
+
+```typescript
+// Start scanning for devices
+await ble.startScan({
+  serviceUUIDs: ['180d'], // Optional: filter by service UUIDs
+  rssiThreshold: -80,     // Optional: minimum signal strength
+  allowDuplicates: false  // Optional: allow duplicate discoveries
+}, (device) => {
+  console.log('Found device:', device.name, device.id);
+});
+
+// Stop scanning
+await ble.stopScan();
+
+// Check if currently scanning
+const isScanning = await ble.isScanning();
+
+// Get already connected devices
+const connectedDevices = await ble.getConnectedDevices();
+```
+
+#### 🔗 Device Connection
+
+```typescript
+// Connect to a device with disconnect event handling
+const deviceId = await ble.connect(deviceId, (deviceId, interrupted, error) => {
+  if (interrupted) {
+    console.log('Connection interrupted:', error);
+    // Handle unexpected disconnection (out of range, etc.)
+  } else {
+    console.log('Disconnected intentionally');
+    // Handle normal disconnection
   }
 });
+
+// Connect without disconnect callback
+const deviceId = await ble.connect(deviceId);
+
+// Disconnect from a device
+await ble.disconnect(deviceId);
+
+// Check connection status
+const isConnected = await ble.isConnected(deviceId);
+```
+
+#### 🔧 Service Discovery
+
+```typescript
+// Discover all services for a device
+await ble.discoverServices(deviceId);
+
+// Get discovered services
+const services = await ble.getServices(deviceId);
+// Returns: ['0000180d-0000-1000-8000-00805f9b34fb', '0000180f-0000-1000-8000-00805f9b34fb', ...] 
+// Always returns full 128-bit UUIDs
+
+// Get characteristics for a service
+const characteristics = await ble.getCharacteristics(deviceId, serviceUUID);
+// Returns: ['00002a37-0000-1000-8000-00805f9b34fb', '00002a38-0000-1000-8000-00805f9b34fb', ...] 
+// Always returns full 128-bit UUIDs
+
+// Note: You can use either short or long form UUIDs as input:
+const characteristics1 = await ble.getCharacteristics(deviceId, '180d'); // Short form
+const characteristics2 = await ble.getCharacteristics(deviceId, '0000180d-0000-1000-8000-00805f9b34fb'); // Long form
+// Both work identically - conversion handled automatically
+```
+
+#### 📖 Reading Characteristics
+
+```typescript
+// Read a characteristic value
+const data = await ble.readCharacteristic(deviceId, serviceUUID, characteristicUUID);
+// Returns: number[] - array of bytes
+
+// Example: Reading battery level
+const batteryData = await ble.readCharacteristic(deviceId, '180f', '2a19');
+const batteryLevel = batteryData[0]; // First byte is battery percentage
+console.log('Battery level:', batteryLevel + '%');
+```
+
+#### ✍️ Writing Characteristics
+
+```typescript
+// Write to a characteristic with response
+await ble.writeCharacteristic(
+  deviceId, 
+  serviceUUID, 
+  characteristicUUID, 
+  [0x01, 0x02, 0x03], // Data as byte array
+  true // withResponse = true (default)
+);
+
+// Write without response (faster, no confirmation)
+await ble.writeCharacteristic(
+  deviceId, 
+  serviceUUID, 
+  characteristicUUID, 
+  [0x01, 0x02, 0x03],
+  false // withResponse = false
+);
+```
+
+#### 📡 Characteristic Notifications
+
+```typescript
+// Subscribe to characteristic notifications
+const subscription = await ble.subscribeToCharacteristic(
+  deviceId,
+  serviceUUID,
+  characteristicUUID,
+  (characteristicId, data) => {
+    console.log('Received notification:', data);
+    // Handle incoming data
+  }
+);
+
+// Unsubscribe from notifications
+await subscription.remove();
+
+// Or unsubscribe directly
+await ble.unsubscribeFromCharacteristic(deviceId, serviceUUID, characteristicUUID);
+```
+
+### Real-World Examples
+
+#### Heart Rate Monitor
+
+```typescript
+const HEART_RATE_SERVICE = '180d';
+const HEART_RATE_MEASUREMENT = '2a37';
+
+// Connect and subscribe to heart rate
+const deviceId = await ble.connect(heartRateDeviceId);
+await ble.discoverServices(deviceId);
+
+const subscription = await ble.subscribeToCharacteristic(
+  deviceId,
+  HEART_RATE_SERVICE,
+  HEART_RATE_MEASUREMENT,
+  (_, data) => {
+    const heartRate = data[1]; // Second byte contains BPM
+    console.log('Heart rate:', heartRate, 'BPM');
+  }
+);
+```
+
+#### Battery Level Reading
+
+```typescript
+const BATTERY_SERVICE = '180f';
+const BATTERY_LEVEL_CHARACTERISTIC = '2a19';
+
+const batteryData = await ble.readCharacteristic(
+  deviceId,
+  BATTERY_SERVICE,
+  BATTERY_LEVEL_CHARACTERISTIC
+);
+const batteryPercentage = batteryData[0];
+console.log('Battery:', batteryPercentage + '%');
+```
+
+#### Custom Device Control
+
+```typescript
+const CUSTOM_SERVICE = 'your-custom-service-uuid';
+const COMMAND_CHARACTERISTIC = 'your-command-characteristic-uuid';
+
+// Send a custom command
+const enableLedCommand = [0x01, 0x1f, 0x01]; // Your protocol
+await ble.writeCharacteristic(
+  deviceId,
+  CUSTOM_SERVICE,
+  COMMAND_CHARACTERISTIC,
+  enableLedCommand
+);
 ```
 
-## 🔄 Migration from react-native-ble-plx
+### UUID Handling
+
+**🔧 Automatic UUID Conversion**
 
-**Zero code changes required!** Simply replace the import:
+This library automatically handles UUID conversion between 16-bit, 32-bit, and 128-bit formats:
 
 ```typescript
-// Before
-import { BleManager, Device, State } from 'react-native-ble-plx';
+// All input methods accept both short and long form UUIDs:
+await ble.readCharacteristic(deviceId, '180d', '2a19');           // Short form ✅
+await ble.readCharacteristic(deviceId, '0000180d-0000-1000-8000-00805f9b34fb', '00002a19-0000-1000-8000-00805f9b34fb'); // Long form ✅
 
-// After
-import { BleManager, Device, State } from 'react-native-ble-nitro';
+// All output methods return full 128-bit UUIDs:
+const services = await ble.getServices(deviceId);
+// Always returns: ['0000180d-0000-1000-8000-00805f9b34fb', ...] 
+
+// Conversion happens automatically on the native side for maximum performance
+```
+
+### Utility Functions
+
+```typescript
+// Manually normalize UUIDs to full 128-bit format (rarely needed)
+const fullUUID = BleNitro.normalizeGattUUID('180d');
+// Returns: '0000180d-0000-1000-8000-00805f9b34fb'
 
-// Everything else stays exactly the same!
+// Normalize multiple UUIDs
+const fullUUIDs = BleNitro.normalizeGattUUIDs(['180d', '180f']);
+// Returns: ['0000180d-0000-1000-8000-00805f9b34fb', '0000180f-0000-1000-8000-00805f9b34fb']
+```
+
+### TypeScript Types
+
+```typescript
+interface BLEDevice {
+  id: string;
+  name: string;
+  rssi: number;
+  manufacturerData: ManufacturerData;
+  serviceUUIDs: string[];
+  isConnectable: boolean;
+}
+
+interface ScanFilter {
+  serviceUUIDs?: string[];
+  rssiThreshold?: number;
+  allowDuplicates?: boolean;
+}
+
+interface Subscription {
+  remove: () => Promise<void>;
+}
+
+enum BLEState {
+  Unknown = 'Unknown',
+  Resetting = 'Resetting', 
+  Unsupported = 'Unsupported',
+  Unauthorized = 'Unauthorized',
+  PoweredOff = 'PoweredOff',
+  PoweredOn = 'PoweredOn'
+}
+
+// Callback types
+type DisconnectEventCallback = (deviceId: string, interrupted: boolean, error: string) => void;
+type CharacteristicUpdateCallback = (characteristicId: string, data: number[]) => void;
 ```
 
 ## 🏗️ Architecture
@@ -130,9 +361,9 @@ Built on [Nitro Modules](https://nitro.margelo.com/) for:
 
 ### Platform Implementation
 
-- **iOS**: Native Swift implementation using Core Bluetooth
-- **Android**: Native Kotlin implementation using Android BLE APIs
-- **Shared C++**: Common logic and type definitions
+- **iOS**: ✅ Complete Swift implementation using Core Bluetooth
+- **Android**: 🚧 Kotlin implementation in development using Android BLE APIs  
+- **Shared C++**: Common logic and type definitions via Nitro Modules
 
 ### Compatibility Layer
 
@@ -144,29 +375,6 @@ While maintaining 100% API compatibility, some internal changes were needed for
 
 See [API_DIFFERENCES.md](./API_DIFFERENCES.md) for technical details.
 
-## 📋 API Reference
-
-The API is identical to `react-native-ble-plx`. Key classes and methods:
-
-### BleManager
-
-- `new BleManager(options?)`: Create manager instance
-- `state()`: Get current Bluetooth state
-- `startDeviceScan()`: Start scanning for devices
-- `connectToDevice()`: Connect to a BLE device
-- `readCharacteristicForDevice()`: Read characteristic value
-- `writeCharacteristicWithResponseForDevice()`: Write with response
-- `monitorCharacteristicForDevice()`: Monitor value changes
-
-### Device
-
-- `connect()`: Connect to this device
-- `discoverAllServicesAndCharacteristics()`: Discover GATT structure
-- `readCharacteristicForService()`: Read characteristic
-- `monitorCharacteristicForService()`: Monitor characteristic
-
-For complete API documentation, see the [react-native-ble-plx docs](https://github.com/dotintent/react-native-ble-plx) - everything applies to this library too!
-
 ## ⚙️ Configuration
 
 ### Expo Plugin Options
@@ -241,7 +449,6 @@ npm run lint
 react-native-ble-nitro/
 ├── src/
 │   ├── specs/              # Nitro module TypeScript specs
-│   ├── compatibility/      # react-native-ble-plx compatibility layer
 │   ├── utils/             # Utility functions (UUID, Base64)
 │   └── errors/            # BLE error handling
 ├── nitrogen/generated/     # Generated native code (Nitro)
@@ -269,20 +476,9 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu
 
 MIT License - see [LICENSE](./LICENSE) file.
 
-## Comparison with react-native-ble-plx
-
-| Feature | react-native-ble-plx | react-native-ble-nitro |
-|---------|---------------------|------------------------|
-| **Performance** | React Native Bridge | Direct JSI ⚡ |
-| **Type Safety** | TypeScript definitions | Compile-time validation ✅ |
-| **Memory Usage** | Higher overhead | Optimized 🎯 |
-| **New Architecture** | Limited support | Full support ✅ |
-| **API Compatibility** | Original | 100% Compatible ✅ |
-
 ## 🙏 Acknowledgments
 
 - [Zyke Band](https://zykeband.com) - The fitness tracker project that inspired this library
-- [react-native-ble-plx](https://github.com/dotintent/react-native-ble-plx) - Original library and API design
 - [Marc Rousavy](https://github.com/mrousavy) - Creator of Nitro Modules and CEO of Margelo
 - [Nitro Modules](https://nitro.margelo.com/) - High-performance native module framework
 - [Margelo](https://margelo.com/) - Nitro Modules creators