react-native-ble-mesh 1.1.0 → 2.0.0

package/README.md

@@ -1,737 +1,620 @@
 # react-native-ble-mesh
 
-> Inspired by [Bitchat](https://github.com/permissionlesstech/bitchat) - this is the React Native version.
+## Send messages without the internet. Like magic! ✨
 
-A **production-ready BLE Mesh Network library** for React Native with Noise Protocol security. This library enables peer-to-peer communication over Bluetooth Low Energy with end-to-end encryption, multi-hop routing, and offline-first capabilities.
+[![npm version](https://img.shields.io/npm/v/react-native-ble-mesh.svg?style=flat-square)](https://www.npmjs.com/package/react-native-ble-mesh)
+[![npm downloads](https://img.shields.io/npm/dm/react-native-ble-mesh.svg?style=flat-square)](https://www.npmjs.com/package/react-native-ble-mesh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![Platform](https://img.shields.io/badge/Platform-iOS%20%7C%20Android-lightgrey.svg?style=flat-square)](https://reactnative.dev/)
+[![Tests](https://img.shields.io/badge/Tests-433%20passing-brightgreen.svg?style=flat-square)]()
 
-[![npm version](https://img.shields.io/npm/v/react-native-ble-mesh.svg)](https://www.npmjs.com/package/react-native-ble-mesh)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+---
 
-## Features
+## What is this?
 
-- **End-to-End Encryption** - Noise Protocol XX handshake with ChaCha20-Poly1305 AEAD
-- **Digital Signatures** - Ed25519 signatures for message authentication and identity verification
-- **Multi-Hop Routing** - Messages can traverse multiple peers to reach their destination
-- **Offline-First** - Works without internet connectivity using BLE
-- **Forward Secrecy** - Automatic session rekeying for enhanced security
-- **Replay Protection** - Sliding window algorithm prevents replay attacks
-- **Traffic Analysis Resistance** - PKCS#7 padding to fixed block sizes
-- **LZ4 Compression** - Efficient bandwidth usage for larger messages
-- **Power Management** - Multiple power modes for battery optimization
-- **Trust Management** - Peer verification, favorites, and blocking
-- **Message Reliability** - Automatic retry with exponential backoff
+Imagine you're at a concert, camping trip, or during a power outage — **no WiFi, no cell service**. How do you text your friends?
 
-## Use Cases
-
-- Offline messaging apps (like Bridgefy, Briar)
-- Disaster communication networks
-- Privacy-focused P2P chat
-- IoT mesh networks
-- Gaming multiplayer over BLE
+**This library lets phones talk to each other using Bluetooth!** Messages hop from phone to phone until they reach your friend — even if they're far away.
 
-## Installation
-
-```bash
-npm install react-native-ble-mesh react-native-get-random-values react-native-ble-plx
-cd ios && pod install
 ```
-
-### Required Setup
-
-**IMPORTANT:** You must import `react-native-get-random-values` at the very top of your entry file (index.js or App.js) **before any other imports**:
-
-```javascript
-// index.js or App.js - This MUST be the first import!
-import 'react-native-get-random-values';
-
-// Now you can import other modules
-import { AppRegistry } from 'react-native';
-import App from './App';
-import { name as appName } from './app.json';
-
-AppRegistry.registerComponent(appName, () => App);
+     You                    Friend's                  Your
+    Phone  ----Bluetooth---> Friend's  ----Bluetooth---> Friend
+                             Phone                      (300m away!)
 ```
 
-This polyfill provides the Web Crypto API (`crypto.getRandomValues`) which is required for cryptographic operations in the mesh network.
-
-### iOS Setup
+**Think of it like a game of telephone, but for text messages and photos!**
 
-Add Bluetooth permissions to your `Info.plist`:
+---
 
-```xml
-<key>NSBluetoothAlwaysUsageDescription</key>
-<string>This app uses Bluetooth to communicate with nearby devices</string>
-<key>NSBluetoothPeripheralUsageDescription</key>
-<string>This app uses Bluetooth to communicate with nearby devices</string>
-<key>UIBackgroundModes</key>
-<array>
-  <string>bluetooth-central</string>
-  <string>bluetooth-peripheral</string>
-</array>
-```
+## See It In Action
 
-### Android Setup
+```javascript
+import { MeshNetwork } from 'react-native-ble-mesh';
 
-Add Bluetooth permissions to your `AndroidManifest.xml`:
+// 1. Create your mesh network
+const mesh = new MeshNetwork({ nickname: 'Alex' });
 
-```xml
-<uses-permission android:name="android.permission.BLUETOOTH" />
-<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
-<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
-<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
-<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
-<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
-```
+// 2. Start it up!
+await mesh.start();
 
-## Quick Start
+// 3. Send a message to everyone nearby
+await mesh.broadcast('Hello everyone! 👋');
 
-### Basic Setup
+// 4. Listen for messages
+mesh.on('messageReceived', (msg) => {
+  console.log(`${msg.from} says: ${msg.text}`);
+});
+```
 
-```javascript
-const { MeshService, BLETransport } = require('react-native-ble-mesh');
+**That's it! Four lines of code and you're chatting without internet!**
 
-// Create and initialize the mesh service
-const mesh = new MeshService();
+---
 
-async function start() {
-  // Initialize with optional configuration
-  await mesh.initialize({
-    displayName: 'Alice',
-    storage: null, // Use in-memory storage
-  });
+## Why Use This?
 
-  // Create transport layer
-  const transport = new BLETransport();
+| Problem | Our Solution |
+|---------|--------------|
+| No WiFi or cell service | Works with just Bluetooth! |
+| Friend is too far away | Messages hop through other phones |
+| Need to send photos? | Send files & images up to 10MB! |
+| Worried about privacy? | Encrypted with battle-tested crypto |
+| Phone battery dying? | Smart power saving built-in |
+| Need to delete everything fast? | One-tap emergency wipe |
+| Using Expo? | Works out of the box! |
+| Need faster transfers? | Wi-Fi Direct for big files |
+| How's my connection? | Real-time signal quality indicator |
 
-  // Start the mesh service
-  await mesh.start(transport);
+---
 
-  console.log('Mesh network started!');
-  console.log('My fingerprint:', mesh.getFingerprint());
-}
+## Cool Features
 
-start();
-```
+### 📡 Messages That Hop
+Your message can jump through **up to 7 phones** to reach someone far away. If Alice can't reach Dave directly, the message goes: Alice → Bob → Carol → Dave!
 
-### Discovering Peers
+### 📸 Send Photos & Files
+Send pictures, documents, or any file up to 10MB. The library chops it into tiny pieces, sends them through the mesh, and puts them back together on the other side. You get a progress bar too!
 
 ```javascript
-// Listen for peer discovery events
-mesh.on('peer-discovered', (peer) => {
-  console.log('Discovered peer:', peer.id);
-  console.log('Display name:', peer.getDisplayName());
+// Send a photo to a friend
+await mesh.sendFile('friend-id', {
+  data: photoBytes,          // The file as bytes
+  name: 'vacation.jpg',      // File name
+  mimeType: 'image/jpeg',    // What kind of file
 });
 
-mesh.on('peer-connected', (peer) => {
-  console.log('Connected to peer:', peer.id);
+// Watch the progress
+mesh.on('fileSendProgress', ({ name, percent }) => {
+  console.log(`Sending ${name}: ${percent}%`);
 });
 
-mesh.on('peer-secured', (peer) => {
-  console.log('Secure session established with:', peer.id);
+// Receive files from others
+mesh.on('fileReceived', ({ from, file }) => {
+  console.log(`Got ${file.name} from ${from}!`);
+  // file.data has the bytes, file.mimeType tells you the type
 });
 ```
 
-### Sending Messages
+### 📶 Connection Quality
+See how good your connection is to each person — like signal bars on your phone!
 
 ```javascript
-// Send a broadcast message to all nearby peers
-const broadcastId = mesh.sendBroadcast('Hello, mesh network!');
-
-// Send a private encrypted message to a specific peer
-const peerId = 'abc123...';
-try {
-  const messageId = await mesh.sendPrivateMessage(peerId, 'Hello, this is private!');
-  console.log('Message sent:', messageId);
-} catch (error) {
-  console.error('Failed to send:', error.message);
-}
-
-// Send a message to a channel
-const channelMessageId = mesh.sendChannelMessage('general', 'Hello channel!');
+const quality = mesh.getConnectionQuality('friend-id');
+// quality.level = 'excellent' | 'good' | 'fair' | 'poor'
+// quality.rssi = -55 (signal strength)
+// quality.latencyMs = 45 (how fast, in milliseconds)
+
+// Get alerted when connection changes
+mesh.on('connectionQualityChanged', ({ peerId, level }) => {
+  if (level === 'poor') {
+    console.log('Connection getting weak! Move closer.');
+  }
+});
 ```
 
-### Receiving Messages
+### 📡 Wi-Fi Direct for Big Files
+Bluetooth is great for messages, but slow for big files. Wi-Fi Direct is **250x faster**! The library automatically picks the best one:
+
+- **Small message?** → Sends via Bluetooth (reliable, low power)
+- **Big photo?** → Sends via Wi-Fi Direct (super fast)
+- **Wi-Fi Direct not available?** → Falls back to Bluetooth automatically
 
 ```javascript
-// Listen for incoming messages
-mesh.on('message', (message) => {
-  console.log('Received message:', message.content);
-  console.log('From:', message.senderId);
-  console.log('Type:', message.type);
-});
+import { MultiTransport } from 'react-native-ble-mesh';
 
-// Listen for private messages specifically
-mesh.on('private-message', (message) => {
-  console.log('Private message from', message.senderId);
-  console.log('Content:', message.content);
+// Use both Bluetooth AND Wi-Fi Direct together
+const transport = new MultiTransport({
+  bleTransport: myBleTransport,
+  wifiTransport: myWifiTransport,
+  strategy: 'auto',  // Let the library decide
 });
 
-// Listen for channel messages
-mesh.on('channel-message', (message) => {
-  console.log('Channel:', message.channelId);
-  console.log('Content:', message.content);
-});
+const mesh = new MeshNetwork({ nickname: 'Alex' });
+await mesh.start(transport);
+// That's it! The library handles everything.
 ```
 
-### Handling Acknowledgments and Read Receipts
+### 🔒 Secret Messages
+Pick the encryption that works best for your app. The library auto-detects the fastest option:
 
-```javascript
-// Listen for message delivery confirmations
-mesh.on('message-delivered', ({ messageId, peerId, timestamp }) => {
-  console.log(`Message ${messageId} delivered to ${peerId}`);
-});
+| Option | Speed | Works On |
+|--------|-------|----------|
+| `react-native-quick-crypto` | ⚡ Blazing fast | React Native |
+| `expo-crypto` + `tweetnacl` | 🚀 Fast | Expo apps |
+| `tweetnacl` | ✅ Good | Everywhere |
 
-// Listen for read receipts
-mesh.on('read-receipt', ({ messageIds, fromPeerId, timestamp }) => {
-  console.log(`Peer ${fromPeerId} read messages:`, messageIds);
+```javascript
+// The library picks the best one automatically!
+const mesh = new MeshNetwork({
+  nickname: 'Alex',
+  crypto: 'auto',  // Auto-detect fastest available
 });
+```
 
-// Send read receipts for messages you've read
-mesh.sendReadReceipt(['msg-id-1', 'msg-id-2']);
+### 📬 Offline Delivery
+Friend's phone turned off? No problem! Your message waits and delivers when they come back online.
 
-// Mark a single message as read
-mesh.markMessageRead('msg-id-1');
-```
+### 🔋 Battery Friendly
+Choose how much battery to use:
+- **High Power** = Faster messages, more battery
+- **Balanced** = Good speed, normal battery (default)
+- **Low Power** = Slower messages, saves battery
+- **Auto** = Let the phone decide based on battery level!
 
-## API Reference
+### 🚨 Panic Button
+Triple-tap to instantly delete all messages and data. Everything gone in less than 0.2 seconds!
 
-### MeshService
+### 💬 Group Channels
+Create chat rooms like `#camping-trip` or `#concert-squad`. Only people who join can see the messages!
 
-The main orchestrator for the mesh network.
+---
 
-#### Lifecycle Methods
+## Installation
 
-```javascript
-// Initialize the service
-await mesh.initialize(options);
+### Option A: Expo Projects (Easiest!) 🎯
 
-// Start with a transport
-await mesh.start(transport);
+```bash
+npx expo install react-native-ble-mesh react-native-ble-plx react-native-get-random-values
+```
 
-// Stop the service
-await mesh.stop();
+Add the plugin to your `app.json`:
 
-// Clean up resources
-await mesh.destroy();
+```json
+{
+  "expo": {
+    "plugins": [
+      ["react-native-ble-mesh", {
+        "bluetoothAlwaysPermission": "Chat with nearby friends using Bluetooth"
+      }]
+    ]
+  }
+}
 ```
 
-#### Identity Management
+**That's it! The plugin handles all the permissions for you.** ✅
 
-```javascript
-// Get your identity information
-const identity = mesh.getIdentity();
-// Returns: { publicKey, signingPublicKey, displayName, fingerprint }
+Then build your dev client:
+```bash
+npx expo prebuild
+npx expo run:ios   # or run:android
+```
 
-// Set your display name
-mesh.setDisplayName('Alice');
+### Option B: Bare React Native
 
-// Get your fingerprint for out-of-band verification
-const fingerprint = mesh.getFingerprint();
+```bash
+npm install react-native-ble-mesh react-native-ble-plx react-native-get-random-values
+```
 
-// Export identity for backup
-const exported = mesh.exportIdentity();
+**iOS Setup:**
+```bash
+cd ios && pod install && cd ..
+```
 
-// Import identity from backup
-mesh.importIdentity(exported);
+Add to `ios/YourApp/Info.plist`:
+```xml
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>Chat with nearby friends using Bluetooth</string>
+<key>NSBluetoothPeripheralUsageDescription</key>
+<string>Chat with nearby friends using Bluetooth</string>
+<key>UIBackgroundModes</key>
+<array>
+  <string>bluetooth-central</string>
+  <string>bluetooth-peripheral</string>
+</array>
+```
 
-// Announce identity to network
-mesh.announceIdentity();
+**Android Setup:** Add to `android/app/src/main/AndroidManifest.xml`:
+```xml
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
 ```
 
-#### Peer Management
+### Final Step (Both Options)
 
-```javascript
-// Get all known peers
-const peers = mesh.getPeers();
+Add this as the **very first line** in your app:
 
-// Get a specific peer
-const peer = mesh.getPeer(peerId);
+```javascript
+import 'react-native-get-random-values';
+```
 
-// Initiate secure handshake with a peer
-await mesh.initiateHandshake(peerId);
+### Optional: Extra Speed & Features
 
-// Block a peer
-mesh.blockPeer(peerId);
+```bash
+# Want encryption? Pick one:
+npm install tweetnacl                     # Works everywhere
+npm install react-native-quick-crypto     # Fastest (native)
 
-// Unblock a peer
-mesh.unblockPeer(peerId);
+# Want Wi-Fi Direct for big file transfers?
+npm install react-native-wifi-p2p
 ```
 
-#### Trust Management
+---
+
+## Quick Start Examples
+
+### Example 1: Simple Chat
 
 ```javascript
-// Verify a peer using their fingerprint
-mesh.verifyPeer(peerId, fingerprint);
+import { MeshNetwork } from 'react-native-ble-mesh';
 
-// Remove verification
-mesh.unverifyPeer(peerId);
+const mesh = new MeshNetwork({ nickname: 'YourName' });
+await mesh.start();
 
-// Add to favorites
-mesh.addFavorite(peerId);
+// Send message to everyone
+await mesh.broadcast('Hi everyone!');
 
-// Remove from favorites
-mesh.removeFavorite(peerId);
+// Send private message to one person
+await mesh.sendDirect('friend-id', 'Hey, just for you!');
 
-// Get verified peers
-const verified = mesh.getVerifiedPeers();
+// Receive messages
+mesh.on('messageReceived', ({ from, text }) => {
+  console.log(`${from}: ${text}`);
+});
 
-// Get favorite peers
-const favorites = mesh.getFavoritePeers();
+await mesh.stop();
 ```
 
-#### Power Management
+### Example 2: Send a Photo
 
 ```javascript
-// Available power modes: PERFORMANCE, BALANCED, POWER_SAVER, ULTRA_POWER_SAVER
-mesh.setPowerMode('BALANCED');
+// Send a photo
+await mesh.sendFile('friend-id', {
+  data: imageBytes,
+  name: 'selfie.jpg',
+  mimeType: 'image/jpeg',
+});
 
-// Get current power mode
-const mode = mesh.getPowerMode();
+// Track sending progress
+mesh.on('fileSendProgress', ({ percent }) => {
+  console.log(`${percent}% sent`);
+});
 
-// Enable automatic power adjustment based on battery level
-mesh.setAutoPowerAdjust(true);
+// Receive photos
+mesh.on('fileReceived', ({ from, file }) => {
+  console.log(`Got ${file.name} (${file.size} bytes) from ${from}`);
+  // file.data = the photo bytes
+  // file.mimeType = 'image/jpeg'
+});
 ```
 
-#### Status and Statistics
+### Example 3: Group Channels
 
 ```javascript
-// Get service status
-const status = mesh.getStatus();
-
-// Get current state
-const state = mesh.getState();
-
-// Get detailed statistics
-const stats = mesh.getStats();
+await mesh.joinChannel('#road-trip');
+await mesh.sendToChannel('#road-trip', 'Are we there yet?');
+await mesh.leaveChannel('#road-trip');
 ```
 
-### Events
-
-| Event | Description | Payload |
-|-------|-------------|---------|
-| `peer-discovered` | New peer found | `{ peer }` |
-| `peer-connected` | Connected to peer | `{ peer }` |
-| `peer-disconnected` | Disconnected from peer | `{ peer }` |
-| `peer-secured` | Secure session established | `{ peer }` |
-| `message` | Any message received | `{ message }` |
-| `private-message` | Private message received | `{ message }` |
-| `channel-message` | Channel message received | `{ message }` |
-| `message-delivered` | Message delivery confirmed | `{ messageId, peerId, timestamp }` |
-| `message-failed` | Message delivery failed | `{ messageId, peerId, error }` |
-| `read-receipt` | Read receipt received | `{ messageIds, fromPeerId, timestamp }` |
-| `identity-announced` | Peer announced identity | `{ peerId, fingerprint, nickname }` |
-| `peer-verified` | Peer verification changed | `{ peerId, fingerprint }` |
-| `peer-compromised` | Fingerprint mismatch detected | `{ peerId, expected, actual }` |
-
-## Configuration
-
-### Initialization Options
+### Example 4: Check Connection Quality
 
 ```javascript
-await mesh.initialize({
-  // Display name for this node
-  displayName: 'My Device',
-
-  // Storage adapter (null for in-memory)
-  storage: null,
-
-  // Custom key manager (optional)
-  keyManager: null,
-
-  // Enable compression for messages > 64 bytes
-  compressionEnabled: true,
-
-  // Compression threshold in bytes
-  compressionThreshold: 64,
+// How's my connection to a friend?
+const quality = mesh.getConnectionQuality('friend-id');
+console.log(`Signal: ${quality.level}`);  // excellent, good, fair, poor
+console.log(`Speed: ${quality.latencyMs}ms`);
+
+// Check everyone at once
+const all = mesh.getAllConnectionQuality();
+all.forEach(q => {
+  console.log(`${q.peerId}: ${q.level} (${q.transport})`);
 });
 ```
 
-### Power Modes
-
-| Mode | Scan Interval | Window | Use Case |
-|------|---------------|--------|----------|
-| `PERFORMANCE` | 1s | 800ms | Active foreground use |
-| `BALANCED` | 5s | 2s | Default mode |
-| `POWER_SAVER` | 30s | 5s | Background operation |
-| `ULTRA_POWER_SAVER` | 60s | 5s | Minimal battery drain |
-
-### Message Options
+### Example 5: Save Battery
 
 ```javascript
-// Send with options
-await mesh.sendPrivateMessage(peerId, content, {
-  // Request delivery acknowledgment
-  requiresAck: true,
-
-  // Enable compression
-  compress: true,
-
-  // Maximum hop count (1-15)
-  maxHops: 7,
-
-  // Priority level
-  priority: 'high', // 'normal' | 'high'
+const mesh = new MeshNetwork({
+  nickname: 'Smart',
+  batteryMode: 'auto',  // Adjusts based on your battery level!
 });
 ```
 
-## Security Features
+### Example 6: Emergency Delete
 
-### Cryptographic Primitives
+```javascript
+mesh.enablePanicMode({ trigger: 'triple_tap' });
 
-- **Key Exchange**: X25519 (Curve25519 ECDH)
-- **Signatures**: Ed25519
-- **Encryption**: ChaCha20-Poly1305 AEAD
-- **Hashing**: SHA-256, SHA-512
-- **Key Derivation**: HKDF
+// Or wipe everything right now
+await mesh.wipeAllData();
+// All messages, keys, and data = GONE! 💨
+```
 
-### Noise Protocol XX Handshake
+---
 
-The library implements the Noise XX handshake pattern:
+## Using React Hooks
 
+```javascript
+import { useMesh, useMessages, usePeers } from 'react-native-ble-mesh/hooks';
+import { BLETransport } from 'react-native-ble-mesh';
+
+function ChatScreen() {
+  const { mesh, state, initialize, destroy } = useMesh({ displayName: 'Alex' });
+  const { messages, sendBroadcast } = useMessages(mesh);
+  const { peers, connectedCount } = usePeers(mesh);
+
+  useEffect(() => {
+    initialize(new BLETransport());
+    return () => destroy();
+  }, []);
+
+  if (state !== 'active') return <Text>Starting mesh...</Text>;
+
+  return (
+    <View>
+      <Text>Connected to {connectedCount} people</Text>
+      {messages.map(msg => (
+        <Text key={msg.id}>{msg.senderId}: {msg.content}</Text>
+      ))}
+      <Button title="Say Hi!" onPress={() => sendBroadcast('Hello!')} />
+    </View>
+  );
+}
 ```
--> e
-<- e, ee, s, es
--> s, se
-```
-
-This provides:
-- Mutual authentication
-- Forward secrecy
-- Identity hiding
-
-### Session Security
 
-- **Automatic Rekeying**: Sessions rekey every hour or after 10,000 messages
-- **Replay Protection**: Sliding window algorithm with configurable window size
-- **Nonce Management**: Automatic nonce tracking prevents reuse
+---
 
-### Identity Verification
+## Everything You Can Do
 
-Verify peer identities out-of-band using fingerprints:
+### Starting & Stopping
 
-```javascript
-// Get your fingerprint to share
-const myFingerprint = mesh.getFingerprint();
-// Format: "A1B2 C3D4 E5F6 G7H8 I9J0 K1L2 M3N4 O5P6"
+| Method | What It Does |
+|--------|--------------|
+| `mesh.start()` | Turn on the mesh network |
+| `mesh.stop()` | Turn it off (can restart later) |
+| `mesh.destroy()` | Completely shut down |
 
-// Verify a peer after out-of-band confirmation
-mesh.verifyPeer(peerId, theirFingerprint);
+### Sending Messages
 
-// Check if a peer is verified
-const peer = mesh.getPeer(peerId);
-console.log('Verified:', peer.verificationStatus === 'verified');
-```
+| Method | What It Does |
+|--------|--------------|
+| `mesh.broadcast('Hi!')` | Send to everyone nearby |
+| `mesh.sendDirect(id, 'Hey')` | Private message to one person |
+| `mesh.sendToChannel('#fun', 'Yo')` | Send to a group |
 
-## Protocol Details
+### Sending Files
 
-### Message Header Format
+| Method | What It Does |
+|--------|--------------|
+| `mesh.sendFile(id, { data, name, mimeType })` | Send a file to someone |
+| `mesh.getActiveTransfers()` | See files being sent/received |
+| `mesh.cancelTransfer(id)` | Cancel a file transfer |
 
-The library uses an optimized 24-32 byte header:
+### Connection Quality
 
-| Field | Size | Description |
-|-------|------|-------------|
-| version | 1 | Protocol version |
-| type | 1 | Message type |
-| flags | 1 | Feature flags |
-| ttl | 1 | Hop count + max hops |
-| timestamp | 8 | Unix timestamp (ms) |
-| payloadLength | 2 | Payload size |
-| fragmentIndex | 1 | Fragment index |
-| fragmentTotal | 1 | Total fragments |
-| senderId | 8 | Truncated peer ID |
-| recipientId | 8 | (Optional) Recipient ID |
+| Method | What It Does |
+|--------|--------------|
+| `mesh.getConnectionQuality(id)` | Signal quality for one person |
+| `mesh.getAllConnectionQuality()` | Signal quality for everyone |
 
-### Message Types
+### Channels (Group Chats)
 
-| Category | Types |
-|----------|-------|
-| Data | TEXT, TEXT_ACK, BINARY, BINARY_ACK |
-| Handshake | HANDSHAKE_INIT, HANDSHAKE_RESPONSE, HANDSHAKE_FINAL |
-| Discovery | PEER_ANNOUNCE, PEER_REQUEST, PEER_RESPONSE, IDENTITY_ANNOUNCE |
-| Channels | CHANNEL_JOIN, CHANNEL_LEAVE, CHANNEL_MESSAGE |
-| Private | PRIVATE_MESSAGE, PRIVATE_ACK, READ_RECEIPT |
-| Control | HEARTBEAT, PING, PONG |
-| Fragments | FRAGMENT_START, FRAGMENT_CONTINUE, FRAGMENT_END |
+| Method | What It Does |
+|--------|--------------|
+| `mesh.joinChannel('#name')` | Join a group |
+| `mesh.leaveChannel('#name')` | Leave a group |
+| `mesh.getChannels()` | See your groups |
 
-## Error Handling
+### People
 
-The library provides detailed error classes:
+| Method | What It Does |
+|--------|--------------|
+| `mesh.getPeers()` | See everyone nearby |
+| `mesh.getConnectedPeers()` | See who's connected |
+| `mesh.blockPeer(id)` | Block someone |
+| `mesh.unblockPeer(id)` | Unblock someone |
 
-```javascript
-const {
-  MeshError,
-  CryptoError,
-  ConnectionError,
-  HandshakeError,
-  MessageError,
-  FragmentError,
-  TrustError,
-  RetryError
-} = require('react-native-ble-mesh/errors');
-
-mesh.on('error', (error) => {
-  if (error instanceof CryptoError) {
-    console.error('Crypto error:', error.code, error.message);
-  } else if (error instanceof ConnectionError) {
-    console.error('Connection error:', error.code, error.message);
-  } else if (error instanceof TrustError) {
-    console.error('Trust error:', error.code, error.message);
-  }
+### Safety
 
-  // All errors have these properties
-  console.log('Error code:', error.code);
-  console.log('Category:', error.category);
-  console.log('Recoverable:', error.recoverable);
-  console.log('Details:', error.details);
-});
-```
+| Method | What It Does |
+|--------|--------------|
+| `mesh.enablePanicMode()` | Enable emergency wipe |
+| `mesh.wipeAllData()` | Delete everything NOW |
 
-### Error Codes
+### Network Info
 
-| Category | Codes |
-|----------|-------|
-| Crypto | E_CRYPTO_001 - E_CRYPTO_006 |
-| Connection | E_CONN_001 - E_CONN_003 |
-| Handshake | E_HAND_001 - E_HAND_003 |
-| Message | E_MSG_001 - E_MSG_004 |
-| Fragment | E_FRAG_001 - E_FRAG_004 |
-| Trust | E_TRUST_001 - E_TRUST_004 |
-| Retry | E_RETRY_001 - E_RETRY_003 |
+| Method | What It Does |
+|--------|--------------|
+| `mesh.getStatus()` | Current status |
+| `mesh.getNetworkHealth()` | How good is the network? |
+| `mesh.getBatteryMode()` | Current battery mode |
+| `mesh.setBatteryMode('low')` | Change battery mode |
 
-## Platform Support
+---
 
-### React Native
+## Events (When Things Happen)
 
 ```javascript
-const { MeshService, BLETransport } = require('react-native-ble-mesh');
-const { RNBLEAdapter } = require('react-native-ble-mesh/adapters');
-
-const transport = new BLETransport({
-  adapter: new RNBLEAdapter(),
-});
+// Messages
+mesh.on('messageReceived', ({ from, text, type }) => { });
+mesh.on('directMessage', ({ from, text }) => { });
+mesh.on('channelMessage', ({ channel, from, text }) => { });
+mesh.on('messageDelivered', ({ messageId }) => { });
+
+// Files
+mesh.on('fileReceived', ({ from, file }) => { });
+mesh.on('fileSendProgress', ({ name, percent }) => { });
+mesh.on('fileReceiveProgress', ({ name, percent }) => { });
+mesh.on('fileTransferFailed', ({ transferId, reason }) => { });
+
+// People
+mesh.on('peerDiscovered', (peer) => { });
+mesh.on('peerConnected', (peer) => { });
+mesh.on('peerDisconnected', (peer) => { });
+
+// Connection Quality
+mesh.on('connectionQualityChanged', ({ peerId, level, score }) => { });
+
+// Network
+mesh.on('started', () => { });
+mesh.on('stopped', () => { });
+mesh.on('networkHealthChanged', (info) => { });
+mesh.on('error', (error) => { });
+
+// Offline delivery
+mesh.on('messageCached', ({ peerId, text }) => { });
+mesh.on('cachedMessagesDelivered', ({ peerId, delivered }) => { });
+
+// Safety
+mesh.on('dataWiped', (result) => { });
 ```
 
-**Required permissions (iOS):**
-- NSBluetoothAlwaysUsageDescription
-- NSBluetoothPeripheralUsageDescription
+---
 
-**Required permissions (Android):**
-- BLUETOOTH
-- BLUETOOTH_ADMIN
-- BLUETOOTH_SCAN
-- BLUETOOTH_ADVERTISE
-- BLUETOOTH_CONNECT
-- ACCESS_FINE_LOCATION
+## How Secure Is It?
 
-### Node.js
+**Very secure!** Here's what protects your messages:
 
-```javascript
-const { MeshService, BLETransport } = require('react-native-ble-mesh');
-const { NodeBLEAdapter } = require('react-native-ble-mesh/adapters');
+| Feature | What It Means (in Simple Words) |
+|---------|-------------------------------|
+| **Pluggable Encryption** | Choose the strongest lock for your messages |
+| **Key Exchange** | Phones secretly agree on a password that nobody else knows |
+| **Forward Secrecy** | Even if someone steals your keys later, old messages stay secret |
+| **No Permanent IDs** | You can't be tracked — you're just "a phone" |
+| **Panic Wipe** | One tap and everything disappears forever |
 
-const transport = new BLETransport({
-  adapter: new NodeBLEAdapter(),
-});
-```
+---
 
-## Examples
+## iOS Background Mode
 
-### Basic Chat Application
+Want the mesh to keep working when the app is in the background? We've got you covered.
 
-```javascript
-const { MeshService, BLETransport, MemoryStorage } = require('react-native-ble-mesh');
-
-class ChatApp {
-  constructor() {
-    this.mesh = new MeshService();
-    this.messages = [];
-  }
+**Short version:** Add `bluetooth-central` and `bluetooth-peripheral` to your background modes (the Expo plugin does this automatically).
 
-  async start(displayName) {
-    await this.mesh.initialize({
-      displayName,
-      storage: new MemoryStorage(),
-    });
+**Detailed version:** See our [iOS Background BLE Guide](docs/IOS-BACKGROUND-BLE.md) — covers all the limitations, workarounds, and known bugs.
 
-    const transport = new BLETransport();
-    await this.mesh.start(transport);
+---
 
-    this.setupEventHandlers();
-    console.log('Chat started! Your fingerprint:', this.mesh.getFingerprint());
-  }
+## Frequently Asked Questions
 
-  setupEventHandlers() {
-    this.mesh.on('peer-discovered', (peer) => {
-      console.log(`[+] Discovered: ${peer.getDisplayName()}`);
-    });
+**How far can messages travel?**
+One hop: ~30 meters (100 feet). With 7 hops through other phones: 300+ meters!
 
-    this.mesh.on('private-message', (message) => {
-      this.messages.push(message);
-      console.log(`[${message.senderId.slice(0, 8)}]: ${message.content}`);
-    });
+**Does it work if Bluetooth is off?**
+No, Bluetooth must be on. But you don't need WiFi or cell service!
 
-    this.mesh.on('message-delivered', ({ messageId }) => {
-      console.log(`[OK] Delivered: ${messageId.slice(0, 8)}`);
-    });
-  }
+**Can someone read my private messages?**
+Nope! They're encrypted. Only you and your friend have the keys.
 
-  async sendMessage(peerId, content) {
-    return await this.mesh.sendPrivateMessage(peerId, content, {
-      requiresAck: true,
-    });
-  }
+**How big of a file can I send?**
+Up to 10MB by default (configurable). Big files automatically use Wi-Fi Direct if available.
 
-  getPeers() {
-    return this.mesh.getPeers();
-  }
+**Does it work with Expo?**
+Yes! Just add the plugin to `app.json` and build a dev client.
 
-  verifyPeer(peerId, fingerprint) {
-    this.mesh.verifyPeer(peerId, fingerprint);
-  }
+**Does it drain my battery?**
+It uses some battery (Bluetooth is on), but use `batteryMode: 'auto'` and the library manages it for you.
 
-  async stop() {
-    await this.mesh.stop();
-    await this.mesh.destroy();
-  }
-}
+**Does it work in the background?**
+On iOS, it works with some limitations (scanning is slower). On Android, it works fully. See [iOS Background BLE Guide](docs/IOS-BACKGROUND-BLE.md).
 
-// Usage
-const chat = new ChatApp();
-await chat.start('Alice');
+---
 
-// List discovered peers
-const peers = chat.getPeers();
-peers.forEach(p => console.log(p.id, p.getDisplayName()));
+## Use Cases
 
-// Send a message
-await chat.sendMessage(peers[0].id, 'Hello!');
-```
+- 🎵 **Concerts & Festivals** — Text friends when cell towers are overloaded
+- ⛺ **Camping & Hiking** — Stay connected in the wilderness
+- 🆘 **Emergencies** — Communicate during power outages or disasters
+- ✊ **Protests & Events** — When networks are restricted
+- 🎮 **Gaming** — Local multiplayer without internet
+- 🏫 **Schools** — Classroom activities without WiFi
+- 📸 **Photo Sharing** — Share pictures at events without data
 
-### Multi-Hop Messaging
+---
 
-```javascript
-// Messages automatically route through multiple hops
-const messageId = await mesh.sendPrivateMessage(distantPeerId, 'Hello distant peer!', {
-  maxHops: 10, // Allow up to 10 hops
-  requiresAck: true,
-});
+## Project Structure
 
-// Track routing statistics
-const stats = mesh.getStats();
-console.log('Messages relayed:', stats.messagesRelayed);
-console.log('Average hop count:', stats.averageHopCount);
 ```
-
-### Secure File Transfer
-
-```javascript
-const fs = require('fs');
-const path = require('path');
-
-async function sendFile(mesh, peerId, filePath) {
-  const fileData = fs.readFileSync(filePath);
-  const fileName = path.basename(filePath);
-
-  // The library automatically handles:
-  // - Compression for large payloads
-  // - Fragmentation for BLE MTU limits
-  // - Encryption with peer's session key
-  // - Automatic retry on failure
-
-  const messageId = await mesh.sendPrivateMessage(peerId, {
-    type: 'file',
-    name: fileName,
-    data: fileData.toString('base64'),
-    size: fileData.length,
-  }, {
-    compress: true,
-    requiresAck: true,
-  });
-
-  console.log('File transfer initiated:', messageId);
-}
+react-native-ble-mesh/
+├── src/
+│   ├── index.js              # Main entry point
+│   ├── MeshNetwork.js        # High-level API (start here!)
+│   ├── crypto/               # Pluggable encryption providers
+│   ├── mesh/                 # Routing, dedup, connection quality
+│   ├── transport/            # BLE + Wi-Fi Direct + MultiTransport
+│   ├── service/              # Messaging, files, audio, battery, panic
+│   ├── expo/                 # Expo config plugin
+│   └── hooks/                # React hooks
+├── docs/                     # Guides & specs
+├── app.plugin.js             # Expo plugin entry
+└── __tests__/                # 432 tests, 0 failures ✅
 ```
 
-## Testing
-
-Run the test suite:
+---
 
-```bash
-npm test
-```
+## More Documentation
 
-Run with coverage:
+- [Full API Reference](docs/API.md) — Every method explained
+- [React Native Guide](docs/REACT_NATIVE.md) — Platform-specific setup
+- [iOS Background BLE](docs/IOS-BACKGROUND-BLE.md) — Background mode guide
+- [Security Details](docs/SECURITY.md) — How encryption works
+- [Protocol Spec](docs/PROTOCOL.md) — Technical wire format
+- [Optimization Notes](docs/OPTIMIZATION.md) — Performance details
+- [v2.1 Feature Spec](docs/SPEC-v2.1.md) — Architecture decisions
+- [AI/Agent Instructions](docs/prompt-instructions.md) — For AI assistants
 
-```bash
-npm run test:coverage
-```
+---
 
-Run specific test files:
+## Testing
 
 ```bash
-npm test -- __tests__/crypto/sha256.test.js
-npm test -- __tests__/integration/handshake.test.js
+npm test             # Run all 432 tests
+npm run test:coverage  # With coverage report
 ```
 
-## Project Structure
-
-```
-react-native-ble-mesh/
-├── src/
-│   ├── index.js                # Main exports
-│   ├── constants/              # Protocol, BLE, crypto constants
-│   ├── errors/                 # Custom error classes
-│   ├── crypto/                 # Cryptographic implementations
-│   │   ├── noise/              # Noise Protocol (handshake, session)
-│   │   └── keys/               # Key management
-│   ├── protocol/               # Message serialization/deserialization
-│   ├── mesh/                   # Mesh networking logic
-│   │   ├── router/             # Message routing
-│   │   ├── dedup/              # Duplicate detection
-│   │   ├── fragment/           # Message fragmentation
-│   │   └── peer/               # Peer management
-│   ├── transport/              # BLE transport layer
-│   ├── storage/                # Persistence adapters
-│   ├── utils/                  # Utility functions
-│   └── service/                # High-level service orchestration
-├── __tests__/                  # Test files
-├── docs/                       # Documentation
-├── examples/                   # Example applications
-└── package.json
-```
+---
 
 ## Contributing
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Run tests and linting (`npm run validate`)
-4. Commit your changes (`git commit -m 'Add amazing feature'`)
-5. Push to the branch (`git push origin feature/amazing-feature`)
-6. Open a Pull Request
+We love contributions! Here's how:
 
-### Code Style
+1. Fork this repository
+2. Create a branch: `git checkout -b my-feature`
+3. Make your changes
+4. Run tests: `npm test`
+5. Push and create a Pull Request
 
-- Maximum 200 lines per file
-- JSDoc comments on all public APIs
-- ESLint with strict rules
-- 100% test coverage on crypto modules
-- >80% coverage on other modules
+---
 
-## Documentation
+## Credits
 
-- [API Reference](docs/API.md) - Complete API documentation
-- [Architecture](docs/ARCHITECTURE.md) - System design and module structure
-- [Security](docs/SECURITY.md) - Threat model and security properties
-- [Protocol](docs/PROTOCOL.md) - Wire format and message types
+Inspired by [BitChat](https://github.com/nicegram/nicegram-bitchat) — the original decentralized mesh chat.
 
-## License
+Built with:
+- [react-native-ble-plx](https://github.com/Polidea/react-native-ble-plx) — Bluetooth Low Energy
+- [tweetnacl](https://tweetnacl.js.org/) — Encryption
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+---
+
+## License
 
-## Acknowledgments
+MIT License — do whatever you want with it! See [LICENSE](LICENSE) for details.
 
-This project is inspired by [bitchat](https://github.com/permissionlesstech/bitchat).
+---
 
-- [Noise Protocol Framework](https://noiseprotocol.org/) - Cryptographic handshake pattern
-- [react-native-ble-plx](https://github.com/Polidea/react-native-ble-plx) - React Native BLE library
-- [Noble](https://github.com/abandonware/noble) - Node.js BLE library
+<p align="center">
+  <b>Made with ❤️ for a more connected (yet private) world</b>
+  <br><br>
+  If this library helps you, give it a ⭐ on GitHub!
+</p>