@toolkit-p2p/transport-ble

Bluetooth Low Energy (BLE) transport for toolkit-p2p.

Features

• ✅ Web Bluetooth API (Android Chrome 56+, macOS/Linux Chrome 70+)
• ✅ Automatic fragmentation for payloads >MTU
• ✅ Exponential backoff retry on failures
• ✅ Heartbeat keepalive & auto-reconnect
• ✅ Rate limiting (100 pkt/s per peer)
• ⚠️ Not supported on iOS (Safari doesn't expose Web Bluetooth)

Installation

pnpm add @toolkit-p2p/transport-ble @toolkit-p2p/core

Usage

import { bleTransport } from '@toolkit-p2p/transport-ble';
import { createEngine } from '@toolkit-p2p/core';

// Create transport
const transport = bleTransport({ mtu: 20 });

// Client: discover nearby peers
const peers = await transport.discover();
const connection = await transport.connect(peers[0]);

// Send/receive
connection.send(new Uint8Array([1, 2, 3]));
connection.onMessage((payload, from) => {
  console.log('Received:', payload);
});

// Integrate with game engine
const engine = createEngine({
  initialState: { score: 0 },
  reducer: (state, input) => state,
  authority: 'host',
});

Browser Support

| Browser | Platform | Supported | Version | |---------|----------|-----------|---------| | Chrome | Android | ✅ Yes | 56+ | | Chrome | macOS | ✅ Yes | 70+ | | Chrome | Linux | ✅ Yes | 70+ | | Chrome | Windows | ⚠️ Partial | 70+ (experimental) | | Safari | iOS | ❌ No | Not exposed | | Safari | macOS | ❌ No | Not exposed | | Firefox | All | ❌ No | Not implemented |

Configuration

bleTransport({
  mtu: 20,              // Max bytes per packet (default: 20)
  retryMs: 100,         // Base retry delay (default: 100ms)
  serviceUUID: '...',   // Custom service UUID (optional)
  txCharUUID: '...',    // Custom TX char UUID (optional)
  rxCharUUID: '...',    // Custom RX char UUID (optional)
});

Architecture

GATT Service

• Service UUID: a8729501-559d-46d4-967e-15be95e5d108
• TX Characteristic: 5f34567b-2de5-482e-a88a-25569e15a516 (write)
• RX Characteristic: 94d284a3-41a1-4518-9736-bcda10c66cbc (notify)

Packet Format

[seq: u8][len: u8][payload: u8[]]

• seq: Sequence number (for fragmentation)
• len: Payload length
• payload: Data (≤MTU-2 bytes)

Fragmentation

Payloads >MTU are automatically split:

// 200-byte snapshot → 10 fragments (at MTU=20)
send(new Uint8Array(200)); // Automatically fragmented

Reliability

• Heartbeat: 1-byte ping every 5s
• Timeout: Reconnect if no pong in 15s
• Exponential Backoff: 100ms, 200ms, 400ms, ...

Limitations

1. iOS not supported: Safari doesn't expose Web Bluetooth API
   • Workaround: Use QR code / audio fallback (v0.2+)
2. No peripheral mode: Web Bluetooth only supports central (client) role
   • Host must use native app (Android/macOS) to advertise
3. MTU variance: Some devices cap at 23 bytes (design for 20)
4. Android Doze: Background BLE may be throttled (document workaround)

Testing

# Unit tests (mocked Web Bluetooth API)
pnpm test

# Manual test (requires 2 physical devices)
pnpm --filter examples/racer dev

License

MIT © Aaron Rosenthal