/mobile-hardware-ble-nfc

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.

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)