@eventmsg/transport-webble/README.md

EventMsgV3 Web Bluetooth transport for browser-based communication with ESP32 devices

# @eventmsg/transport-webble

[![npm](https://img.shields.io/npm/v/@eventmsg/transport-webble)](https://www.npmjs.com/package/@eventmsg/transport-webble)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/npm/l/@eventmsg/transport-webble)](LICENSE)

Web Bluetooth transport for EventMsgV3 - Enable reliable messaging between web browsers and ESP32 devices.

## Installation

```bash
npm install @eventmsg/core @eventmsg/transport-webble
```

### Browser CDN Usage

Use directly in browser via CDN without npm:

```html
<script type="importmap">
{
  "imports": {
    "@eventmsg/core": "https://cdn.jsdelivr.net/npm/@eventmsg/core@latest",
    "@eventmsg/transport-webble": "https://cdn.jsdelivr.net/npm/@eventmsg/transport-webble@latest"
  }
}
</script>
<script type="module">
  import { EventMsg } from '@eventmsg/core';
  import { WebBLETransport, createNordicUARTConfig } from '@eventmsg/transport-webble';
  // Use same API as npm version
</script>
```

## Usage

### Quick Start

```typescript
import { EventMsg } from '@eventmsg/core';
import { WebBLETransport, createNordicUARTConfig } from '@eventmsg/transport-webble';

// Create transport with Nordic UART Service
const config = createNordicUARTConfig(0, 0); // localAddress=0, groupAddress=0
const transport = new WebBLETransport(config);
const eventMsg = new EventMsg({ transport });

// Connect and send messages
await eventMsg.connect();
await eventMsg.send('hello', 'Hello ESP32!', { receiverId: 1 });

// Listen for responses
eventMsg.onMessage('response', (data, metadata) => {
  console.log(`Response from device ${metadata.senderId}:`, data);
});
```

### Browser Support

**Supported:** Chrome 56+, Edge 79+, Opera 43+  
**Required:** HTTPS (or localhost for development)

### Configuration

```typescript
// Basic setup
const config = createNordicUARTConfig(localAddress, groupAddress);

// Custom configuration
const config: WebBLETransportConfig = {
  localAddress: 0,
  groupAddress: 0,
  service: {
    uuid: '6e400001-b5a3-f393-e0a9-e50e24dcca9e',
    txCharacteristic: '6e400002-b5a3-f393-e0a9-e50e24dcca9e',
    rxCharacteristic: '6e400003-b5a3-f393-e0a9-e50e24dcca9e'
  },
  connection: {
    timeout: 10000,
    mtu: 20,
    reconnectAttempts: 3
  }
};
```

### Examples

#### Send Different Message Types

```typescript
// String message
await eventMsg.send('text', 'Hello ESP32!', { receiverId: 1 });

// JSON data
await eventMsg.send('sensor_data', { temperature: 25.5 }, { receiverId: 1 });

// Broadcast to all devices
await eventMsg.send('announcement', 'System update', { 
  receiverId: 255, 
  receiverGroupId: 255 
});
```

#### Ping/Pong Pattern

```typescript
const startTime = Date.now();
await eventMsg.send('ping', { timestamp: startTime }, { receiverId: 1 });

const pong = await eventMsg.waitFor('pong', {
  timeout: 5000,
  filter: (meta) => meta.senderId === 1
});

console.log(`RTT: ${Date.now() - startTime}ms`);
```

#### Connection Management

```typescript
eventMsg.on('connect', () => console.log('Connected'));
eventMsg.on('disconnect', () => console.log('Disconnected'));
eventMsg.on('error', (error) => console.error('Error:', error.message));
```

## Troubleshooting

### Common Issues

**"Web Bluetooth not supported"**
- Use Chrome, Edge, or Opera browser
- Ensure `navigator.bluetooth` is available

**"User cancelled device selection"**
- User must select a device from browser dialog
- Ensure user gesture triggers connection

**"No devices found"**
- ESP32 must be powered and advertising
- Check ESP32 firmware includes Nordic UART Service
- Verify device is within Bluetooth range

**"GATT Server disconnected"**
- Check device power and proximity
- Implement automatic reconnection
- Ensure messages are under MTU limit

**"Service not found"**
- Verify ESP32 firmware implements Nordic UART Service
- Check service UUID matches configuration
- Ensure service is properly advertised

### Debug Tips

```typescript
// Enable debug logging
const eventMsg = new EventMsg({ transport, debug: true });

// Monitor connection events
eventMsg.on('connect', () => console.log('Connected'));
eventMsg.on('disconnect', () => console.log('Disconnected'));
eventMsg.on('error', (error) => console.error('Error:', error));

// Check browser support
if (!navigator.bluetooth) {
  console.error('Web Bluetooth not supported');
}
```

### ESP32 Requirements

Your ESP32 must implement Nordic UART Service with these UUIDs:
- **Service:** `6e400001-b5a3-f393-e0a9-e50e24dcca9e`
- **RX Characteristic:** `6e400002-b5a3-f393-e0a9-e50e24dcca9e`
- **TX Characteristic:** `6e400003-b5a3-f393-e0a9-e50e24dcca9e`

---