mobile-hardware-ble-nfc
BLE scanning/connecting/GATT operations with react-native-ble-plx, NFC tag reading/writing with react-native-nfc-manager, permissions, background mode, battery-efficient patterns
Install
npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/mobile-hardware-ble-nfc/skills/mobile-hardware-ble-nfc
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
git clone https://github.com/agents-inc/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
BLE & NFC Patterns
Quick Guide: Use
react-native-ble-plxfor BLE (scanning, connecting, GATT read/write/monitor). Usereact-native-nfc-managerfor NFC (NDEF read/write, tag technology access). BLE values are Base64-encoded -- decode before use. NFC operations follow request-technology/operate/cancel-technology lifecycle. Always clean up: remove BLE subscriptions, callcancelTechnologyRequest()for NFC, anddestroy()the BleManager. MTU defaults to 23 bytes (20 usable) -- negotiate higher on Android. iOS auto-negotiates up to 187 bytes.
<critical_requirements>
CRITICAL: Before Using This Skill
(You MUST call destroy() on BleManager when deallocating resources -- leaking the manager causes native memory leaks and zombie listeners)
(You MUST call discoverAllServicesAndCharacteristics() after connecting before any read/write/monitor operations -- GATT structure is not available until discovered)
(You MUST call cancelTechnologyRequest() in a finally block after every NFC operation -- failing to release the NFC session blocks subsequent scans)
(You MUST check BLE adapter state (PoweredOn) before scanning -- scanning while powered off or unauthorized throws errors silently on some devices)
(You MUST remove all BLE subscriptions (scan listeners, characteristic monitors, disconnect listeners) on cleanup -- leaked subscriptions cause crashes after component unmount)
</critical_requirements>
Auto-detection: react-native-ble-plx, BleManager, startDeviceScan, connectToDevice, monitorCharacteristicForDevice, writeCharacteristicWithResponseForDevice, readCharacteristicForDevice, requestMTUForDevice, react-native-nfc-manager, NfcManager, NfcTech, Ndef, requestTechnology, cancelTechnologyRequest, writeNdefMessage, ndefHandler, useCodeScanner BLE, BLE scanning, NFC tag, NDEF record, characteristic notification, GATT
When to use:
- Scanning for and connecting to BLE peripherals (IoT sensors, wearables, medical devices)
- Reading/writing BLE GATT characteristics and monitoring notifications
- Reading NDEF tags or writing NDEF records to NFC tags
- Implementing background BLE reconnection with state restoration
- MTU negotiation for large data transfers over BLE
- Accessing low-level NFC technologies (NfcA, IsoDep, MifareUltralight)
When NOT to use:
- Classic Bluetooth audio/file transfer (different protocol, different libraries)
- BLE peripheral/server mode (react-native-ble-plx is central-only)
- Web-based Bluetooth (use Web Bluetooth API)
- Wi-Fi Direct or peer-to-peer networking
Key patterns covered:
- BLE lifecycle: scan, connect, discover services, read/write/monitor, disconnect
- Battery-efficient scanning with UUID filters and scan modes
- MTU negotiation (Android explicit, iOS automatic)
- Characteristic subscriptions (notifications/indications) with cleanup
- BLE reconnection and disconnect monitoring
- NFC NDEF read/write lifecycle with technology request/cancel
- NFC technology types and platform availability (iOS vs Android)
- Permission handling for both BLE and NFC
Detailed Resources:
- examples/core.md - BLE scanning, connecting, GATT operations, disconnect handling
- examples/nfc.md - NFC NDEF reading/writing, technology types, platform differences
- reference.md - API quick reference, permission matrix, decision frameworks
<decision_framework>
Decision Framework
BLE vs NFC
What kind of hardware interaction?
|
+-> Continuous connection with a peripheral (sensor, wearable)?
| +-> BLE -- long-lived connection with GATT operations
|
+-> One-tap read/write (tag, card)?
| +-> NFC -- session-based, tap and go
|
+-> Background monitoring of nearby devices?
| +-> BLE -- background scanning with state restoration
|
+-> Quick device provisioning (write config to tag)?
+-> NFC -- write NDEF record, tap target device
BLE Write Method
Which write method?
|
+-> Data MUST arrive reliably?
| +-> writeCharacteristicWithResponseForService (acknowledged, slower)
|
+-> Speed matters more than reliability?
| +-> writeCharacteristicWithoutResponseForService (fire-and-forget, faster)
|
+-> Large payload (> MTU)?
+-> Negotiate higher MTU first, then use write-with-response
NFC Technology Selection
What kind of NFC tag?
|
+-> Standard NDEF content (URL, text, MIME)?
| +-> NfcTech.Ndef (iOS + Android)
|
+-> ISO 14443-3A tag (raw commands)?
| +-> NfcTech.NfcA (iOS + Android)
|
+-> Smart card / ISO 7816 (APDU commands)?
| +-> NfcTech.IsoDep (iOS + Android)
|
+-> Mifare Classic (Android only)?
| +-> NfcTech.MifareClassic
|
+-> Mifare Ultralight (Android only)?
+-> NfcTech.MifareUltralight
</decision_framework>
<red_flags>
RED FLAGS
High Priority Issues:
- Skipping
discoverAllServicesAndCharacteristics()after connecting -- read/write/monitor calls fail silently or throw errors because GATT structure is not cached - Not removing BLE subscriptions on cleanup -- leaked subscriptions fire callbacks after component unmount, causing "setState on unmounted component" crashes
- Forgetting
cancelTechnologyRequest()in NFC finally block -- NFC session stays locked, all subsequent NFC operations fail until app restart - Creating multiple BleManager instances -- each instance allocates native resources. Create ONE and share it. Call
destroy()only once on app teardown. - Scanning without UUID filter and without timeout -- scans all devices indefinitely, drains battery rapidly
Medium Priority Issues:
- Not checking
State.PoweredOnbefore scanning -- scanning while Bluetooth is off throws errors on some devices and does nothing on others - Not handling Base64 encoding/decoding for BLE characteristic values -- raw Base64 strings are not human-readable and cannot be compared directly
- Using
writeCharacteristicWithoutResponseForServicefor critical data -- fire-and-forget may lose data; use write-with-response for reliability - Not requesting MTU on Android -- default 23-byte MTU means 20 usable bytes per packet, making large transfers extremely slow
- Hardcoding service/characteristic UUIDs inline instead of using named constants
Gotchas & Edge Cases:
- iOS BLE device IDs are random UUIDs, not MAC addresses -- they can change after Bluetooth is toggled or the device restarts. Do not persist iOS device IDs for reconnection; use service UUID scanning instead.
- Android 12+ changed BLE permissions --
BLUETOOTH_SCANandBLUETOOTH_CONNECTreplacedACCESS_FINE_LOCATIONfor BLE scanning (setneverForLocation: truein Expo config if scanning does not need location) - Android 14+ defaults MTU to 517 bytes --
requestMTUmay be unnecessary on newer Android devices. Checkdevice.mtuafter connection. - iOS auto-negotiates MTU up to 187 bytes -- calling
requestMTUon iOS has no effect onDeviceDisconnectedfires once per registration -- you must re-register the listener after each reconnection if you want continued disconnect monitoring- NfcTech.NfcB, NfcF, NfcV are Android-only -- iOS has different equivalents (Iso15693IOS, FelicaIOS). Always check platform before requesting a technology.
- NFC on iOS shows a system scan dialog -- you cannot customize it beyond the
alertMessage. On Android, scanning is silent. - BLE
allowDuplicatesis iOS-only -- Android always emits duplicates. Deduplicate in your scan callback using a Set of device IDs. - HCE (Host Card Emulation) is NOT supported by react-native-nfc-manager -- use a dedicated library like
react-native-hcefor card emulation - NFC
getTag()returns the last discovered tag -- if no tag was tapped during the session, it returns the previous tag. Always request technology first.
</red_flags>
<critical_reminders>
CRITICAL REMINDERS
(You MUST call destroy() on BleManager when deallocating resources -- leaking the manager causes native memory leaks and zombie listeners)
(You MUST call discoverAllServicesAndCharacteristics() after connecting before any read/write/monitor operations -- GATT structure is not available until discovered)
(You MUST call cancelTechnologyRequest() in a finally block after every NFC operation -- failing to release the NFC session blocks subsequent scans)
(You MUST check BLE adapter state (PoweredOn) before scanning -- scanning while powered off or unauthorized throws errors silently on some devices)
(You MUST remove all BLE subscriptions (scan listeners, characteristic monitors, disconnect listeners) on cleanup -- leaked subscriptions cause crashes after component unmount)
Failure to follow these rules will cause native crashes, memory leaks, blocked NFC sessions, and battery drain.
</critical_reminders>
Files (skills)
-
examples
-
core.md 14.4 KB
Loading… -
nfc.md 11.4 KB
Loading…
-
-
reference.md 11.9 KB
Loading… -
SKILL.md 19.2 KB
--- name: mobile-hardware-ble-nfc description: BLE scanning/connecting/GATT operations with react-native-ble-plx, NFC tag reading/writing with react-native-nfc-manager, permissions, background mode, battery-efficient patterns --- # BLE & NFC Patterns > **Quick Guide:** Use `react-native-ble-plx` for BLE (scanning, connecting, GATT read/write/monitor). Use `react-native-nfc-manager` for NFC (NDEF read/write, tag technology access). BLE values are Base64-encoded -- decode before use. NFC operations follow request-technology/operate/cancel-technology lifecycle. Always clean up: remove BLE subscriptions, call `cancelTechnologyRequest()` for NFC, and `destroy()` the BleManager. MTU defaults to 23 bytes (20 usable) -- negotiate higher on Android. iOS auto-negotiates up to 187 bytes. --- <critical_requirements> ## CRITICAL: Before Using This Skill **(You MUST call `destroy()` on BleManager when deallocating resources -- leaking the manager causes native memory leaks and zombie listeners)** **(You MUST call `discoverAllServicesAndCharacteristics()` after connecting before any read/write/monitor operations -- GATT structure is not available until discovered)** **(You MUST call `cancelTechnologyRequest()` in a finally block after every NFC operation -- failing to release the NFC session blocks subsequent scans)** **(You MUST check BLE adapter state (`PoweredOn`) before scanning -- scanning while powered off or unauthorized throws errors silently on some devices)** **(You MUST remove all BLE subscriptions (scan listeners, characteristic monitors, disconnect listeners) on cleanup -- leaked subscriptions cause crashes after component unmount)** </critical_requirements> --- **Auto-detection:** react-native-ble-plx, BleManager, startDeviceScan, connectToDevice, monitorCharacteristicForDevice, writeCharacteristicWithResponseForDevice, readCharacteristicForDevice, requestMTUForDevice, react-native-nfc-manager, NfcManager, NfcTech, Ndef, requestTechnology, cancelTechnologyRequest, writeNdefMessage, ndefHandler, useCodeScanner BLE, BLE scanning, NFC tag, NDEF record, characteristic notification, GATT **When to use:** - Scanning for and connecting to BLE peripherals (IoT sensors, wearables, medical devices) - Reading/writing BLE GATT characteristics and monitoring notifications - Reading NDEF tags or writing NDEF records to NFC tags - Implementing background BLE reconnection with state restoration - MTU negotiation for large data transfers over BLE - Accessing low-level NFC technologies (NfcA, IsoDep, MifareUltralight) **When NOT to use:** - Classic Bluetooth audio/file transfer (different protocol, different libraries) - BLE peripheral/server mode (react-native-ble-plx is central-only) - Web-based Bluetooth (use Web Bluetooth API) - Wi-Fi Direct or peer-to-peer networking **Key patterns covered:** - BLE lifecycle: scan, connect, discover services, read/write/monitor, disconnect - Battery-efficient scanning with UUID filters and scan modes - MTU negotiation (Android explicit, iOS automatic) - Characteristic subscriptions (notifications/indications) with cleanup - BLE reconnection and disconnect monitoring - NFC NDEF read/write lifecycle with technology request/cancel - NFC technology types and platform availability (iOS vs Android) - Permission handling for both BLE and NFC **Detailed Resources:** - [examples/core.md](examples/core.md) - BLE scanning, connecting, GATT operations, disconnect handling - [examples/nfc.md](examples/nfc.md) - NFC NDEF reading/writing, technology types, platform differences - [reference.md](reference.md) - API quick reference, permission matrix, decision frameworks --- <philosophy> ## Philosophy BLE and NFC are hardware communication protocols with fundamentally different interaction models: **BLE** is connection-oriented and long-lived. You scan for devices, establish a persistent connection, discover the GATT service/characteristic tree, then read/write/subscribe to characteristics over time. Connections can last minutes to hours. The main challenges are connection lifecycle management, reconnection, and battery-efficient scanning. **NFC** is session-oriented and brief. You request a technology, tap a tag, perform one operation (read or write), and release the technology. Sessions last seconds. The main challenges are platform differences (iOS vs Android technology support) and ensuring proper cleanup. **Core principles:** 1. **Lifecycle-driven** -- BLE connections have a strict flow: scan -> connect -> discover -> operate -> disconnect. Skipping steps causes silent failures. 2. **Subscription-based** -- BLE characteristic monitoring returns Subscription objects that MUST be removed on cleanup. NFC technology requests MUST be canceled in finally blocks. 3. **Base64-encoded** -- All BLE characteristic values are Base64-encoded strings. Decode before use, encode before write. 4. **Platform-aware** -- BLE permissions differ significantly between Android versions. NFC technology support varies between iOS and Android. Always check platform capabilities. **When to use BLE:** - Continuous communication with a peripheral (sensor readings, device control) - Background monitoring (health devices, beacons) - Large data transfers requiring MTU negotiation **When to use NFC:** - One-tap interactions (read a tag, write a tag, verify identity) - Quick data exchange without pairing - Tag provisioning or configuration **When NOT to use either:** - High-bandwidth streaming (use Wi-Fi or classic Bluetooth) - Cross-platform web apps (use Web Bluetooth / Web NFC) </philosophy> --- <patterns> ## Core Patterns ### Pattern 1: BLE Manager Initialization and State Create one BleManager instance for the app lifetime. Check adapter state before operations. ```typescript import { BleManager, State } from "react-native-ble-plx"; const manager = new BleManager(); // Wait for Bluetooth to be ready manager.onStateChange((state) => { if (state === State.PoweredOn) { // Safe to scan } }, true); // true = emit current state immediately // Cleanup on app teardown manager.destroy(); ``` **Why good:** single manager instance, state checked before operations, destroy called on cleanup, `true` flag emits current state immediately so you don't miss the initial PoweredOn See [examples/core.md](examples/core.md) for full initialization with background mode support and state restoration. --- ### Pattern 2: BLE Scanning with Filters Filter scans by service UUIDs for battery efficiency. Stop scanning as soon as you find the target device. ```typescript const HEART_RATE_SERVICE_UUID = "0000180d-0000-1000-8000-00805f9b34fb"; const SCAN_TIMEOUT_MS = 10000; manager.startDeviceScan( [HEART_RATE_SERVICE_UUID], // Filter by service UUID -- null scans ALL devices { allowDuplicates: false }, (error, device) => { if (error) { /* handle */ return; } if (device?.name === "MyDevice") { manager.stopDeviceScan(); // Connect to device } }, ); // Always set a timeout to stop scanning setTimeout(() => manager.stopDeviceScan(), SCAN_TIMEOUT_MS); ``` **Why good:** UUID filter reduces battery drain, scan timeout prevents indefinite scanning, duplicates disabled to reduce callback noise, scan stopped once target found See [examples/core.md](examples/core.md) for complete scanning with Android scan modes and permission handling. --- ### Pattern 3: BLE Connection and GATT Discovery Connect, discover services/characteristics, then operate. Always monitor for disconnects. ```typescript const device = await manager.connectToDevice(deviceId, { requestMTU: 512, // Android only -- request larger MTU during connection }); // MUST discover before read/write/monitor await device.discoverAllServicesAndCharacteristics(); // Monitor for unexpected disconnects const disconnectSubscription = device.onDisconnected( (error, disconnectedDevice) => { // Handle reconnection logic }, ); // Cleanup disconnectSubscription.remove(); await device.cancelConnection(); ``` **Why good:** MTU requested during connection (Android), GATT discovered before operations, disconnect monitored for reconnection, subscription removed on cleanup See [examples/core.md](examples/core.md) for full connection flow with retry logic and error handling. --- ### Pattern 4: Reading and Writing BLE Characteristics All values are Base64-encoded. Decode after read, encode before write. ```typescript import { decode as atob, encode as btoa } from "base-64"; const SERVICE_UUID = "0000180d-0000-1000-8000-00805f9b34fb"; const CHAR_UUID = "00002a37-0000-1000-8000-00805f9b34fb"; // Read const characteristic = await device.readCharacteristicForService( SERVICE_UUID, CHAR_UUID, ); const decodedValue = atob(characteristic.value ?? ""); // Write with response (acknowledged) const base64Value = btoa("command-data"); await device.writeCharacteristicWithResponseForService( SERVICE_UUID, CHAR_UUID, base64Value, ); // Write without response (faster, no acknowledgment) await device.writeCharacteristicWithoutResponseForService( SERVICE_UUID, CHAR_UUID, base64Value, ); ``` **Why good:** named constants for UUIDs, Base64 decode/encode explicit, write-with-response used for reliable delivery, write-without-response available for speed See [examples/core.md](examples/core.md) for complete read/write patterns with error handling. --- ### Pattern 5: Characteristic Monitoring (Notifications) Subscribe to characteristic value changes. Returns a Subscription that MUST be removed. ```typescript const subscription = device.monitorCharacteristicForService( SERVICE_UUID, CHAR_UUID, (error, characteristic) => { if (error) { /* handle */ return; } const value = atob(characteristic?.value ?? ""); // Process incoming notification }, ); // CRITICAL: Remove on cleanup subscription.remove(); ``` **Why good:** subscription stored for cleanup, error handled in callback, value decoded from Base64 **Gotcha:** Check `characteristic.isNotifiable` or `characteristic.isIndicatable` before monitoring -- not all characteristics support notifications. See [examples/core.md](examples/core.md) for monitoring with React hooks and cleanup patterns. --- ### Pattern 6: MTU Negotiation Larger MTU = fewer packets for big payloads. iOS negotiates automatically (up to 187 bytes). Android requires explicit request. ```typescript import { Platform } from "react-native"; const DESIRED_MTU = 512; const BLE_HEADER_BYTES = 3; // Request MTU after connection (Android only -- iOS auto-negotiates) if (Platform.OS === "android") { const updatedDevice = await device.requestMTU(DESIRED_MTU); const usableBytes = updatedDevice.mtu - BLE_HEADER_BYTES; // usableBytes is the max payload per packet } ``` **Why good:** platform check avoids unnecessary call on iOS, named constants for MTU and header size, usable bytes calculated correctly (MTU minus 3-byte ATT header) See [reference.md](reference.md) for MTU size recommendations by use case. --- ### Pattern 7: NFC NDEF Read Request NDEF technology, read the tag, clean up in finally block. ```typescript import NfcManager, { NfcTech } from "react-native-nfc-manager"; // Initialize once at app start await NfcManager.start(); async function readNdefTag(): Promise<string | null> { try { await NfcManager.requestTechnology(NfcTech.Ndef); const tag = await NfcManager.getTag(); if (tag?.ndefMessage && tag.ndefMessage.length > 0) { // tag.ndefMessage is an array of NDEF records // Each record has: tnf, type, id, payload (all number arrays) return String.fromCharCode(...tag.ndefMessage[0].payload); } return null; } catch (error) { // User cancelled or tag not found return null; } finally { // CRITICAL: Always release the NFC session await NfcManager.cancelTechnologyRequest(); } } ``` **Why good:** technology request and cancel in try/finally, error handled for user cancellation, start() called once at app initialization, tag null-checked before access See [examples/nfc.md](examples/nfc.md) for complete NDEF reading with record parsing. --- ### Pattern 8: NFC NDEF Write Request technology, encode the message, write, release. ```typescript import NfcManager, { NfcTech, Ndef } from "react-native-nfc-manager"; async function writeNdefTag(url: string): Promise<boolean> { try { await NfcManager.requestTechnology(NfcTech.Ndef); const bytes = Ndef.encodeMessage([Ndef.uriRecord(url)]); await NfcManager.ndefHandler.writeNdefMessage(bytes); return true; } catch (error) { return false; } finally { await NfcManager.cancelTechnologyRequest(); } } ``` **Why good:** Ndef utility encodes records properly, try/finally ensures cleanup, boolean return signals success/failure See [examples/nfc.md](examples/nfc.md) for text records, multi-record messages, and platform-specific handling. --- ### Pattern 9: BLE Permissions BLE permissions differ significantly across Android versions. iOS requires Info.plist entries. ```typescript import { Platform, PermissionsAndroid } from "react-native"; async function requestBlePermissions(): Promise<boolean> { if (Platform.OS === "android") { const apiLevel = Platform.Version; if (apiLevel >= 31) { // Android 12+: BLUETOOTH_SCAN + BLUETOOTH_CONNECT const results = await PermissionsAndroid.requestMultiple([ PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN, PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT, ]); return Object.values(results).every((r) => r === "granted"); } // Android <12: ACCESS_FINE_LOCATION const result = await PermissionsAndroid.request( PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION, ); return result === "granted"; } // iOS: permissions handled via Info.plist (NSBluetoothAlwaysUsageDescription) return true; } ``` **Why good:** Android API level checked for correct permission set, Android 12+ uses new Bluetooth permissions, pre-12 falls back to location permission, iOS handled via plist See [reference.md](reference.md) for the full permission matrix across platforms and Android versions. </patterns> --- <decision_framework> ## Decision Framework ### BLE vs NFC ``` What kind of hardware interaction? | +-> Continuous connection with a peripheral (sensor, wearable)? | +-> BLE -- long-lived connection with GATT operations | +-> One-tap read/write (tag, card)? | +-> NFC -- session-based, tap and go | +-> Background monitoring of nearby devices? | +-> BLE -- background scanning with state restoration | +-> Quick device provisioning (write config to tag)? +-> NFC -- write NDEF record, tap target device ``` ### BLE Write Method ``` Which write method? | +-> Data MUST arrive reliably? | +-> writeCharacteristicWithResponseForService (acknowledged, slower) | +-> Speed matters more than reliability? | +-> writeCharacteristicWithoutResponseForService (fire-and-forget, faster) | +-> Large payload (> MTU)? +-> Negotiate higher MTU first, then use write-with-response ``` ### NFC Technology Selection ``` What kind of NFC tag? | +-> Standard NDEF content (URL, text, MIME)? | +-> NfcTech.Ndef (iOS + Android) | +-> ISO 14443-3A tag (raw commands)? | +-> NfcTech.NfcA (iOS + Android) | +-> Smart card / ISO 7816 (APDU commands)? | +-> NfcTech.IsoDep (iOS + Android) | +-> Mifare Classic (Android only)? | +-> NfcTech.MifareClassic | +-> Mifare Ultralight (Android only)? +-> NfcTech.MifareUltralight ``` </decision_framework> --- <red_flags> ## RED FLAGS **High Priority Issues:** - **Skipping `discoverAllServicesAndCharacteristics()` after connecting** -- read/write/monitor calls fail silently or throw errors because GATT structure is not cached - **Not removing BLE subscriptions on cleanup** -- leaked subscriptions fire callbacks after component unmount, causing "setState on unmounted component" crashes - **Forgetting `cancelTechnologyRequest()` in NFC finally block** -- NFC session stays locked, all subsequent NFC operations fail until app restart - **Creating multiple BleManager instances** -- each instance allocates native resources. Create ONE and share it. Call `destroy()` only once on app teardown. - **Scanning without UUID filter and without timeout** -- scans all devices indefinitely, drains battery rapidly **Medium Priority Issues:** - Not checking `State.PoweredOn` before scanning -- scanning while Bluetooth is off throws errors on some devices and does nothing on others - Not handling Base64 encoding/decoding for BLE characteristic values -- raw Base64 strings are not human-readable and cannot be compared directly - Using `writeCharacteristicWithoutResponseForService` for critical data -- fire-and-forget may lose data; use write-with-response for reliability - Not requesting MTU on Android -- default 23-byte MTU means 20 usable bytes per packet, making large transfers extremely slow - Hardcoding service/characteristic UUIDs inline instead of using named constants **Gotchas & Edge Cases:** - **iOS BLE device IDs are random UUIDs**, not MAC addresses -- they can change after Bluetooth is toggled or the device restarts. Do not persist iOS device IDs for reconnection; use service UUID scanning instead. - **Android 12+ changed BLE permissions** -- `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` replaced `ACCESS_FINE_LOCATION` for BLE scanning (set `neverForLocation: true` in Expo config if scanning does not need location) - **Android 14+ defaults MTU to 517 bytes** -- `requestMTU` may be unnecessary on newer Android devices. Check `device.mtu` after connection. - **iOS auto-negotiates MTU up to 187 bytes** -- calling `requestMTU` on iOS has no effect - **`onDeviceDisconnected` fires once per registration** -- you must re-register the listener after each reconnection if you want continued disconnect monitoring - **NfcTech.NfcB, NfcF, NfcV are Android-only** -- iOS has different equivalents (Iso15693IOS, FelicaIOS). Always check platform before requesting a technology. - **NFC on iOS shows a system scan dialog** -- you cannot customize it beyond the `alertMessage`. On Android, scanning is silent. - **BLE `allowDuplicates` is iOS-only** -- Android always emits duplicates. Deduplicate in your scan callback using a Set of device IDs. - **HCE (Host Card Emulation) is NOT supported by react-native-nfc-manager** -- use a dedicated library like `react-native-hce` for card emulation - **NFC `getTag()` returns the last discovered tag** -- if no tag was tapped during the session, it returns the previous tag. Always request technology first. </red_flags> --- <critical_reminders> ## CRITICAL REMINDERS **(You MUST call `destroy()` on BleManager when deallocating resources -- leaking the manager causes native memory leaks and zombie listeners)** **(You MUST call `discoverAllServicesAndCharacteristics()` after connecting before any read/write/monitor operations -- GATT structure is not available until discovered)** **(You MUST call `cancelTechnologyRequest()` in a finally block after every NFC operation -- failing to release the NFC session blocks subsequent scans)** **(You MUST check BLE adapter state (`PoweredOn`) before scanning -- scanning while powered off or unauthorized throws errors silently on some devices)** **(You MUST remove all BLE subscriptions (scan listeners, characteristic monitors, disconnect listeners) on cleanup -- leaked subscriptions cause crashes after component unmount)** **Failure to follow these rules will cause native crashes, memory leaks, blocked NFC sessions, and battery drain.** </critical_reminders>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.