use-bluetooth

Connect to Bluetooth Low Energy devices with the Web Bluetooth API.


Package	`@vizejs/composable/use-bluetooth`
Own the source	`vize lib pull composable:use-bluetooth`
Runtime exports	`useBluetooth`
Gzip budget	2560 B

Usage

import { useBluetooth } from "@vizejs/composable/use-bluetooth";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useBluetooth`	system	experimental	deterministic-fallback	caller-managed	reactive-scope, returned-value	web, desktop	`window`	`tryOnScopeDispose`

API

`useBluetooth`

Connect to Bluetooth Low Energy devices with the Web Bluetooth API. requestDevice() prompts for a device, connect() connects its GATT server, and read / write / notify address characteristics by service and characteristic UUID. connected follows gattserverdisconnected and available follows availabilitychanged. Failures land in error. Notifications are stopped and the server disconnected when the owning reactive scope stops; outside a scope call disconnect(). Server rendering: supported, available and connected are false and nothing is queried. Inside a component the host is resolved after mounting, so hydration renders this server state first.

function useBluetooth(options: UseBluetoothOptions = {}): BluetoothControls

const ble = useBluetooth({ requestOptions: { filters: [{ services: ["heart_rate"] }] } });
await ble.requestDevice();
await ble.connect();
await ble.notify("heart_rate", "heart_rate_measurement", (value) => show(value.getUint8(1)));

Types

`BluetoothDeviceFilter`

Scan filter for requestDevice.

Member	Type	Description
`services`?	`readonly BluetoothUUIDLike[]`	Services the device must advertise.
`name`?	`string`	Exact device name.
`namePrefix`?	`string`	Device name prefix.

`BluetoothCharacteristicLike`

Minimal BluetoothRemoteGATTCharacteristic used by useBluetooth.

Member	Type	Description
`value`?	`DataView \| null \| undefined`	Last read or notified value.
`readValue`	`() => Promise<DataView>`	Read the value.
`writeValueWithResponse`	`(value: BufferSource) => Promise<void>`	Write and wait for the device's acknowledgement.
`writeValueWithoutResponse`	`(value: BufferSource) => Promise<void>`	Write without acknowledgement.
`startNotifications`	`() => Promise<unknown>`	Start `characteristicvaluechanged` notifications.
`stopNotifications`	`() => Promise<unknown>`	Stop notifications.

`BluetoothServiceLike`

Minimal BluetoothRemoteGATTService.

Member	Type	Description
`getCharacteristic`	`(characteristic: BluetoothUUIDLike) => Promise<BluetoothCharacteristicLike>`	Look up a characteristic.

`BluetoothGATTServerLike`

Minimal BluetoothRemoteGATTServer.

Member	Type	Description
`connected`	`boolean`	Whether the server is connected.
`connect`	`() => Promise<unknown>`	Connect to the server.
`disconnect`	`() => void`	Disconnect from the server.
`getPrimaryService`	`(service: BluetoothUUIDLike) => Promise<BluetoothServiceLike>`	Look up a primary service.

`BluetoothDeviceLike`

Minimal BluetoothDevice used by useBluetooth.

Member	Type	Description
`id`	`string`	Opaque device identifier.
`name`?	`string \| undefined`	Advertised name.
`gatt`?	`BluetoothGATTServerLike \| undefined`	GATT server, when the device supports GATT.

`BluetoothHost`

navigator.bluetooth-like capability used by useBluetooth.

Member	Type	Description
`getAvailability`	`() => Promise<boolean>`	Whether a Bluetooth adapter is available.
`requestDevice`	`(options: BluetoothRequestOptions) => Promise<BluetoothDeviceLike>`	Prompt the user for a device.

`UseBluetoothOptions`

Options for useBluetooth.

Member	Type	Description
`host`?	`MaybeRefOrGetter<BluetoothHost \| null \| undefined>`	`navigator.bluetooth`-like capability.
`requestOptions`?	`BluetoothRequestOptions`	Default options for `requestDevice()`.

`BluetoothControls`

Reactive state and actions returned by useBluetooth.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether Web Bluetooth is available.
`available`	`Readonly<Ref<boolean>>`	Whether an adapter is available, following `availabilitychanged`.
`device`	`Readonly<ShallowRef<BluetoothDeviceLike \| undefined>>`	Most recently chosen device.
`connected`	`Readonly<Ref<boolean>>`	Whether the device's GATT server is connected.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure.
`requestDevice`	`( options?: BluetoothRequestOptions, ) => Promise<BluetoothDeviceLike \| undefined>`	Prompt the user for a device (requires user activation). Disconnects the previous device.
`connect`	`() => Promise<boolean>`	Connect to the device's GATT server.
`disconnect`	`() => void`	Stop notifications and disconnect the GATT server. Idempotent.
`read`	`( service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike, ) => Promise<DataView \| undefined>`	Read a characteristic.
`write`	`( service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike, value: BufferSource, options?: { readonly withoutResponse?: boolean }, ) => Promise<boolean>`	Write a characteristic, with a response unless `withoutResponse`.
`notify`	`( service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike, listener: (value: DataView) => void, ) => Promise<BluetoothNotificationStop \| undefined>`	Subscribe to characteristic notifications.