![\"Munim](\"./.github/resources/banner.png?v=3\")
\n \n \n \n munim-bluetooth
\n \n
\n \n ![\"Package](\"https://img.shields.io/npm/v/munim-bluetooth.svg?style=flat-square&label=Version&labelColor=000000&color=0066CC\")
\n \n \n ![\"License:](\"https://img.shields.io/badge/License-Apache%202.0-success.svg?style=flat-square&color=33CC12\"){kind=icon}
\n \n \n ![\"Downloads\"](\"https://img.shields.io/npm/dm/munim-bluetooth.svg?style=flat-square&labelColor=gray&color=33CC12&label=Downloads\")
\n \n \n ![\"Total](\"https://img.shields.io/npm/dt/munim-bluetooth.svg?style=flat-square&labelColor=gray&color=0066CC&label=Total%20Downloads\")
\n \n
\n Works with Expo\n β’ \n Read the Documentation\n β’ \n Report Issues\n
\n\nLearn about building BLE apps in our documentation!
\n\n- [Getting Started](#-installation)\n- [API Reference](#-api-reference)\n- [Usage Examples](#-usage-examples)\n- [Troubleshooting](#-troubleshooting)\n\n## π Features\n\n### Peripheral Mode\n\n- π΅ **BLE Peripheral Mode**: Transform your React Native app into a BLE peripheral device\n- π‘ **Service Advertising**: Advertise custom GATT services with multiple characteristics\n- π **Real-time Communication**: Support for read, write, and notify operations\n- β **Platform-Aware BLE Advertising**: Use service UUIDs and local names cross-platform, plus Android advertising payload data where the OS allows it\n- π§ **Dynamic Updates**: Update advertising data while advertising is active\n\n### Central Mode\n\n- π **Device Scanning**: Scan for BLE devices with filtering options\n- π **Device Connection**: Connect and disconnect from BLE devices\n- π **GATT Operations**: Discover services, read/write characteristics\n- π **Notifications**: Subscribe to characteristic notifications/indications\n- πΆ **RSSI Monitoring**: Read signal strength for connected devices\n\n### Additional Features\n\n- π± **Cross-platform**: Works on both iOS and Android\n- π§ **Capability Reporting**: `getCapabilities()` reports platform and hardware support before you call optional APIs\n- πΈοΈ **Apple Multipeer Transport**: iOS/iPadOS devices can discover, invite, and message nearby peers with Apple's Multipeer Connectivity\n- 𧡠**LE L2CAP Channels**: Stream payloads over LE Credit Based Channels on supported iOS and Android versions\n- π **Android Classic Bluetooth**: Android RFCOMM client/server messaging for SPP-style devices\n- π― **TypeScript Support**: Full TypeScript definitions included\n- β‘ **High Performance**: Built with React Native's Nitro modules architecture\n- π **Expo Compatible**: Works seamlessly with Expo managed and bare workflows\n- π **Permission Handling**: Built-in permission request helpers\n\n## Platform Support Matrix\n\n| Capability | iOS | Android | Notes |\n| --- | --- | --- | --- |\n| Peripheral advertising | β | β | iOS only allows CoreBluetooth-supported advertising keys such as local name and service UUIDs. Android splits primary advertising data and scan response data to stay within BLE size limits. |\n| Peripheral GATT services | β | β | Read and write requests are handled natively on both platforms. Characteristics can require encrypted access; authenticated-MITM permissions are Android-only because CoreBluetooth has no matching public option. |\n| Peripheral notify/indicate subscriptions | β | β | Subscribe/unsubscribe events are emitted when centrals change CCC state. |\n| Central scan | β | β | Service UUID, name, and manufacturer filters on both platforms (iOS applies name/manufacturer in-process); Android also takes address filters and `ScanSettings`. Android scan failures, including its 5-starts-per-30-seconds throttle, emit `scanFailed`. |\n| Central connect/disconnect | β | β | `connect()` times out after 15 seconds by default (`timeoutMs` configurable); `autoConnect` maps to Android background connect and iOS 17+ auto-reconnect. |\n| Central service discovery | β | β | Emits `servicesDiscovered` in addition to resolving the Promise. Native timeout rejects if callbacks do not arrive. |\n| Central characteristic read | β | β | Resolves with hex-encoded values. Native timeout rejects if callbacks do not arrive. |\n| Central characteristic write | β | β | Supports `write` and `writeWithoutResponse`. With-response writes have native timeout protection; write-without-response is flow controlled, and `getMaximumWriteLength()` reports the payload limit. |\n| Central descriptor read/write | β | β | Uses `readDescriptor()` and `writeDescriptor()` with hex-encoded values. Native timeout rejects if callbacks do not arrive. |\n| Central notify/indicate subscription | β | β | Values emit through `characteristicValueChanged`. |\n| RSSI read | β | β | Resolves with dBm. |\n| ATT MTU request | β | β | Android negotiates the requested MTU. iOS negotiates the MTU itself; `requestMTU()` resolves with the MTU in effect. |\n| Connection priority | β | β | Android `requestConnectionPriority()`; iOS resolves `false`. |\n| GATT cache refresh / Service Changed | β | β | Both emit `servicesChanged` (Android 12+). `refreshGattCache()` is Android-only; iOS resolves `false`. |\n| Enable Bluetooth prompt | β | β | Android `requestEnable()` shows the system dialog; iOS resolves with the current state. |\n| BLE PHY read/preference | β | β | Android 8+ supports `readPhy()` and `setPreferredPhy()` when hardware allows it. |\n| Pairing/bond state | β | β | Android supports bond state, lists bonded devices (`getBondedDevices()`), and starts/removes bonds. iOS handles pairing automatically and does not expose bond management through CoreBluetooth. |\n| Extended advertising | β | β | Android 8+ supports `startExtendedAdvertising()` on hardware with LE extended advertising. iOS does not expose BLE extended advertising. |\n| BLE L2CAP channel streams | β | β | iOS uses CoreBluetooth LE Credit Based Channels. Android requires Android 10+ for LE CoC sockets. Published and outbound channels require encryption by default. |\n| Classic Bluetooth RFCOMM | β | β | Android supports discovery, SPP-style RFCOMM client connections, server/listener sockets, disconnect, write, and receive events. iOS apps cannot use public Classic Bluetooth RFCOMM APIs. |\n| Apple Multipeer Connectivity | β | β | iOS/iPadOS devices can discover peers, approve incoming invitations explicitly, manually invite selected peers, and exchange encrypted messages. Android cannot join Apple's Multipeer sessions; use BLE/GATT for iOS-to-Android. |\n\nCall `getCapabilities()` at runtime when you need optional behavior. Platform support can still vary by OS version, hardware, permissions, and app background state.\n\n## π¦ Installation\n\n### React Native CLI\n\n```bash\nnpm install munim-bluetooth react-native-nitro-modules\n# or\nyarn add munim-bluetooth react-native-nitro-modules\n```\n\n### Expo\n\n```bash\nnpx expo install munim-bluetooth react-native-nitro-modules\n```\n\n> **Note**: This library requires Expo SDK 50+ and works with both managed and bare workflows. To support Nitro modules, you need React Native version v0.78.0 or higher.\n>\n> **Important**: This package requires a native development build in Expo. It does not work in Expo Go. After installing, run `npx expo run:ios`, `npx expo run:android`, or create a development build with EAS.\n\n### iOS Setup\n\nFor iOS, the library is automatically linked. However, you need to add the following to your `Info.plist`:\n\n```xml\n![\"Star](\"https://user-images.githubusercontent.com/9664363/185428788-d762fd5d-97b3-4f59-8db7-f72405be9677.gif\")
\n","readmeFilename":"README.md"}![\"Munim](\"https://img.shields.io/badge/GitHub-222222?style=for-the-badge&logo=github&logoColor=white\"){kind=icon}
\n ![\"Munim](\"https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white\"){kind=icon}
\n ![\"Munim](\"https://img.shields.io/badge/Website-0066CC?style=for-the-badge&logo=globe&logoColor=white\"){kind=icon}
\n