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

package/plugin/build/index.d.ts

@@ -0,0 +1,28 @@
+import { ConfigPlugin } from 'expo/config-plugins';
+import withBleNitro, { withBleNitroAndroid, withBleNitroIOS, type BleNitroPluginProps } from './withBleNitro';
+/**
+ * Expo Config Plugin for react-native-ble-nitro
+ *
+ * Configures iOS and Android permissions and settings for BLE operations
+ *
+ * @example
+ * ```json
+ * {
+ *   "expo": {
+ *     "plugins": [
+ *       [
+ *         "react-native-ble-nitro",
+ *         {
+ *           "isBackgroundEnabled": true,
+ *           "modes": ["peripheral", "central"],
+ *           "bluetoothAlwaysPermission": "Allow $(PRODUCT_NAME) to connect to bluetooth devices"
+ *         }
+ *       ]
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+declare const plugin: ConfigPlugin<BleNitroPluginProps | void>;
+export default plugin;
+export { withBleNitro, withBleNitroAndroid, withBleNitroIOS, type BleNitroPluginProps };

package/plugin/build/index.js

@@ -0,0 +1,29 @@
+import withBleNitro, { withBleNitroAndroid, withBleNitroIOS } from './withBleNitro';
+/**
+ * Expo Config Plugin for react-native-ble-nitro
+ *
+ * Configures iOS and Android permissions and settings for BLE operations
+ *
+ * @example
+ * ```json
+ * {
+ *   "expo": {
+ *     "plugins": [
+ *       [
+ *         "react-native-ble-nitro",
+ *         {
+ *           "isBackgroundEnabled": true,
+ *           "modes": ["peripheral", "central"],
+ *           "bluetoothAlwaysPermission": "Allow $(PRODUCT_NAME) to connect to bluetooth devices"
+ *         }
+ *       ]
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+const plugin = (config, props) => {
+    return withBleNitro(config, props || {});
+};
+export default plugin;
+export { withBleNitro, withBleNitroAndroid, withBleNitroIOS };

package/plugin/build/withBleNitro.d.ts

@@ -0,0 +1,31 @@
+import { ConfigPlugin } from 'expo/config-plugins';
+export interface BleNitroPluginProps {
+    /**
+     * Enable background BLE support on Android.
+     * Adds required permissions and features to AndroidManifest.xml
+     * @default false
+     */
+    isBackgroundEnabled?: boolean;
+    /**
+     * Set to true only if you can strongly assert that your app never derives
+     * physical location from Bluetooth scan results. The location permission
+     * will still be required on older Android devices.
+     * @default false
+     * @warning This parameter is experimental and BLE might not work. Test before releasing.
+     */
+    neverForLocation?: boolean;
+    /**
+     * iOS background modes for BLE operations
+     * @default undefined
+     */
+    modes?: ('peripheral' | 'central')[];
+    /**
+     * iOS Bluetooth permission message. Set to false to skip adding the permission.
+     * @default "Allow $(PRODUCT_NAME) to connect to bluetooth devices"
+     */
+    bluetoothAlwaysPermission?: string | false;
+}
+export declare const withBleNitroAndroid: ConfigPlugin<BleNitroPluginProps>;
+export declare const withBleNitroIOS: ConfigPlugin<BleNitroPluginProps>;
+declare const withBleNitro: ConfigPlugin<BleNitroPluginProps>;
+export default withBleNitro;

package/plugin/build/withBleNitro.js

@@ -0,0 +1,87 @@
+import { AndroidConfig, WarningAggregator, withAndroidManifest, withInfoPlist, } from 'expo/config-plugins';
+const BLUETOOTH_PERMISSIONS = [
+    'android.permission.BLUETOOTH',
+    'android.permission.BLUETOOTH_ADMIN',
+    'android.permission.ACCESS_COARSE_LOCATION',
+    'android.permission.ACCESS_FINE_LOCATION',
+];
+const BLUETOOTH_PERMISSIONS_API_31 = [
+    'android.permission.BLUETOOTH_SCAN',
+    'android.permission.BLUETOOTH_ADVERTISE',
+    'android.permission.BLUETOOTH_CONNECT',
+];
+export const withBleNitroAndroid = (config, props = {}) => {
+    const { isBackgroundEnabled = false, neverForLocation = false } = props;
+    return withAndroidManifest(config, (config) => {
+        const androidManifest = config.modResults;
+        // Add required permissions
+        AndroidConfig.Permissions.ensurePermissions(config.modResults, [
+            ...BLUETOOTH_PERMISSIONS,
+            ...BLUETOOTH_PERMISSIONS_API_31,
+        ]);
+        // Add uses-feature for BLE
+        if (!androidManifest.manifest['uses-feature']) {
+            androidManifest.manifest['uses-feature'] = [];
+        }
+        const usesFeatures = androidManifest.manifest['uses-feature'];
+        // Add BLE feature requirement
+        const bleFeature = {
+            $: {
+                'android:name': 'android.hardware.bluetooth_le',
+                'android:required': (isBackgroundEnabled ? 'true' : 'false'),
+            },
+        };
+        if (!usesFeatures.find((f) => f.$?.['android:name'] === 'android.hardware.bluetooth_le')) {
+            usesFeatures.push(bleFeature);
+        }
+        // Handle location permission settings for Android 12+
+        if (neverForLocation) {
+            // Add neverForLocation attribute to location permissions for Android 12+
+            const permissions = androidManifest.manifest['uses-permission'] || [];
+            permissions.forEach((permission) => {
+                if (permission.$?.['android:name'] === 'android.permission.ACCESS_FINE_LOCATION' ||
+                    permission.$?.['android:name'] === 'android.permission.ACCESS_COARSE_LOCATION') {
+                    permission.$['android:usesPermissionFlags'] = 'neverForLocation';
+                }
+            });
+        }
+        return config;
+    });
+};
+export const withBleNitroIOS = (config, props = {}) => {
+    const { modes, bluetoothAlwaysPermission = 'Allow $(PRODUCT_NAME) to connect to bluetooth devices' } = props;
+    return withInfoPlist(config, (config) => {
+        // Add NSBluetoothAlwaysUsageDescription
+        if (bluetoothAlwaysPermission !== false) {
+            config.modResults.NSBluetoothAlwaysUsageDescription = bluetoothAlwaysPermission;
+        }
+        // Add background modes if specified
+        if (modes && modes.length > 0) {
+            const backgroundModes = modes.map(mode => `bluetooth-${mode}`);
+            if (!config.modResults.UIBackgroundModes) {
+                config.modResults.UIBackgroundModes = [];
+            }
+            backgroundModes.forEach(mode => {
+                if (!config.modResults.UIBackgroundModes.includes(mode)) {
+                    config.modResults.UIBackgroundModes.push(mode);
+                }
+            });
+        }
+        return config;
+    });
+};
+const withBleNitro = (config, props = {}) => {
+    // Validate props
+    if (props.neverForLocation && !props.isBackgroundEnabled) {
+        WarningAggregator.addWarningForPlatform('android', 'react-native-ble-nitro', 'neverForLocation is set to true but isBackgroundEnabled is false. ' +
+            'This might cause issues with BLE scanning on some Android devices.');
+    }
+    if (props.modes && props.modes.some(mode => !['peripheral', 'central'].includes(mode))) {
+        WarningAggregator.addWarningForPlatform('ios', 'react-native-ble-nitro', 'Invalid background mode specified. Only "peripheral" and "central" are supported.');
+    }
+    // Apply platform-specific configurations
+    config = withBleNitroAndroid(config, props);
+    config = withBleNitroIOS(config, props);
+    return config;
+};
+export default withBleNitro;

package/react-native.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: './android',
+        packageImportPath: 'import co.zyke.ble.BleNitroPackage;',
+      },
+      ios: {
+        project: './ios/BleNitro.xcodeproj',
+      },
+    },
+  },
+};

package/src/BleManagerCompatFactory.ts

@@ -0,0 +1,373 @@
+/**
+ * BleManager Compatibility Factory
+ * 
+ * Creates BleManager instances with full react-native-ble-plx compatibility
+ * by wrapping the Nitro implementation with compatibility shims
+ */
+
+import { createBleManager } from './BleManagerFactory';
+import type { BleManager as BleManagerInterface } from './specs/BleManager.nitro';
+import type { 
+  BleManagerOptions,
+  UUID,
+  DeviceId,
+  TransactionId,
+  ConnectionPriority,
+  ConnectionOptions,
+  ScanOptions,
+  NativeDevice,
+  NativeService,
+  NativeCharacteristic,
+  NativeDescriptor,
+  LogLevel,
+  State,
+  Subscription
+} from './specs/types';
+import { DeviceWrapper } from './compatibility/deviceWrapper';
+import { 
+  stateToString, 
+  stringToState,
+  logLevelToString,
+  stringToLogLevel,
+  normalizeLogLevel,
+  normalizeCharacteristicSubscriptionType,
+  characteristicSubscriptionTypeToString
+} from './compatibility/enums';
+import { serviceDataMapToArray } from './compatibility/serviceData';
+
+/**
+ * BleManager wrapper that provides react-native-ble-plx compatibility
+ */
+export class BleManagerCompat {
+  private bleManager: BleManagerInterface;
+
+  constructor(options?: BleManagerOptions) {
+    this.bleManager = createBleManager(options);
+  }
+
+  // Lifecycle
+  async destroy(): Promise<void> {
+    return await this.bleManager.destroy();
+  }
+
+  // Common operations with compatibility
+  async setLogLevel(logLevel: LogLevel | string): Promise<string> {
+    const normalizedLogLevel = normalizeLogLevel(logLevel);
+    const result = await this.bleManager.setLogLevel(normalizedLogLevel);
+    return logLevelToString(result);
+  }
+
+  async logLevel(): Promise<string> {
+    const result = await this.bleManager.logLevel();
+    return logLevelToString(result);
+  }
+
+  async cancelTransaction(transactionId: TransactionId): Promise<void> {
+    return await this.bleManager.cancelTransaction(transactionId);
+  }
+
+  // State management with string conversion
+  async enable(transactionId?: TransactionId): Promise<BleManagerCompat> {
+    await this.bleManager.enable(transactionId);
+    return this;
+  }
+
+  async disable(transactionId?: TransactionId): Promise<BleManagerCompat> {
+    await this.bleManager.disable(transactionId);
+    return this;
+  }
+
+  async state(): Promise<string> {
+    const result = await this.bleManager.state();
+    return stateToString(result);
+  }
+
+  onStateChange(
+    listener: (newState: string) => void, 
+    emitCurrentState?: boolean
+  ): Subscription {
+    return this.bleManager.onStateChange((state) => {
+      listener(stateToString(state));
+    }, emitCurrentState);
+  }
+
+  // Device scanning with compatibility wrappers
+  async startDeviceScan(
+    uuids: UUID[] | null,
+    options: ScanOptions | null,
+    listener: (error: any | null, scannedDevice: DeviceWrapper | null) => void
+  ): Promise<void> {
+    return await this.bleManager.startDeviceScan(uuids, options, (error, device) => {
+      listener(error, device ? new DeviceWrapper(this.createDeviceFromNative(device)) : null);
+    });
+  }
+
+  async stopDeviceScan(): Promise<void> {
+    return await this.bleManager.stopDeviceScan();
+  }
+
+  // Connection management
+  async connectToDevice(
+    deviceIdentifier: DeviceId,
+    options?: Partial<ConnectionOptions>
+  ): Promise<DeviceWrapper> {
+    // Provide defaults for Nitro's required fields
+    const connectionOptions: ConnectionOptions = {
+      autoConnect: options?.autoConnect ?? false,
+      requestMTU: options?.requestMTU ?? 23,
+      timeout: options?.timeout ?? 0,
+    };
+
+    const result = await this.bleManager.connectToDevice(deviceIdentifier, connectionOptions);
+    return new DeviceWrapper(this.createDeviceFromNative(result));
+  }
+
+  async cancelDeviceConnection(deviceIdentifier: DeviceId): Promise<DeviceWrapper> {
+    const result = await this.bleManager.cancelDeviceConnection(deviceIdentifier);
+    return new DeviceWrapper(this.createDeviceFromNative(result));
+  }
+
+  async isDeviceConnected(deviceIdentifier: DeviceId): Promise<boolean> {
+    return await this.bleManager.isDeviceConnected(deviceIdentifier);
+  }
+
+  onDeviceDisconnected(
+    deviceIdentifier: DeviceId,
+    listener: (error: any | null, device: DeviceWrapper | null) => void
+  ): Subscription {
+    return this.bleManager.onDeviceDisconnected(deviceIdentifier, (error, device) => {
+      listener(error, device ? new DeviceWrapper(this.createDeviceFromNative(device)) : null);
+    });
+  }
+
+  // Device discovery
+  async devices(deviceIdentifiers: DeviceId[]): Promise<DeviceWrapper[]> {
+    const result = await this.bleManager.devices(deviceIdentifiers);
+    return result.map(device => new DeviceWrapper(this.createDeviceFromNative(device)));
+  }
+
+  async connectedDevices(serviceUUIDs: UUID[]): Promise<DeviceWrapper[]> {
+    const result = await this.bleManager.connectedDevices(serviceUUIDs);
+    return result.map(device => new DeviceWrapper(this.createDeviceFromNative(device)));
+  }
+
+  // RSSI and MTU operations
+  async readRSSIForDevice(
+    deviceIdentifier: DeviceId,
+    transactionId?: TransactionId
+  ): Promise<DeviceWrapper> {
+    const result = await this.bleManager.readRSSIForDevice(deviceIdentifier, transactionId);
+    return new DeviceWrapper(this.createDeviceFromNative(result));
+  }
+
+  async requestMTUForDevice(
+    deviceIdentifier: DeviceId,
+    mtu: number,
+    transactionId?: TransactionId
+  ): Promise<DeviceWrapper> {
+    const result = await this.bleManager.requestMTUForDevice(deviceIdentifier, mtu, transactionId);
+    return new DeviceWrapper(this.createDeviceFromNative(result));
+  }
+
+  async requestConnectionPriorityForDevice(
+    deviceIdentifier: DeviceId,
+    connectionPriority: ConnectionPriority,
+    transactionId?: TransactionId
+  ): Promise<DeviceWrapper> {
+    const result = await this.bleManager.requestConnectionPriorityForDevice(
+      deviceIdentifier,
+      connectionPriority,
+      transactionId
+    );
+    return new DeviceWrapper(this.createDeviceFromNative(result));
+  }
+
+  // Service discovery
+  async discoverAllServicesAndCharacteristicsForDevice(
+    deviceIdentifier: DeviceId,
+    transactionId?: TransactionId
+  ): Promise<DeviceWrapper> {
+    const result = await this.bleManager.discoverAllServicesAndCharacteristicsForDevice(
+      deviceIdentifier,
+      transactionId
+    );
+    return new DeviceWrapper(this.createDeviceFromNative(result));
+  }
+
+  // Service operations
+  async servicesForDevice(deviceIdentifier: DeviceId): Promise<NativeService[]> {
+    return await this.bleManager.servicesForDevice(deviceIdentifier);
+  }
+
+  // Characteristic operations
+  async characteristicsForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID
+  ): Promise<NativeCharacteristic[]> {
+    return await this.bleManager.characteristicsForDevice(deviceIdentifier, serviceUUID);
+  }
+
+  async readCharacteristicForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic> {
+    return await this.bleManager.readCharacteristicForDevice(
+      deviceIdentifier,
+      serviceUUID,
+      characteristicUUID,
+      transactionId
+    );
+  }
+
+  async writeCharacteristicWithResponseForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    base64Value: string,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic> {
+    return await this.bleManager.writeCharacteristicWithResponseForDevice(
+      deviceIdentifier,
+      serviceUUID,
+      characteristicUUID,
+      base64Value,
+      transactionId
+    );
+  }
+
+  async writeCharacteristicWithoutResponseForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    base64Value: string,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic> {
+    return await this.bleManager.writeCharacteristicWithoutResponseForDevice(
+      deviceIdentifier,
+      serviceUUID,
+      characteristicUUID,
+      base64Value,
+      transactionId
+    );
+  }
+
+  monitorCharacteristicForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    listener: (error: any | null, characteristic: NativeCharacteristic | null) => void,
+    transactionId?: TransactionId,
+    subscriptionType?: 'notification' | 'indication'
+  ): Subscription {
+    const nitroSubscriptionType = subscriptionType 
+      ? normalizeCharacteristicSubscriptionType(subscriptionType)
+      : undefined;
+
+    return this.bleManager.monitorCharacteristicForDevice(
+      deviceIdentifier,
+      serviceUUID,
+      characteristicUUID,
+      listener,
+      transactionId,
+      nitroSubscriptionType
+    );
+  }
+
+  // Descriptor operations
+  async descriptorsForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID
+  ): Promise<NativeDescriptor[]> {
+    return await this.bleManager.descriptorsForDevice(
+      deviceIdentifier,
+      serviceUUID,
+      characteristicUUID
+    );
+  }
+
+  async readDescriptorForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor> {
+    return await this.bleManager.readDescriptorForDevice(
+      deviceIdentifier,
+      serviceUUID,
+      characteristicUUID,
+      descriptorUUID,
+      transactionId
+    );
+  }
+
+  async writeDescriptorForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    valueBase64: string,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor> {
+    return await this.bleManager.writeDescriptorForDevice(
+      deviceIdentifier,
+      serviceUUID,
+      characteristicUUID,
+      descriptorUUID,
+      valueBase64,
+      transactionId
+    );
+  }
+
+  /**
+   * Helper method to create a Device wrapper from NativeDevice data
+   * This is a temporary method until we have proper Device Nitro objects
+   */
+  private createDeviceFromNative(nativeDevice: NativeDevice): any {
+    // This is a placeholder - in the actual implementation, we'd need to create
+    // proper Nitro Device objects, but for now we'll work with the native data
+    return {
+      id: nativeDevice.id,
+      deviceName: nativeDevice.name,
+      rssi: nativeDevice.rssi,
+      mtu: nativeDevice.mtu,
+      manufacturerData: nativeDevice.manufacturerData,
+      rawScanRecord: nativeDevice.rawScanRecord,
+      serviceData: nativeDevice.serviceData,
+      serviceUUIDs: nativeDevice.serviceUUIDs,
+      localName: nativeDevice.localName,
+      txPowerLevel: nativeDevice.txPowerLevel,
+      solicitedServiceUUIDs: nativeDevice.solicitedServiceUUIDs,
+      isConnectable: nativeDevice.isConnectable,
+      overflowServiceUUIDs: nativeDevice.overflowServiceUUIDs,
+      // Add placeholder methods - these would be implemented in the actual Device class
+      requestConnectionPriority: async () => this.createDeviceFromNative(nativeDevice),
+      readRSSI: async () => this.createDeviceFromNative(nativeDevice),
+      requestMTU: async () => this.createDeviceFromNative(nativeDevice),
+      connect: async () => this.createDeviceFromNative(nativeDevice),
+      cancelConnection: async () => this.createDeviceFromNative(nativeDevice),
+      isConnected: async () => false,
+      onDisconnected: () => ({ remove: () => {} }),
+      discoverAllServicesAndCharacteristics: async () => this.createDeviceFromNative(nativeDevice),
+      services: async () => [],
+      characteristicsForService: async () => [],
+      readCharacteristicForService: async () => ({}),
+      writeCharacteristicWithResponseForService: async () => ({}),
+      writeCharacteristicWithoutResponseForService: async () => ({}),
+      monitorCharacteristicForService: () => ({ remove: () => {} }),
+      descriptorsForService: async () => [],
+      readDescriptorForService: async () => ({}),
+      writeDescriptorForService: async () => ({}),
+    };
+  }
+}
+
+/**
+ * Factory function to create a compatibility BleManager
+ */
+export function createBleManagerCompat(options?: BleManagerOptions): BleManagerCompat {
+  return new BleManagerCompat(options);
+}

package/src/BleManagerFactory.ts

@@ -0,0 +1,30 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { BleManager as BleManagerInterface } from './specs/BleManager.nitro';
+import type { BleManagerOptions } from './specs/types';
+
+/**
+ * Creates a BleManager instance using Nitro Modules
+ * This function maintains compatibility with react-native-ble-plx's BleManager constructor
+ */
+export function createBleManager(options?: BleManagerOptions): BleManagerInterface {
+  const BleManagerModule = NitroModules.createHybridObject<BleManagerInterface>('BleManager');
+  
+  if (!BleManagerModule) {
+    throw new Error(
+      'Failed to create BleManager: Nitro module not found. ' +
+      'Make sure react-native-ble-nitro is properly installed and linked.'
+    );
+  }
+
+  // If options are provided, we could initialize with them
+  // For now, we return the module directly as Nitro handles the native initialization
+  return BleManagerModule;
+}
+
+/**
+ * Legacy compatibility: Export a BleManager constructor function
+ * This maintains compatibility with code that imports { BleManager } from 'react-native-ble-plx'
+ */
+export const BleManager = function(options?: BleManagerOptions): BleManagerInterface {
+  return createBleManager(options);
+} as any;