Skip to main content

Bluetooth devices

The app owns the BLE manager and the SDK provider owns the scan and managed-device lifecycle for the screen where it is mounted. Use one long-lived manager per flow; creating one during render can cause competing scans and interfere with operating-system restoration.

Connect a built-in device​

import { BleManager } from 'react-native-ble-plx';
import { BTProvider, IntegratedDevices } from '@ovok/native/bt-management';

const bleManager = new BleManager();
const acceptedDevices = [IntegratedDevices.BP2] as const;

export function DeviceScreen() {
  return (
    <BTProvider
      bleManager={bleManager}
      acceptedDevices={acceptedDevices}
      onDeviceFound={async (device) => device.connect()}
      onDeviceStatusChanged={({ deviceData, status }) => {
        updateDeviceStatus(deviceData.name, status);
      }}
      onResult={({ id, deviceData, data }) => {
        saveReading({ id, deviceData, data });
      }}
      onError={({ deviceData, error }) => {
        reportDeviceError(deviceData?.name, error);
      }}
    >
      <DeviceFlow />
    </BTProvider>
  );
}

The host app requests and explains Bluetooth permission through the operating system. The SDK reports discovery, connection status, readings, and errors through provider callbacks.

Discovery lifecycle​

The provider checks permission, waits for Bluetooth to be available, scans for accepted declarations, wraps matches as managed devices, and stops its scan when it unmounts. onResult receives decoded measurement data. Use its stable id when making a queued or retried write idempotent.

Pairing, battery, and history-transfer details arrive as connection events; they are not additional device-status values. Derive any richer screen state in the host app.

Device catalog and custom declarations​

Use SUPPORTED_DEVICES to show the catalog and its localized labels, images, credits, measurement types, and ready-to-use declarations. Use SUPPORTED_ACCEPTED_DEVICES when the app intentionally accepts every catalog declaration. A display entry itself is not an acceptedDevices value.

For a supported peripheral that is not in the catalog, the Bluetooth module exposes defineCustomDevice and types for its name matcher, services, fields, frames, and commands. Keep declaration IDs unique and stable, and validate the protocol against the actual device before shipping it.

Permissions and background scans​

Bluetooth permissions and background modes are configured at native build time. Declare only the capabilities the app needs, rebuild after changing native configuration, and test on physical devices. Background scanning is subject to iOS and Android scheduling and radio behavior; it is not a guarantee of continuous execution. See background work for durable result delivery and platform constraints.