# Bluetooth management

Canonical page: https://docs.ovok.com/native-sdk/guide/components/bt-management

The Bluetooth module is the runtime and protocol layer behind BLE discovery and measurement delivery. Its public React entry point is `BTProvider`; its SDK subpath is `@ovok/native/bt-management`.

## Choose an entry point [#choose-an-entry-point]

| Need | API |
| --- | --- |
| Start a BLE session | `BTProvider` with a stable `BleManager` and an `acceptedDevices` tuple |
| Respond to discovery and readings | `onDeviceFound`, `onDeviceStatusChanged`, `onConnectionEvent`, `onResult`, and `onError` |
| Ask users to choose among discoveries | `autoConnect`, `onDeviceSelectionRequired`, and `BluetoothDevicePicker` |
| Inspect runtime state in a component | `useNearbyDevices`, `useDeviceConnection`, `useMeasurements`, `useScanControl`, and `useRuntimeEvent` |
| Remember pairings | `usePairedDevices` with app-provided key-value storage |
| Use an SDK protocol | `IntegratedDevices` or an entry from `SUPPORTED_DEVICES` |
| Add a new protocol | `defineCustomDevice` and a custom device declaration |
| Deliver readings while backgrounded | `backgroundSync` configuration and native setup |

## Runtime lifecycle [#runtime-lifecycle]

By default, `BTProvider` requests permissions on mount and starts discovery when `acceptedDevices` is non-empty. Set `gateOnPermission` to keep children from rendering until the automatic request resolves; a denied request then shows the permission fallback. Set `requestPermissionOnMount={false}` to keep the provider mounted but wait for an app-triggered request through `useBluetoothState().requestPermission()`. The manager is destroyed when the provider unmounts or its core configuration changes.

Keep both the `BleManager` and `acceptedDevices` stable. Recreating either during render can restart a session. The provider owns scanning and managed device subscriptions; application code owns the manager object, result persistence, patient association, and application-specific UI.

## Component and API reference [#component-and-api-reference]

- [BTProvider](/native-sdk/guide/components/bt-management/bt-provider/) — session lifecycle and props.
- [BluetoothDevicePicker](/native-sdk/guide/components/bt-management/bluetooth-device-picker/) — chooser for multiple auto-connect candidates.
- [BluetoothRuntimeProvider](/native-sdk/guide/components/bt-management/runtime-provider/) — low-level runtime context primitive.
- [DefaultPermissionFallback](/native-sdk/guide/components/bt-management/default-permission-fallback/) — default settings prompt used by the provider.
- [Provider callbacks](/native-sdk/guide/components/bt-management/bt-provider/) — discovery, status, connection events, results, errors, and permission changes.
- [Runtime hooks](/native-sdk/guide/components/bt-management/hooks/) — access nearby devices, statuses, results, scan control, and pairing storage.
- [Advanced Bluetooth usage](/native-sdk/guide/components/bt-management/advanced-usage/) — direct manager ownership, runtime composition, and BLE fixtures.
- [Device types and protocols](/native-sdk/guide/components/bt-management/device-types/) — built-in keys, decodable profiles, and custom protocol boundaries.
- [Bluetooth services](/native-sdk/guide/components/bt-management/device-services/) — the public session and protocol surface.
- [Supported devices](/native-sdk/guide/components/bt-management/supported-devices/) — catalog definitions and accepted-device entries.
- [Custom devices](/native-sdk/guide/components/bt-management/custom-devices/) — declare a supported GATT and measurement protocol.
- [Types](/native-sdk/guide/components/bt-management/types/) — device, event, error, result, and declaration types.
- [PairingFlow](/native-sdk/guide/components/ui/pairing-flow), [BluetoothStateNotice](/native-sdk/guide/components/ui/bluetooth-state-notice), and [SupportedDevicesCatalogList](/native-sdk/guide/components/ui/supported-devices-catalog-list) — reusable UI integrations from `@ovok/native/ui`.
- [Bluetooth device UI](/native-sdk/guide/components/bt-device/) — device list, row, catalog, and manual components.

For an end-to-end flow, start with the [Bluetooth guide](/native-sdk/guide/modules/bt-management).