@eventmsg/transport-webble

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

Installation

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

Browser CDN Usage

Use directly in browser via CDN without npm:

<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

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

// 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

// 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

// Arm the wait before sending so a fast response can't arrive
// before the listener is registered
const startTime = Date.now();
const [pong] = await Promise.all([
  eventMsg.waitFor('pong', {
    timeout: 5000,
    filter: (meta) => meta.senderId === 1
  }),
  eventMsg.send('ping', { timestamp: startTime }, { receiverId: 1 })
]);

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

Connection Management

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

// 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