react-native-ble-nitro 1.1.0 → 1.3.0

package/README.md

@@ -5,13 +5,13 @@
 
 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.
+Originally developed for [Zyke Band](https://zykeband.com?utm_source=github&utm_medium=readme&utm_campaign=opensource) - a fitness and health tracker created by a small team.
 
 ## ✨ Features
 
 - 🚀 **High Performance**: Built on Nitro Modules with JSI for zero-overhead native communication
 - 📱 **iOS Support**: Complete iOS implementation with Swift and Core Bluetooth
-- 🤖 **Android Support**: Currently in development - iOS fully functional
+- 🤖 **Android Support**: Complete Android implementation with Kotlin and Android BLE APIs
 - 🎯 **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
@@ -66,12 +66,10 @@ npx pod-install # iOS only
 
 ## 📖 Usage
 
-> **📱 Platform Support**: Currently iOS only. Android implementation is in development.
-
 ### Basic Setup
 
 ```typescript
-import { BleNitro, BLEState, type BLEDevice } from 'react-native-ble-nitro';
+import { BleNitro, BLEState, AndroidScanMode, type BLEDevice } from 'react-native-ble-nitro';
 
 // Get the singleton instance
 const ble = BleNitro.instance();
@@ -111,9 +109,13 @@ await ble.openSettings();
 ble.startScan({
   serviceUUIDs: ['180d'], // Optional: filter by service UUIDs
   rssiThreshold: -80,     // Optional: minimum signal strength
-  allowDuplicates: false  // Optional: allow duplicate discoveries
+  allowDuplicates: false, // Optional: allow duplicate discoveries
+  androidScanMode: AndroidScanMode.Balanced // Optional: Android scan mode
 }, (device) => {
-  console.log('Found device:', device.name, device.id);
+  console.log('Discovered device:', device);
+}, (error) => {
+  // only called on Android
+  console.error('Scan error:', error);
 });
 
 // Stop scanning
@@ -148,6 +150,15 @@ await ble.disconnect(deviceId);
 
 // Check connection status
 const isConnected = ble.isConnected(deviceId);
+
+// MTU negotiation (Android only, as iOS manages MTU automatically)
+// iOS returns current MTU size
+const mtu = await ble.requestMTU(deviceId, 256); // Request MTU size
+
+// MTU negotiation (Android only)
+// iOS manages MTU automatically, this method returns current MTU size
+const newMTU = ble.requestMTU(deviceId, 247);
+console.log('MTU set to:', newMTU);
 ```
 
 #### 🔧 Service Discovery
@@ -177,11 +188,12 @@ const characteristics2 = ble.getCharacteristics(deviceId, '0000180d-0000-1000-80
 ```typescript
 // Read a characteristic value
 const data = await ble.readCharacteristic(deviceId, serviceUUID, characteristicUUID);
-// Returns: number[] - array of bytes
+// Returns: ArrayBuffer - binary data
 
 // Example: Reading battery level
 const batteryData = await ble.readCharacteristic(deviceId, '180f', '2a19');
-const batteryLevel = batteryData[0]; // First byte is battery percentage
+const batteryArray = new Uint8Array(batteryData);
+const batteryLevel = batteryArray[0]; // First byte is battery percentage
 console.log('Battery level:', batteryLevel + '%');
 ```
 
@@ -189,11 +201,12 @@ console.log('Battery level:', batteryLevel + '%');
 
 ```typescript
 // Write to a characteristic with response
+const data = new Uint8Array([0x01, 0x02, 0x03]);
 await ble.writeCharacteristic(
   deviceId, 
   serviceUUID, 
   characteristicUUID, 
-  [0x01, 0x02, 0x03], // Data as byte array
+  data.buffer, // Data as ArrayBuffer
   true // withResponse = true (default)
 );
 
@@ -202,7 +215,7 @@ await ble.writeCharacteristic(
   deviceId, 
   serviceUUID, 
   characteristicUUID, 
-  [0x01, 0x02, 0x03],
+  data.buffer,
   false // withResponse = false
 );
 ```
@@ -245,7 +258,8 @@ const subscription = ble.subscribeToCharacteristic(
   HEART_RATE_SERVICE,
   HEART_RATE_MEASUREMENT,
   (_, data) => {
-    const heartRate = data[1]; // Second byte contains BPM
+    const dataArray = new Uint8Array(data);
+    const heartRate = dataArray[1]; // Second byte contains BPM
     console.log('Heart rate:', heartRate, 'BPM');
   }
 );
@@ -265,7 +279,8 @@ const batteryData = await ble.readCharacteristic(
   BATTERY_SERVICE,
   BATTERY_LEVEL_CHARACTERISTIC
 );
-const batteryPercentage = batteryData[0];
+const batteryArray = new Uint8Array(batteryData);
+const batteryPercentage = batteryArray[0];
 console.log('Battery:', batteryPercentage + '%');
 ```
 
@@ -276,12 +291,12 @@ 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
+const enableLedCommand = new Uint8Array([0x01, 0x1f, 0x01]); // Your protocol
 await ble.writeCharacteristic(
   deviceId,
   CUSTOM_SERVICE,
   COMMAND_CHARACTERISTIC,
-  enableLedCommand
+  enableLedCommand.buffer
 );
 ```
 
@@ -331,6 +346,7 @@ interface ScanFilter {
   serviceUUIDs?: string[];
   rssiThreshold?: number;
   allowDuplicates?: boolean;
+  androidScanMode?: AndroidScanMode;
 }
 
 interface Subscription {
@@ -346,9 +362,19 @@ enum BLEState {
   PoweredOn = 'PoweredOn'
 }
 
+enum AndroidScanMode {
+  LowLatency = 'LowLatency',        // Highest power, fastest discovery
+  Balanced = 'Balanced',            // Balanced power/discovery (default)
+  LowPower = 'LowPower',            // Lowest power, slower discovery  
+  Opportunistic = 'Opportunistic',  // Only when other apps are scanning
+}
+
 // Callback types
+type StateChangeCallback = (state: BLEState) => void;
+type ScanEventCallback = (device: BLEDevice) => void;
+type ScanErrorCallback = (error: string) => void; // Android only
 type DisconnectEventCallback = (deviceId: string, interrupted: boolean, error: string) => void;
-type CharacteristicUpdateCallback = (characteristicId: string, data: number[]) => void;
+type CharacteristicUpdateCallback = (characteristicId: string, data: ArrayBuffer) => void;
 ```
 
 ## 🏗️ Architecture
@@ -365,7 +391,7 @@ Built on [Nitro Modules](https://nitro.margelo.com/) for:
 ### Platform Implementation
 
 - **iOS**: ✅ Complete Swift implementation using Core Bluetooth
-- **Android**: 🚧 Kotlin implementation in development using Android BLE APIs  
+- **Android**: ✅ Complete Kotlin implementation using Android BLE APIs  
 - **Shared C++**: Common logic and type definitions via Nitro Modules
 
 ### Compatibility Layer
@@ -388,6 +414,7 @@ interface BleNitroPluginProps {
   neverForLocation?: boolean;        // Assert no location derivation [Android 12+]
   modes?: ('peripheral' | 'central')[]; // iOS background modes
   bluetoothAlwaysPermission?: string | false; // iOS permission message
+  androidAdvertisingEnabled?: boolean; // Android Peripheral mode (advertising)
 }
 ```
 
@@ -405,7 +432,7 @@ Adds these to `Info.plist`:
 
 ### Android Permissions
 
-Automatically adds required permissions:
+Automatically adds required permissions and also handling neverForLocation and advertise mode.
 
 ```xml
 <!-- Basic Bluetooth -->
@@ -413,7 +440,6 @@ Automatically adds required permissions:
 <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+ -->
@@ -425,6 +451,47 @@ Automatically adds required permissions:
 <uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />
 ```
 
+## Android Flow with Permission Handling
+
+```ts
+import { PermissionsAndroid, Platform } from 'react-native';
+
+const requestPermissionsAndroid = async () => {
+  if (Platform.OS !== 'android') {
+    return true
+  }
+  if (Platform.OS === 'android' && PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION) {
+    const apiLevel = parseInt(Platform.Version.toString(), 10);
+    if (apiLevel < 31) {
+      const result = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION);
+      return (
+        result === PermissionsAndroid.RESULTS.GRANTED
+      );
+    }
+    if (PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN && PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT) {
+      const result = await PermissionsAndroid.requestMultiple([
+        PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
+        PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
+        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
+      ])
+
+      return (
+        result['android.permission.BLUETOOTH_CONNECT'] === PermissionsAndroid.RESULTS.GRANTED &&
+        result['android.permission.BLUETOOTH_SCAN'] === PermissionsAndroid.RESULTS.GRANTED &&
+        result['android.permission.ACCESS_FINE_LOCATION'] === PermissionsAndroid.RESULTS.GRANTED
+      )
+    }
+
+    logMessage('Request permissions failed');
+    throw new Error('Request permissions failed');
+  }
+};
+
+const hasPermissions = await requestPermissionsAndroid();
+
+// Then start scanning or other operations
+```
+
 ## 🔧 Development
 
 ### Building the Library
@@ -481,7 +548,7 @@ MIT License - see [LICENSE](./LICENSE) file.
 
 ## 🙏 Acknowledgments
 
-- [Zyke Band](https://zykeband.com) - The fitness tracker project that inspired this library
+- [Zyke Band](https://zykeband.com?utm_source=github&utm_medium=readme&utm_campaign=opensource) - The fitness tracker project that inspired this library
 - [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

package/android/CMakeLists.txt

@@ -0,0 +1,32 @@
+project(BleNitro)
+cmake_minimum_required(VERSION 3.9.0)
+
+set (PACKAGE_NAME BleNitro)
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 20)
+
+# Enable Raw Props parsing in react-native (for Nitro Views)
+add_compile_options(-DRN_SERIALIZABLE_STATE=1)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED
+        src/main/cpp/cpp-adapter.cpp
+)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/BleNitro+autolinking.cmake)
+
+# Set up local includes
+include_directories(
+        "src/main/cpp"
+        "../cpp"
+)
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android                                   # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,140 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.12.1"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/BleNitro+autolinking.gradle'
+apply from: "./fix-prefab.gradle"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["BleNitro_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["BleNitro_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.co.zyke.ble"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+            "META-INF",
+            "META-INF/**",
+            "**/libc++_shared.so",
+            "**/libfbjni.so",
+            "**/libjsi.so",
+            "**/libfolly_json.so",
+            "**/libfolly_runtime.so",
+            "**/libglog.so",
+            "**/libhermes.so",
+            "**/libhermes-executor-debug.so",
+            "**/libhermes_executor.so",
+            "**/libreactnative.so",
+            "**/libreactnativejni.so",
+            "**/libturbomodulejsijni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          // React Codegen files
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+
+dependencies {
+  // For < 0.71, this will be from the local maven repo
+  // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+
+  // Add a dependency on NitroModules
+  implementation project(":react-native-nitro-modules")
+}

package/android/fix-prefab.gradle

@@ -0,0 +1,51 @@
+tasks.configureEach { task ->
+  // Make sure that we generate our prefab publication file only after having built the native library
+  // so that not a header publication file, but a full configuration publication will be generated, which
+  // will include the .so file
+
+  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
+  def matcher = task.name =~ prefabConfigurePattern
+  if (matcher.matches()) {
+    def variantName = matcher[0][1]
+    task.outputs.upToDateWhen { false }
+    task.dependsOn("externalNativeBuild${variantName}")
+  }
+}
+
+afterEvaluate {
+  def abis = reactNativeArchitectures()
+  rootProject.allprojects.each { proj ->
+    if (proj === rootProject) return
+
+    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
+      config.dependencies.any { dep ->
+        dep.group == project.group && dep.name == project.name
+      }
+    }
+    if (!dependsOnThisLib && proj != project) return
+
+    if (!proj.plugins.hasPlugin('com.android.application') && !proj.plugins.hasPlugin('com.android.library')) {
+      return
+    }
+
+    def variants = proj.android.hasProperty('applicationVariants') ? proj.android.applicationVariants : proj.android.libraryVariants
+    // Touch the prefab_config.json files to ensure that in ExternalNativeJsonGenerator.kt we will re-trigger the prefab CLI to
+    // generate a libnameConfig.cmake file that will contain our native library (.so).
+    // See this condition: https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:build-system/gradle-core/src/main/java/com/android/build/gradle/tasks/ExternalNativeJsonGenerator.kt;l=207-219?q=createPrefabBuildSystemGlue
+    variants.all { variant ->
+      def variantName = variant.name
+      abis.each { abi ->
+        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
+        if (!searchDir.exists()) return
+        def matches = []
+        searchDir.eachDir { randomDir ->
+          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
+          if (prefabFile.exists()) matches << prefabFile
+        }
+        matches.each { prefabConfig ->
+          prefabConfig.setLastModified(System.currentTimeMillis())
+        }
+      }
+    }
+  }
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+BleNitro_kotlinVersion=2.1.20
+BleNitro_minSdkVersion=23
+BleNitro_targetSdkVersion=36
+BleNitro_compileSdkVersion=36
+BleNitro_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,6 @@
+#include <jni.h>
+#include "BleNitroOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::co::zyke::ble::initialize(vm);
+}