react-native-ble-nitro 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zyke (https://zyke.co)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,298 @@
+# react-native-ble-nitro
+
+[![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.
+
+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
+- 🎯 **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
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install react-native-nitro-modules react-native-ble-nitro
+```
+
+### Expo Setup
+
+Add the plugin to your `app.json` or `app.config.js`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-ble-nitro",
+        {
+          "isBackgroundEnabled": true,
+          "modes": ["peripheral", "central"],
+          "bluetoothAlwaysPermission": "Allow $(PRODUCT_NAME) to connect to bluetooth devices"
+        }
+      ]
+    ]
+  }
+}
+```
+
+Then prebuild and run:
+
+```bash
+npx expo prebuild
+npx expo run:android
+# or
+npx expo run:ios
+```
+
+### React Native CLI Setup
+
+For bare React Native projects, the library auto-links. Just run:
+
+```bash
+npx pod-install # iOS only
+```
+
+## 📖 Usage
+
+The API is 100% identical to `react-native-ble-plx`:
+
+```typescript
+import { BleManager, State } from 'react-native-ble-nitro';
+
+const manager = new BleManager();
+
+// Check Bluetooth state
+const state = await manager.state();
+if (state === State.PoweredOn) {
+  console.log('Bluetooth is ready!');
+}
+
+// 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);
+  }
+});
+```
+
+## 🔄 Migration from react-native-ble-plx
+
+**Zero code changes required!** Simply replace the import:
+
+```typescript
+// Before
+import { BleManager, Device, State } from 'react-native-ble-plx';
+
+// After
+import { BleManager, Device, State } from 'react-native-ble-nitro';
+
+// Everything else stays exactly the same!
+```
+
+## 🏗️ Architecture
+
+### Nitro Modules Foundation
+
+Built on [Nitro Modules](https://nitro.margelo.com/) for:
+
+- **Direct JSI Communication**: No React Native bridge overhead
+- **Type-Safe Bindings**: Compile-time type checking across JS/Native boundary  
+- **High Performance**: Near-native performance for all operations
+- **Memory Efficient**: Optimal memory management with smart references
+
+### Platform Implementation
+
+- **iOS**: Native Swift implementation using Core Bluetooth
+- **Android**: Native Kotlin implementation using Android BLE APIs
+- **Shared C++**: Common logic and type definitions
+
+### Compatibility Layer
+
+While maintaining 100% API compatibility, some internal changes were needed for Nitro:
+
+- **Enum Values**: Numeric instead of string (transparent to users)
+- **Service Data**: Structured format internally (automatic conversion)
+- **Type Safety**: Enhanced compile-time checks
+
+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
+
+```typescript
+interface BleNitroPluginProps {
+  isBackgroundEnabled?: boolean;     // Enable background BLE support
+  neverForLocation?: boolean;        // Assert no location derivation [Android 12+]
+  modes?: ('peripheral' | 'central')[]; // iOS background modes
+  bluetoothAlwaysPermission?: string | false; // iOS permission message
+}
+```
+
+### iOS Background Modes
+
+```json
+{
+  "modes": ["peripheral", "central"]
+}
+```
+
+Adds these to `Info.plist`:
+- `bluetooth-peripheral`: Act as BLE peripheral in background
+- `bluetooth-central`: Scan/connect as central in background
+
+### Android Permissions
+
+Automatically adds required permissions:
+
+```xml
+<!-- Basic Bluetooth -->
+<uses-permission android:name="android.permission.BLUETOOTH" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+
+<!-- Location (required for BLE scanning) -->
+<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+
+<!-- Android 12+ -->
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+
+<!-- BLE Hardware Feature -->
+<uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />
+```
+
+## 🔧 Development
+
+### Building the Library
+
+```bash
+# Install dependencies
+npm install
+
+# Generate native Nitro code
+npx nitro-codegen
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+```
+
+### Project Structure
+
+```
+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)
+├── plugin/                # Expo config plugin
+├── ios/                   # iOS native implementation (Swift)
+├── android/               # Android native implementation (Kotlin)
+└── docs/                  # Documentation
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+### Development Setup
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork**: `git clone https://github.com/YOUR_USERNAME/react-native-ble-nitro.git`
+3. **Add upstream remote**: `git remote add upstream https://github.com/zykeco/react-native-ble-nitro.git`
+4. **Install dependencies**: `npm install`
+5. **Generate Nitro code**: `npx nitro-codegen`
+6. **Make your changes** and run tests: `npm test`
+7. **Submit a pull request**
+
+## 📄 License
+
+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
+
+## 📞 Support
+
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/zykeco/react-native-ble-nitro/issues)
+- 💬 **Questions**: [GitHub Discussions](https://github.com/zykeco/react-native-ble-nitro/discussions)
+- 📖 **Documentation**: [API Reference](./docs/api.md)
+
+---
+
+**Made with ❤️ for the React Native community**

package/android/build.gradle

@@ -0,0 +1,55 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+    compileSdkVersion safeExtGet('compileSdkVersion', 34)
+    
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 21)
+        targetSdkVersion safeExtGet('targetSdkVersion', 34)
+        versionCode 1
+        versionName "1.0"
+    }
+    
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+    
+    kotlinOptions {
+        jvmTarget = "1.8"
+    }
+    
+    packagingOptions {
+        pickFirst '**/libc++_shared.so'
+    }
+}
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    implementation 'androidx.core:core-ktx:1.9.0'
+    
+    // React Native
+    implementation 'com.facebook.react:react-native:+'
+    
+    // Nitro Modules
+    implementation 'com.margelo.nitro:nitro-modules:0.26.4'
+    
+    // BLE Dependencies
+    implementation 'no.nordicsemi.android:ble:2.6.1'
+    implementation 'no.nordicsemi.android:ble-ktx:2.6.1'
+    
+    // Coroutines
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="co.zyke.ble">
+
+    <!-- Required for all BLE functionality -->
+    <uses-permission android:name="android.permission.BLUETOOTH" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+    
+    <!-- Required for BLE scanning -->
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    
+    <!-- Android 12+ runtime permissions -->
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    
+    <!-- BLE feature requirement -->
+    <uses-feature
+        android:name="android.hardware.bluetooth_le"
+        android:required="false" />
+
+</manifest>