11  Operating from the browser: Web Bluetooth console

With the Web Bluetooth API, you can connect to BLE devices from JavaScript in the browser. Use the console below on this page to operate an ESP32-C3 flashed with Step 6 (or Step 5).

WarningRequirements
  • Works in Chrome / Edge (Windows, macOS, Linux, Android). Safari on iPhone / iPad and Firefox are not supported
  • Works only on HTTPS pages (or local localhost)
  • Connecting must be initiated by a user action such as a button click
  • The pairing dialog (passkey entry) is shown by the OS. How it appears differs by OS and version. If it doesn’t work, first pair with HANDSON-C3-XXXX from the OS’s Bluetooth settings, then connect

11.1 Console

Disconnected
Counter (Notify)
—
PING response
—
STATUS: counter / since boot
—
Notify receive interval
—
Receive interval of Counter's Notify [ms] (deviation from 1000 ms is due to the connection interval and browser/OS processing)
Log

TipTry it
  1. Press “Connect” and choose your own HANDSON-C3-XXXX from the list (only devices advertising the service UUID c0a60001-… appear in the list)
  2. The first time you are asked to enter the passkey. Enter the 123456 shown in the serial monitor
  3. The counter increases every second and the receive interval is plotted on the chart. Think about why it isn’t exactly 1000 ms
  4. Press “PING”, “STATUS” and “Undefined” and check the responses. Does the counter in STATUS match the counter in Notify?
  5. In the serial monitor, check the flow of events such as MAIN: STATE_CONNECTED <- EVT_BLE_CMD_PING

11.2 Key points of the code

device = await navigator.bluetooth.requestDevice({ filters: [{ services: [SERVICE] }] });
const server = await device.gatt.connect();
const svc = await server.getPrimaryService(SERVICE);
counterChr = await svc.getCharacteristic(COUNTER);
cmdChr = await svc.getCharacteristic(COMMAND);
counterChr.addEventListener("characteristicvaluechanged", e => onCounter(e.target.value));
await counterChr.startNotifications();
Web Bluetooth What happens in BLE Firmware side
requestDevice({ filters: [{ services }] }) Scans and shows only devices whose advertisement contains that service UUID uuids128 in the advertisement
gatt.connect() Connect BLE_GAP_EVENT_CONNECT
getPrimaryService() / getCharacteristic() Service discovery Definition of gatt_svcs[]
startNotifications() Writes 01 00 to the CCCD. If not paired, an error is returned and the OS starts pairing BLE_GAP_EVENT_SUBSCRIBE, PASSKEY_ACTION
writeValueWithResponse() Write Request BLE_GATT_ACCESS_OP_WRITE_CHR
characteristicvaluechanged Notify received ble_gatts_notify_custom()
  • The received value is a DataView. The true in getUint32(offset, true) specifies little-endian
  • In Web Bluetooth, running two GATT operations at the same time causes an error (GATT operation already in progress). This console chains Promises to serialize them
NoteWhy the receive interval isn’t exactly 1000 ms

The ESP32-C3 queues a Notify exactly every second via esp_timer, but the radio actually transmits at the next connection event (Chapter 2). On the receiving side too, delays are added as it is passed from the OS’s Bluetooth stack → browser → JavaScript. With a 30 ms connection interval, a variation of about ±30 ms occurs.