Bluetooth
Bluetooth capabilities allow your agent to discover, connect to, and read from or write to nearby BLE (Bluetooth Low Energy) devices.
If your app needs to connect to heart-rate straps, controllers, peripheral sensors, or other BLE hardware, this is a good place to start.
Use Cases
- Discover nearby BLE devices
- Connect to peripherals and read from or write to GATT services and characteristics
- Subscribe to device notifications and continuously receive status updates
Basic Usage
Use navigator.bluetooth to request a device, then connect to the device and read its services:
const device = await navigator.bluetooth.requestDevice({
filters: [{ services: ['0000180d-0000-1000-8000-00805f9b34fb'] }],
optionalServices: ['0000180f-0000-1000-8000-00805f9b34fb'],
});
const server = await device.gatt.connect();
const service = await server.getPrimaryService('0000180d-0000-1000-8000-00805f9b34fb');
const characteristic = await service.getCharacteristic('00002a37-0000-1000-8000-00805f9b34fb');
await characteristic.startNotifications();
characteristic.addEventListener('characteristicvaluechanged', () => {
console.log(characteristic.value);
});
Scan for Devices
If you need to keep discovering nearby devices, you can use scan mode:
const scan = await navigator.bluetooth.scanDevices({
filters: [{ services: ['heart_rate'] }],
});
scan.onDeviceFound((event) => {
console.log('Device found:', event.device.id, event.device.name);
});
// Stop when scanning is no longer needed.
scan.stop();
Best Practices
- Prefer filtering by service UUID or device name to reduce irrelevant scan results.
- After connecting, confirm that the required services and characteristics exist before starting the read/write flow.
- Prefer notifications over polling for continuously updated data.
- Disconnect promptly when leaving the page or when the connection is no longer needed.
Notes
- The current interface must allow user interaction when searching for, selecting, or initially connecting to a nearby device.
- When calls such as
connect()orrequestDevice()fail, distinguish between states such as "unavailable", "no permission", and "connection failed". - After a notification event fires,
characteristic.valueis updated to the latest cached value.
Continue Reading
- IMU: See motion and posture sensor capabilities on the device.
- Bluetooth (API Reference): See the complete Bluetooth API reference.