Browser support

The web package uses the Web Bluetooth API to connect to BLE devices. Support and requirements differ by browser and environment. The underlying standard is maintained by the W3C Web Bluetooth Community Group; see the Web Bluetooth specification (GitHub) for the spec, use cases, and implementation status.

Supported environments

Environment	Support
Chrome (desktop, Android)	Supported
Edge (Chromium)	Supported
Opera	Supported
Safari (macOS, iOS*)	Not supported (no Web Bluetooth)
Firefox	Not supported (no Web Bluetooth)

* On iOS, Web Bluetooth works in third-party browsers such as Bluefy and WebBLE. For native apps, use Capacitor or React Native.

For per-browser and per-feature details (including Chrome platforms and flags), see the Web Bluetooth implementation status. Check caniuse.com/web-bluetooth for up-to-date support.

Requirements

1. Secure context: The page must be served over HTTPS or from localhost. Mixed content or http:// (except localhost) will block Web Bluetooth.
2. User gesture: Connection must be initiated by a user gesture (e.g. click, tap). Calling device.connect() from a timeout or on load will fail.
3. Bluetooth available: The device must have Bluetooth enabled and the OS must allow the browser to use it.

Mobile and alternative platforms

• Web on mobile: Chrome on Android supports Web Bluetooth. iOS Safari does not support Web Bluetooth; use Capacitor or React Native for iOS.
• Capacitor: Uses @capacitor-community/bluetooth-le and works on iOS and Android. See Platforms: Capacitor.
• React Native: Uses react-native-ble-plx and works on iOS and Android. See Platforms: React Native.
• CLI: Uses webbluetooth (Node) or platform-specific BLE. See Platforms: CLI.

WH-C06 and advertisement scanning

For the Weiheng WH-C06, Chrome’s watchAdvertisements may be required. If the device is not discovered:

1. Paste chrome://flags/#enable-experimental-web-platform-features into the Chrome address bar.
2. Enable Experimental Web Platform features.
3. Restart Chrome.

See the WH-C06 device page for details.

Device debugging

In Chrome (desktop or Android), you can inspect Bluetooth devices and GATT services:

• Chrome Bluetooth Internals - Paste chrome://bluetooth-internals/#devices into the Chrome address bar (links to chrome:// do not open from web pages). There you can view discovered and connected BLE devices, services, and characteristics. Use it to verify that your device advertises correctly and to debug connection or characteristic issues. No user gesture is required; helpful to confirm the device is in range and advertising the expected services.

Troubleshooting

Issue	Check
"User cancelled"	User must click/tap to start connection; avoid calling connect() without a gesture.
"Origin is not allowed"	Use HTTPS or localhost.
"Bluetooth not available"	Enable Bluetooth in OS and ensure the browser has permission.
Device not found	Ensure the device is on, in range, and not connected to another app. For WH-C06, try enabling experimental Web Platform features.

Testing locally

Use localhost (e.g. npm run dev with Vite) so Web Bluetooth works without HTTPS. For testing on a phone, use a tunnel or deploy to a host with HTTPS. See Get started for a minimal example.

For more help, see GitHub Issues or Discord.