# @ovok/native/bluetooth

Canonical page: https://docs.ovok.com/native-sdk/reference/bluetooth

Bluetooth: one `Bluetooth` entry point, one `Device` handle per paired device whose actions all run on the same
link, and React hooks over both. Import from `@ovok/native/bluetooth`.

## Classes [#classes]

### Bluetooth [#bluetooth]

The one entry point: the catalog, discovery, pairing, and a handle per paired device.

#### Constructors [#constructors]

##### Constructor [#constructor]

```ts
new Bluetooth(options): Bluetooth;
```

###### Parameters [#parameters]

| Parameter | Type |
| ------ | ------ |
| `options` | [`BluetoothOptions`](#bluetoothoptions) |

###### Returns [#returns]

[`Bluetooth`](#bluetooth)

#### Methods [#methods]

##### adapter() [#adapter]

```ts
adapter(): AdapterSnapshot;
```

The radio state and permission as last reported.

###### Returns [#returns-1]

[`AdapterSnapshot`](#adaptersnapshot)

##### destroy() [#destroy]

```ts
destroy(): Promise<void>;
```

Stops watching the adapter and the app, stops syncing by itself, and disconnects every device.

###### Returns [#returns-2]

`Promise`\<`void`\>

##### device() [#device]

```ts
device(address): Device | undefined;
```

The handle of the device paired at `address`, `undefined` when none is.

###### Parameters [#parameters-1]

| Parameter | Type |
| ------ | ------ |
| `address` | `string` |

###### Returns [#returns-3]

[`Device`](#device-1) \| `undefined`

##### devices() [#devices]

```ts
devices(): readonly Device[];
```

The handle of every paired device.

###### Returns [#returns-4]

readonly [`Device`](#device-1)[]

##### discover() [#discover]

```ts
discover(selector?, __namedParameters?): Discovery;
```

Scans for the devices the selector names; identifies against the whole catalog, then filters.

###### Parameters [#parameters-2]

| Parameter | Type |
| ------ | ------ |
| `selector?` | [`DeviceSelector`](#deviceselector) |
| `__namedParameters?` | [`DiscoverOptions`](#discoveroptions) |

###### Returns [#returns-5]

[`Discovery`](#discovery)

##### forget() [#forget]

```ts
forget(address): Promise<void>;
```

Disconnects a paired device, then removes it from the store and from `devices`.

###### Parameters [#parameters-3]

| Parameter | Type |
| ------ | ------ |
| `address` | `string` |

###### Returns [#returns-6]

`Promise`\<`void`\>

##### openSettings() [#opensettings]

```ts
openSettings(): Promise<void>;
```

Opens the system settings, the only place a `blocked` permission can be granted.

###### Returns [#returns-7]

`Promise`\<`void`\>

##### pair() [#pair]

```ts
pair(found, choice?): Promise<Device>;
```

Pairs a found device and returns its handle, still connected so the first sync needs no reconnect.

###### Parameters [#parameters-4]

| Parameter | Type |
| ------ | ------ |
| `found` | [`Found`](#found-1) |
| `choice?` | \{ `model?`: `string`; \} |
| `choice.model?` | `string` |

###### Returns [#returns-8]

`Promise`\<[`Device`](#device-1)\>

##### pairedSnapshots() [#pairedsnapshots]

```ts
pairedSnapshots(): readonly DeviceSnapshot[];
```

The snapshot of every paired device, replaced whenever one changes.

###### Returns [#returns-9]

readonly [`DeviceSnapshot`](#devicesnapshot-1)[]

##### pinToEnter() [#pintoenter]

```ts
pinToEnter(model): string | null;
```

The PIN to show the user while `model` pairs, because the system prompt asks for it and this platform cannot enter it; `null` otherwise.

###### Parameters [#parameters-5]

| Parameter | Type |
| ------ | ------ |
| `model` | [`DeviceModel`](#devicemodel) |

###### Returns [#returns-10]

`string` \| `null`

##### readings() [#readings]

```ts
readings(): readonly ReceivedReading[];
```

The readings received this session, oldest first, with how each save went.

###### Returns [#returns-11]

readonly [`ReceivedReading`](#receivedreading)[]

##### requestPermission() [#requestpermission]

```ts
requestPermission(): Promise<BluetoothPermission>;
```

Prompts for Bluetooth permission if needed and returns the answer.

###### Returns [#returns-12]

`Promise`\<[`BluetoothPermission`](#bluetoothpermission)\>

##### runnable() [#runnable]

```ts
runnable(model): boolean;
```

Whether this runtime has the protocol and the radio a model needs.

###### Parameters [#parameters-6]

| Parameter | Type |
| ------ | ------ |
| `model` | [`DeviceModel`](#devicemodel) |

###### Returns [#returns-13]

`boolean`

##### subscribeAdapter() [#subscribeadapter]

```ts
subscribeAdapter(listener): () => void;
```

Calls `listener` when the radio state or permission changes; returns the unsubscribe.

###### Parameters [#parameters-7]

| Parameter | Type |
| ------ | ------ |
| `listener` | () => `void` |

###### Returns [#returns-14]

() => `void`

##### subscribeDevices() [#subscribedevices]

```ts
subscribeDevices(listener): () => void;
```

Calls `listener` when a device is paired or forgotten, or a paired one changes; returns the unsubscribe.

###### Parameters [#parameters-8]

| Parameter | Type |
| ------ | ------ |
| `listener` | () => `void` |

###### Returns [#returns-15]

() => `void`

##### subscribeReadings() [#subscribereadings]

```ts
subscribeReadings(listener): () => void;
```

Calls `listener` when a reading arrives or its save state changes; returns the unsubscribe.

###### Parameters [#parameters-9]

| Parameter | Type |
| ------ | ------ |
| `listener` | () => `void` |

###### Returns [#returns-16]

() => `void`

#### Properties [#properties]

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-catalog"></a> `catalog` | `public readonly` | [`Catalog`](#catalog) | The models this runtime knows, whether or not it can run them. |
| <a id="property-ready"></a> `ready` | `public readonly` | `Promise`\<`void`\> | Resolves once the stored paired devices are loaded. |

***

### Catalog [#catalog]

The models the SDK knows, in the order their defaults are chosen.

#### Constructors [#constructors-1]

##### Constructor [#constructor-1]

```ts
new Catalog(all): Catalog;
```

###### Parameters [#parameters-10]

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `all` | readonly [`DeviceModel`](#devicemodel)[] | Every model, in the order their defaults are chosen. |

###### Returns [#returns-17]

[`Catalog`](#catalog)

#### Methods [#methods-1]

##### model() [#model]

```ts
model(id): DeviceModel | undefined;
```

The model with this id, `undefined` when the catalog does not have it.

###### Parameters [#parameters-11]

| Parameter | Type |
| ------ | ------ |
| `id` | `string` |

###### Returns [#returns-18]

[`DeviceModel`](#devicemodel) \| `undefined`

##### models() [#models]

```ts
models(selector?): DeviceModel[];
```

The models the selector names; every model when it names none.

###### Parameters [#parameters-12]

| Parameter | Type |
| ------ | ------ |
| `selector?` | [`DeviceSelector`](#deviceselector) |

###### Returns [#returns-19]

[`DeviceModel`](#devicemodel)[]

##### vendors() [#vendors]

```ts
vendors(): Vendor[];
```

The distinct vendors, sorted by name.

###### Returns [#returns-20]

[`Vendor`](#vendor-2)[]

#### Properties [#properties-1]

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-all"></a> `all` | `public readonly` | readonly [`DeviceModel`](#devicemodel)[] | Every model, in the order their defaults are chosen. |

***

### Device [#device-1]

One paired device: it owns the link, queues every action on it, and reconnects when a press needs it.

#### Accessors [#accessors]

##### address [#address]

###### Get Signature [#get-signature]

```ts
get address(): string;
```

The address its record is stored under.

###### Returns [#returns-21]

`string`

#### Constructors [#constructors-2]

##### Constructor [#constructor-2]

```ts
new Device(
   record,
   deps,
   latestAdvertisement?
): Device;
```

###### Parameters [#parameters-13]

| Parameter | Type |
| ------ | ------ |
| `record` | [`PairedDevice`](#paireddevice) |
| `deps` | `DeviceDeps` |
| `latestAdvertisement?` | `Advertisement` |

###### Returns [#returns-22]

[`Device`](#device-1)

#### Methods [#methods-2]

##### acknowledge() [#acknowledge]

```ts
acknowledge(recordId): Promise<void>;
```

Moves the cursor past a record once the app saved it, so the next sync skips it.

###### Parameters [#parameters-14]

| Parameter | Type |
| ------ | ------ |
| `recordId` | `string` |

###### Returns [#returns-23]

`Promise`\<`void`\>

##### change() [#change]

```ts
change(change): Promise<void>;
```

Changes one of the device's settings, such as a hearing aid's volume.

###### Parameters [#parameters-15]

| Parameter | Type |
| ------ | ------ |
| `change` | [`HearingAidChange`](#hearingaidchange) |

###### Returns [#returns-24]

`Promise`\<`void`\>

##### configure() [#configure]

```ts
configure(settings): Promise<void>;
```

Changes and stores whether it syncs by itself, stays connected in the background, and records what it streams.

###### Parameters [#parameters-16]

| Parameter | Type |
| ------ | ------ |
| `settings` | `Partial`\<[`DeviceSettings`](#devicesettings)\> |

###### Returns [#returns-25]

`Promise`\<`void`\>

##### disconnect() [#disconnect]

```ts
disconnect(): Promise<void>;
```

Stops live, waits for queued actions, then closes the link.

###### Returns [#returns-26]

`Promise`\<`void`\>

##### fetch() [#fetch]

```ts
fetch(recordId): Promise<void>;
```

Delivers one stored record as a `record` event, whatever the cursor says.

###### Parameters [#parameters-17]

| Parameter | Type |
| ------ | ------ |
| `recordId` | `string` |

###### Returns [#returns-27]

`Promise`\<`void`\>

##### pair() [#pair-1]

```ts
pair(): Promise<void>;
```

Opens the link for pairing, so the first sync runs on the same link; a broadcasting device opens none.

###### Returns [#returns-28]

`Promise`\<`void`\>

##### records() [#records]

```ts
records(): Promise<RecordInfo[]>;
```

Lists the records stored on the device, without delivering them.

###### Returns [#returns-29]

`Promise`\<[`RecordInfo`](#recordinfo)[]\>

##### release() [#release]

```ts
release(recordId): void;
```

Forgets a delivered record without saving it, so the next sync delivers it again.

###### Parameters [#parameters-18]

| Parameter | Type |
| ------ | ------ |
| `recordId` | `string` |

###### Returns [#returns-30]

`void`

##### seen() [#seen]

```ts
seen(ad): void;
```

A scan saw the device again; a broadcasting device's result is delivered once, until it sends a different one.

###### Parameters [#parameters-19]

| Parameter | Type |
| ------ | ------ |
| `ad` | `Advertisement` |

###### Returns [#returns-31]

`void`

##### setClock() [#setclock]

```ts
setClock(): Promise<void>;
```

Sets the device's clock to now.

###### Returns [#returns-32]

`Promise`\<`void`\>

##### snapshot() [#snapshot]

```ts
snapshot(): DeviceSnapshot;
```

What a UI shows now; replaced, never changed in place.

###### Returns [#returns-33]

[`DeviceSnapshot`](#devicesnapshot-1)

##### startLive() [#startlive]

```ts
startLive(): Promise<void>;
```

Starts `live` and `waveform` events, which the device also records and saves while it measures with `record` on.

###### Returns [#returns-34]

`Promise`\<`void`\>

##### stopLive() [#stoplive]

```ts
stopLive(): Promise<void>;
```

Stops the stream and waits until the device has stopped sending.

###### Returns [#returns-35]

`Promise`\<`void`\>

##### stored() [#stored]

```ts
stored(): PairedDevice;
```

The device as it is stored.

###### Returns [#returns-36]

[`PairedDevice`](#paireddevice)

##### subscribe() [#subscribe]

```ts
subscribe(listener): () => void;
```

Calls `listener` for every event, state changes included; returns the unsubscribe.

###### Parameters [#parameters-20]

| Parameter | Type |
| ------ | ------ |
| `listener` | (`event`) => `void` |

###### Returns [#returns-37]

() => `void`

##### sync() [#sync]

```ts
sync(): Promise<SyncSummary>;
```

Delivers each record past the cursor as a `record` event; the cursor moves on `acknowledge`.

###### Returns [#returns-38]

`Promise`\<[`SyncSummary`](#syncsummary)\>

***

### DeviceError [#deviceerror]

A failed device action, with a stable code to branch on.

#### Extends [#extends]

- `Error`

#### Constructors [#constructors-3]

##### Constructor [#constructor-3]

```ts
new DeviceError(
   code,
   message,
   cause?
): DeviceError;
```

###### Parameters [#parameters-21]

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `code` | [`DeviceErrorCode`](#deviceerrorcode) | A stable code to branch on. |
| `message` | `string` | - |
| `cause?` | `unknown` | What threw underneath, when there was something. |

###### Returns [#returns-39]

[`DeviceError`](#deviceerror)

###### Overrides [#overrides]

`Error.constructor`

#### Properties [#properties-2]

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="property-cause"></a> `cause?` | `public readonly` | `unknown` | What threw underneath, when there was something. | `Error.cause` |
| <a id="property-code"></a> `code` | `public readonly` | [`DeviceErrorCode`](#deviceerrorcode) | A stable code to branch on. | - |

***

### Discovery [#discovery]

One scan: rows keyed by address and updated in place.

#### Constructors [#constructors-4]

##### Constructor [#constructor-4]

```ts
new Discovery(deps): Discovery;
```

###### Parameters [#parameters-22]

| Parameter | Type |
| ------ | ------ |
| `deps` | `DiscoveryDeps` |

###### Returns [#returns-40]

[`Discovery`](#discovery)

#### Methods [#methods-3]

##### snapshot() [#snapshot-1]

```ts
snapshot(): DiscoverySnapshot;
```

The current rows and scan state, replaced on each change.

###### Returns [#returns-41]

[`DiscoverySnapshot`](#discoverysnapshot-1)

##### start() [#start]

```ts
start(): void;
```

Starts scanning; a `null` filter means no model the selector names can run here, so nothing is scanned.

###### Returns [#returns-42]

`void`

##### stop() [#stop]

```ts
stop(): void;
```

Stops scanning; the rows already found stay in the snapshot.

###### Returns [#returns-43]

`void`

##### subscribe() [#subscribe-1]

```ts
subscribe(listener): () => void;
```

Calls `listener` whenever the snapshot changes; returns the unsubscribe.

###### Parameters [#parameters-23]

| Parameter | Type |
| ------ | ------ |
| `listener` | () => `void` |

###### Returns [#returns-44]

() => `void`

## Functions [#functions]

### androidForegroundService() [#androidforegroundservice]

```ts
function androidForegroundService(text?, __namedParameters?): KeepAlive;
```

Android's connected-device foreground service, which keeps the process alive for background sync; nothing elsewhere.
With an `outbox`, its notification says how many readings wait to upload.

#### Parameters [#parameters-24]

| Parameter | Type |
| ------ | ------ |
| `text?` | [`ForegroundServiceText`](#foregroundservicetext) |
| `__namedParameters?` | [`ForegroundServiceOptions`](#foregroundserviceoptions) |

#### Returns [#returns-45]

[`KeepAlive`](#keepalive)

***

### blePlxCentral() [#bleplxcentral]

```ts
function blePlxCentral(manager): BleCentral;
```

The device's Bluetooth LE radio through `react-native-ble-plx`.

#### Parameters [#parameters-25]

| Parameter | Type |
| ------ | ------ |
| `manager` | `BleManager` |

#### Returns [#returns-46]

[`BleCentral`](#blecentral)

***

### BluetoothProvider() [#bluetoothprovider]

```ts
function BluetoothProvider(__namedParameters): Element;
```

Makes one `Bluetooth` available to the hooks below it.

#### Parameters [#parameters-26]

| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`BluetoothProviderProps`](#bluetoothproviderprops) |

#### Returns [#returns-47]

`Element`

***

### createBluetooth() [#createbluetooth]

```ts
function createBluetooth(__namedParameters): Bluetooth;
```

Bluetooth for a React Native app, over `react-native-ble-plx`, saving readings to Ovok and syncing in the background.
Call it as soon as the app starts: iOS relaunches an app it ended when a kept device connects, and gives it about 10 seconds.

#### Parameters [#parameters-27]

| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`CreateBluetoothOptions`](#createbluetoothoptions) |

#### Returns [#returns-48]

[`Bluetooth`](#bluetooth)

***

### osBluetoothPermissions() [#osbluetoothpermissions]

```ts
function osBluetoothPermissions(): BluetoothPermissions;
```

The platform's Bluetooth permissions through `react-native-permissions`.

#### Returns [#returns-49]

[`BluetoothPermissions`](#bluetoothpermissions)

***

### ovokOutboxWatch() [#ovokoutboxwatch]

```ts
function ovokOutboxWatch(outbox, logger?): OutboxWatch;
```

Watches the signed-in account's Ovok outbox, so the reading log and the notification follow what it sends.

#### Parameters [#parameters-28]

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `outbox` | `WatchedOutbox` | `undefined` |
| `logger?` | [`Logger`](#logger) | `silentLogger` |

#### Returns [#returns-50]

[`OutboxWatch`](#outboxwatch)

***

### ovokReadingSink() [#ovokreadingsink]

```ts
function ovokReadingSink(client, savesFor?): ReadingSink;
```

Saves readings through the Ovok measurements API, queueing them offline: for the signed-in account, or for the
patient `savesFor` names, or holds them when it returns `HOLD`. A reading with a series also saves it; a stored record then removes the live recordings it
replaces, once it is saved.

#### Parameters [#parameters-29]

| Parameter | Type |
| ------ | ------ |
| `client` | [`OvokSinkClient`](#ovoksinkclient) |
| `savesFor?` | [`SavesFor`](#savesfor) |

#### Returns [#returns-51]

[`ReadingSink`](#readingsink)

***

### reactNativeLifecycle() [#reactnativelifecycle]

```ts
function reactNativeLifecycle(): AppLifecycle;
```

The app's foreground and background through React Native's `AppState`.

#### Returns [#returns-52]

[`AppLifecycle`](#applifecycle)

***

### storagePairedDevices() [#storagepaireddevices]

```ts
function storagePairedDevices(storage, key?): PairedDeviceStore;
```

Paired devices as one JSON list under one key; writes run one after another so none is lost.

#### Parameters [#parameters-30]

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `storage` | `OvokStorage` | `undefined` |
| `key?` | `string` | `DEFAULT_KEY` |

#### Returns [#returns-53]

[`PairedDeviceStore`](#paireddevicestore)

***

### useBluetooth() [#usebluetooth]

```ts
function useBluetooth(): Bluetooth;
```

The `Bluetooth` given to the nearest `BluetoothProvider`.

#### Returns [#returns-54]

[`Bluetooth`](#bluetooth)

***

### useBluetoothAdapter() [#usebluetoothadapter]

```ts
function useBluetoothAdapter(): AdapterState;
```

The adapter and the Bluetooth permission, with the ways to change them.

#### Returns [#returns-55]

`AdapterState`

***

### useCatalog() [#usecatalog]

```ts
function useCatalog(selector?): DeviceModel[];
```

The models the selector names; the catalog never changes, so this renders once.

#### Parameters [#parameters-31]

| Parameter | Type |
| ------ | ------ |
| `selector?` | [`DeviceSelector`](#deviceselector) |

#### Returns [#returns-56]

[`DeviceModel`](#devicemodel)[]

***

### useDevice() [#usedevice]

```ts
function useDevice(address): object;
```

A paired device's snapshot and its actions; the actions never rely on `this`, so `onPress={device.sync}` works.

#### Parameters [#parameters-32]

| Parameter | Type |
| ------ | ------ |
| `address` | `string` |

#### Returns [#returns-57]

| Name | Type | Description |
| ------ | ------ | ------ |
| `device` | [`Device`](#device-1) \| `undefined` | The handle to run actions on, `undefined` until it is paired. |
| `snapshot` | [`DeviceSnapshot`](#devicesnapshot-1) \| `undefined` | The device's snapshot, `undefined` until it is paired. |

***

### useDiscovery() [#usediscovery]

```ts
function useDiscovery(selector?, __namedParameters?): DiscoveryState;
```

Scans for the devices the selector names while mounted, unless `auto` is false.
In a browser that scan lists only the devices the site may already use; `start` from a click handler also opens
the browser's chooser.

#### Parameters [#parameters-33]

| Parameter | Type |
| ------ | ------ |
| `selector?` | [`DeviceSelector`](#deviceselector) |
| `__namedParameters?` | \{ `auto?`: `boolean`; \} |
| `__namedParameters.auto?` | `boolean` |

#### Returns [#returns-58]

`DiscoveryState`

***

### useLiveValues() [#uselivevalues]

```ts
function useLiveValues(address): LiveValues | null;
```

The newest live values a device streamed, such as its heart rate; `null` until one arrives.

#### Parameters [#parameters-34]

| Parameter | Type |
| ------ | ------ |
| `address` | `string` |

#### Returns [#returns-59]

[`LiveValues`](#livevalues) \| `null`

***

### usePairedDevices() [#usepaireddevices]

```ts
function usePairedDevices(): readonly DeviceSnapshot[];
```

Every paired device's snapshot.

#### Returns [#returns-60]

readonly [`DeviceSnapshot`](#devicesnapshot-1)[]

***

### useReadings() [#usereadings]

```ts
function useReadings(address?, __namedParameters?): readonly ReceivedReading[];
```

Readings received this session with their save state, newest last; one device's when `address` is given.

#### Parameters [#parameters-35]

| Parameter | Type |
| ------ | ------ |
| `address?` | `string` |
| `__namedParameters?` | \{ `limit?`: `number`; \} |
| `__namedParameters.limit?` | `number` |

#### Returns [#returns-61]

readonly [`ReceivedReading`](#receivedreading)[]

***

### useWaveform() [#usewaveform]

```ts
function useWaveform(address, __namedParameters?): WaveformBuffer;
```

A streamed waveform for a trace; it re-renders at most once per animation frame, never per sample.

#### Parameters [#parameters-36]

| Parameter | Type |
| ------ | ------ |
| `address` | `string` |
| `__namedParameters?` | \{ `seconds?`: `number`; \} |
| `__namedParameters.seconds?` | `number` |

#### Returns [#returns-62]

[`WaveformBuffer`](#waveformbuffer)

## Interfaces [#interfaces]

### AppLifecycle [#applifecycle]

The app's lifecycle as the OS reports it.

#### Methods [#methods-4]

##### watch() [#watch]

```ts
watch(listener): () => void;
```

Reports the visibility now and on each change, until the returned stop is called.

###### Parameters [#parameters-37]

| Parameter | Type |
| ------ | ------ |
| `listener` | (`visibility`) => `void` |

###### Returns [#returns-63]

() => `void`

***

### BleCentral [#blecentral]

The platform's Bluetooth Low Energy radio.

#### Methods [#methods-5]

##### connect() [#connect]

```ts
connect(address): Promise<GattLink>;
```

Opens a GATT connection to the device at `address`.

###### Parameters [#parameters-38]

| Parameter | Type |
| ------ | ------ |
| `address` | `string` |

###### Returns [#returns-64]

`Promise`\<[`GattLink`](#gattlink)\>

##### scan() [#scan]

```ts
scan(filter, handlers): () => void;
```

Reports advertisements until the returned stop is called.

###### Parameters [#parameters-39]

| Parameter | Type |
| ------ | ------ |
| `filter` | [`ScanFilter`](#scanfilter) |
| `handlers` | [`ScanHandlers`](#scanhandlers) |

###### Returns [#returns-65]

() => `void`

##### watchState() [#watchstate]

```ts
watchState(listener): () => void;
```

Reports the adapter state now and on each change, until the returned stop is called.

###### Parameters [#parameters-40]

| Parameter | Type |
| ------ | ------ |
| `listener` | (`state`) => `void` |

###### Returns [#returns-66]

() => `void`

***

### BluetoothPermissions [#bluetoothpermissions]

The OS permission prompts Bluetooth needs.

#### Methods [#methods-6]

##### check() [#check]

```ts
check(): Promise<BluetoothPermission>;
```

The current permission, without prompting.

###### Returns [#returns-67]

`Promise`\<[`BluetoothPermission`](#bluetoothpermission)\>

##### openSettings() [#opensettings-1]

```ts
openSettings(): Promise<void>;
```

Opens the system settings for the app.

###### Returns [#returns-68]

`Promise`\<`void`\>

##### request() [#request]

```ts
request(): Promise<BluetoothPermission>;
```

Prompts if the OS still allows it, then returns the answer.

###### Returns [#returns-69]

`Promise`\<[`BluetoothPermission`](#bluetoothpermission)\>

***

### DeviceProtocol [#deviceprotocol]

One device family's conversation over an open link. `C` is the protocol's own per-link state.
Each optional member is a capability: a protocol without `live` has no live button.

#### Type Parameters [#type-parameters]

| Type Parameter | Default type |
| ------ | ------ |
| <a id="type-parameter-c"></a> `C` | `unknown` |

#### Methods [#methods-7]

##### battery()? [#battery]

```ts
battery?(connection): Promise<Omit<Battery, "at">>;
```

Reads the battery level.

###### Parameters [#parameters-41]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |

###### Returns [#returns-70]

`Promise`\<`Omit`\<[`Battery`](#battery-1), `"at"`\>\>

##### broadcast()? [#broadcast]

```ts
broadcast?(advertisement, receivedAt): HistoryRecord | null;
```

Reads the result a device sends in its advertisement, for a device that opens no link; `null` when it carries none.
The id must stay the same while the device repeats one result, so the result is delivered once.
`receivedAt` is when the advertisement arrived, for a device that sends no time.

###### Parameters [#parameters-42]

| Parameter | Type |
| ------ | ------ |
| `advertisement` | `Advertisement` |
| `receivedAt` | `Date` |

###### Returns [#returns-71]

[`HistoryRecord`](#historyrecord) \| `null`

##### change()? [#change-1]

```ts
change?(connection, change): Promise<void>;
```

Changes one setting; rejects when the device refuses it.

###### Parameters [#parameters-43]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |
| `change` | [`HearingAidChange`](#hearingaidchange) |

###### Returns [#returns-72]

`Promise`\<`void`\>

##### close()? [#close]

```ts
close?(connection): Promise<void>;
```

Lets go of the per-link state when the link ends.

###### Parameters [#parameters-44]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |

###### Returns [#returns-73]

`Promise`\<`void`\>

##### fetch()? [#fetch-1]

```ts
fetch?(connection, recordId): Promise<DecodedReading | null>;
```

`null` for a record the protocol cannot decode, which then counts as handled.

###### Parameters [#parameters-45]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |
| `recordId` | `string` |

###### Returns [#returns-74]

`Promise`\<`DecodedReading` \| `null`\>

##### history()? [#history]

```ts
history?(connection, saved): AsyncIterable<HistoryRecord>;
```

Reads the stored records of a device that sends them in order, oldest first, for a device without `records`.
`saved` holds the ids already saved, newest last, so a protocol that can ask for records after one starts there.

###### Parameters [#parameters-46]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |
| `saved` | readonly `string`[] |

###### Returns [#returns-75]

`AsyncIterable`\<[`HistoryRecord`](#historyrecord)\>

##### identify()? [#identify]

```ts
identify?(connection): Promise<Omit<DeviceIdentity, "at">>;
```

Reads the serial, firmware and hardware the device reports.

###### Parameters [#parameters-47]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |

###### Returns [#returns-76]

`Promise`\<`Omit`\<[`DeviceIdentity`](#deviceidentity), `"at"`\>\>

##### live()? [#live]

```ts
live?(
   connection,
   onFrame,
   signal
): Promise<void>;
```

Streams until `signal` aborts, then stops the device's stream before it resolves.

###### Parameters [#parameters-48]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |
| `onFrame` | (`frame`) => `void` |
| `signal` | `AbortSignal` |

###### Returns [#returns-77]

`Promise`\<`void`\>

##### open() [#open]

```ts
open(context): Promise<C>;
```

Starts the conversation and returns the state every other member receives.

###### Parameters [#parameters-49]

| Parameter | Type |
| ------ | ------ |
| `context` | [`ProtocolContext`](#protocolcontext) |

###### Returns [#returns-78]

`Promise`\<`C`\>

##### pairing()? [#pairing]

```ts
pairing?(connection): Promise<void>;
```

What pairing needs after the connect steps, on a link of its own that closes once it is done.

###### Parameters [#parameters-50]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |

###### Returns [#returns-79]

`Promise`\<`void`\>

##### records()? [#records-1]

```ts
records?(connection): Promise<RecordInfo[]>;
```

Lists the records stored on the device, without reading them.

###### Parameters [#parameters-51]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |

###### Returns [#returns-80]

`Promise`\<[`RecordInfo`](#recordinfo)[]\>

##### setClock()? [#setclock-1]

```ts
setClock?(connection, now): Promise<void>;
```

Sets the device's clock to `now`.

###### Parameters [#parameters-52]

| Parameter | Type |
| ------ | ------ |
| `connection` | `C` |
| `now` | `Date` |

###### Returns [#returns-81]

`Promise`\<`void`\>

#### Properties [#properties-3]

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-id"></a> `id` | `readonly` | `string` | What `DeviceModel.protocol` names. |
| <a id="property-services"></a> `services` | `readonly` | readonly `string`[] | The GATT services it uses, full upper-case UUIDs. |

***

### GattLink [#gattlink]

An open GATT connection: bytes in, bytes out, no knowledge of any device.

#### Methods [#methods-8]

##### close() [#close-1]

```ts
close(): Promise<void>;
```

Ends the connection.

###### Returns [#returns-82]

`Promise`\<`void`\>

##### onDisconnect() [#ondisconnect]

```ts
onDisconnect(listener): () => void;
```

Calls `listener` when the device drops the link; returns the unsubscribe.

###### Parameters [#parameters-53]

| Parameter | Type |
| ------ | ------ |
| `listener` | () => `void` |

###### Returns [#returns-83]

() => `void`

##### read() [#read]

```ts
read(service, characteristic): Promise<Uint8Array<ArrayBufferLike>>;
```

Reads one characteristic once.

###### Parameters [#parameters-54]

| Parameter | Type |
| ------ | ------ |
| `service` | `string` |
| `characteristic` | `string` |

###### Returns [#returns-84]

`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>

##### subscribe() [#subscribe-2]

```ts
subscribe(
   service,
   characteristic,
   onValue
): Promise<() => void>;
```

Calls `onValue` for each notification or indication; resolves to the unsubscribe once it is enabled.

###### Parameters [#parameters-55]

| Parameter | Type |
| ------ | ------ |
| `service` | `string` |
| `characteristic` | `string` |
| `onValue` | (`bytes`) => `void` |

###### Returns [#returns-85]

`Promise`\<() => `void`\>

##### write() [#write]

```ts
write(
   service,
   characteristic,
   bytes
): Promise<void>;
```

Writes with response.

###### Parameters [#parameters-56]

| Parameter | Type |
| ------ | ------ |
| `service` | `string` |
| `characteristic` | `string` |
| `bytes` | `Uint8Array` |

###### Returns [#returns-86]

`Promise`\<`void`\>

##### writeWithoutResponse() [#writewithoutresponse]

```ts
writeWithoutResponse(
   service,
   characteristic,
   bytes
): Promise<void>;
```

Writes without waiting for the device to confirm, for a characteristic that only accepts that.

###### Parameters [#parameters-57]

| Parameter | Type |
| ------ | ------ |
| `service` | `string` |
| `characteristic` | `string` |
| `bytes` | `Uint8Array` |

###### Returns [#returns-87]

`Promise`\<`void`\>

***

### KeepAlive [#keepalive]

Keeps the app process alive while devices are connected or kept connected; Android needs a foreground service.

#### Methods [#methods-9]

##### start() [#start-1]

```ts
start(): Promise<void>;
```

Starts keeping the process alive.

###### Returns [#returns-88]

`Promise`\<`void`\>

##### stop() [#stop-1]

```ts
stop(): Promise<void>;
```

Lets the OS manage the process again.

###### Returns [#returns-89]

`Promise`\<`void`\>

***

### Logger [#logger]

Structured logging: a stable event name and a context; never readings, frames or other health data.

#### Methods [#methods-10]

##### debug() [#debug]

```ts
debug(event, context?): void;
```

Development detail.

###### Parameters [#parameters-58]

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `context?` | `LogContext` |

###### Returns [#returns-90]

`void`

##### error() [#error]

```ts
error(event, context?): void;
```

A failure, possibly recoverable.

###### Parameters [#parameters-59]

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `context?` | `LogContext` |

###### Returns [#returns-91]

`void`

##### info() [#info]

```ts
info(event, context?): void;
```

A success or an expected but notable event.

###### Parameters [#parameters-60]

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `context?` | `LogContext` |

###### Returns [#returns-92]

`void`

##### warn() [#warn]

```ts
warn(event, context?): void;
```

Something unexpected that is not a failure.

###### Parameters [#parameters-61]

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `context?` | `LogContext` |

###### Returns [#returns-93]

`void`

***

### OutboxWatch [#outboxwatch]

The offline queue behind a sink, which the reading log and the foreground notification watch; the sink side provides it.

#### Methods [#methods-11]

##### subscribe() [#subscribe-3]

```ts
subscribe(listener): () => void;
```

Calls `listener` with the view now and after every change, until the returned stop is called.

###### Parameters [#parameters-62]

| Parameter | Type |
| ------ | ------ |
| `listener` | (`view`) => `void` |

###### Returns [#returns-94]

() => `void`

***

### PairedDeviceStore [#paireddevicestore]

Where paired devices are kept between app starts.

#### Methods [#methods-12]

##### load() [#load]

```ts
load(): Promise<PairedDevice[]>;
```

Every stored device.

###### Returns [#returns-95]

`Promise`\<[`PairedDevice`](#paireddevice)[]\>

##### remove() [#remove]

```ts
remove(address): Promise<void>;
```

Deletes the device stored at `address`.

###### Parameters [#parameters-63]

| Parameter | Type |
| ------ | ------ |
| `address` | `string` |

###### Returns [#returns-96]

`Promise`\<`void`\>

##### save() [#save]

```ts
save(device): Promise<void>;
```

Adds the device, or replaces the one with the same address.

###### Parameters [#parameters-64]

| Parameter | Type |
| ------ | ------ |
| `device` | [`PairedDevice`](#paireddevice) |

###### Returns [#returns-97]

`Promise`\<`void`\>

***

### ReadingSink [#readingsink]

Where readings are saved; `device` is the snapshot of the device that took it.

#### Methods [#methods-13]

##### save() [#save-1]

```ts
save(reading, device): Promise<SaveOutcome | SaveReceipt>;
```

Saves one reading, and says which outbox items hold it when it was queued; rejects when it could be neither saved nor queued.

###### Parameters [#parameters-65]

| Parameter | Type |
| ------ | ------ |
| `reading` | [`Reading`](#reading-2) |
| `device` | [`DeviceSnapshot`](#devicesnapshot-1) |

###### Returns [#returns-98]

`Promise`\<[`SaveOutcome`](#saveoutcome) \| [`SaveReceipt`](#savereceipt)\>

## Type Aliases [#type-aliases]

### AdapterSnapshot [#adaptersnapshot]

```ts
type AdapterSnapshot = object;
```

What the radio and the app's permission look like right now.

#### Properties [#properties-4]

##### permission [#permission]

```ts
permission: BluetoothPermission;
```

Whether the app may use it.

##### state [#state]

```ts
state: AdapterState;
```

Whether the radio is usable.

***

### AdapterState [#adapterstate]

```ts
type AdapterState = "unknown" | "on" | "off" | "unauthorized" | "unsupported";
```

The Bluetooth adapter; `unknown` until the platform reports it.

***

### AdvertisementTest [#advertisementtest]

```ts
type AdvertisementTest =
  | {
  kind: "service";
  uuid: string;
}
  | {
  at: number;
  company: number;
  equals: string;
  kind: "manufacturer";
  mask?: string;
}
  | {
  at: number;
  equals: string;
  kind: "serviceData";
  mask?: string;
  uuid: string;
};
```

A test on advertised bytes; `mask` and `equals` are hex.

#### Union Members [#union-members]

##### Type Literal [#type-literal]

```ts
{
  kind: "service";
  uuid: string;
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"service"` | Passes when the advertisement lists a service. |
| `uuid` | `string` | The service UUID, short or full. |

***

##### Type Literal [#type-literal-1]

```ts
{
  at: number;
  company: number;
  equals: string;
  kind: "manufacturer";
  mask?: string;
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `at` | `number` | Byte offset where the comparison starts. |
| `company` | `number` | The company id the data is keyed by. |
| `equals` | `string` | The bytes expected after masking. |
| `kind` | `"manufacturer"` | Reads bytes of the manufacturer data; no such data means no verdict. |
| `mask?` | `string` | ANDed with the bytes before comparing; without it every bit counts. |

***

##### Type Literal [#type-literal-2]

```ts
{
  at: number;
  equals: string;
  kind: "serviceData";
  mask?: string;
  uuid: string;
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `at` | `number` | Byte offset where the comparison starts. |
| `equals` | `string` | The bytes expected after masking. |
| `kind` | `"serviceData"` | Reads bytes of a service's data; no such data means no verdict. |
| `mask?` | `string` | ANDed with the bytes before comparing; without it every bit counts. |
| `uuid` | `string` | The service whose data is read, short or full. |

***

### AppVisibility [#appvisibility]

```ts
type AppVisibility = "foreground" | "background";
```

Whether the app is in front of the user.

***

### Battery [#battery-1]

```ts
type Battery = object;
```

The device's battery as it last reported it.

#### Properties [#properties-5]

##### at [#at]

```ts
at: Date;
```

When the device reported it.

##### charging [#charging]

```ts
charging: boolean | null;
```

Whether it is charging, `null` when the device does not say.

##### percent [#percent]

```ts
percent: number;
```

Charge level from 0 to 100.

***

### BluetoothOptions [#bluetoothoptions]

```ts
type BluetoothOptions = object;
```

The ports and data `Bluetooth` runs on; each platform entry point fills them in.

#### Properties [#properties-6]

##### autoSync? [#autosync]

```ts
autoSync?: boolean;
```

Whether paired devices sync by themselves when seen; turn it off where a scan needs the user, as in a browser.

##### central [#central]

```ts
central: BleCentral;
```

The platform's BLE radio.

##### keepAlive? [#keepalive-1]

```ts
keepAlive?: KeepAlive;
```

Keeps the process alive while devices are connected; nothing extra, by default.

##### lifecycle? [#lifecycle]

```ts
lifecycle?: AppLifecycle;
```

Whether the app is in the foreground; always, by default.

##### logger? [#logger-1]

```ts
logger?: Logger;
```

Where structured events go; silent by default.

##### lostAfterMs? [#lostafterms]

```ts
lostAfterMs?: number;
```

A scan row silent this long is dropped.

##### models [#models-1]

```ts
models: readonly DeviceModel[];
```

The models to identify, usually the built-in ones.

##### now? [#now]

```ts
now?: () => Date;
```

The clock; a test passes a fixed one.

###### Returns [#returns-99]

`Date`

##### outbox? [#outbox]

```ts
outbox?: OutboxWatch;
```

The offline queue behind the sink; the reading log follows it, so a queued reading becomes saved. Nothing waits, by default.

##### pairingAgent? [#pairingagent]

```ts
pairingAgent?: PairingAgent;
```

Enters a model's fixed PIN for the user; without one, the user types it into the system prompt.

##### permissions [#permissions]

```ts
permissions: BluetoothPermissions;
```

The OS permission prompts.

##### protocols [#protocols]

```ts
protocols: readonly DeviceProtocol[];
```

The protocols that talk to them; a model whose protocol is missing is `unsupported` here.

##### sink [#sink]

```ts
sink: ReadingSink;
```

Where readings are saved.

##### store [#store]

```ts
store: PairedDeviceStore;
```

Where paired devices are kept.

***

### BluetoothPermission [#bluetoothpermission]

```ts
type BluetoothPermission = "unknown" | "granted" | "denied" | "blocked";
```

Whether the app may use Bluetooth; `blocked` means only the system settings can grant it.

***

### BluetoothProviderProps [#bluetoothproviderprops]

```ts
type BluetoothProviderProps = object;
```

What `BluetoothProvider` takes.

#### Properties [#properties-7]

##### bluetooth [#bluetooth-1]

```ts
bluetooth: Bluetooth;
```

The instance every hook below it reads.

##### children [#children]

```ts
children: ReactNode;
```

The tree that may use the hooks.

***

### ConnectionState [#connectionstate]

```ts
type ConnectionState =
  | "disconnected"
  | "connecting"
  | "pairing"
  | "connected"
  | "disconnecting";
```

Where the link stands; `pairing` is a new device's first connect.

***

### CreateBluetoothOptions [#createbluetoothoptions]

```ts
type CreateBluetoothOptions = object & Partial<BluetoothOptions>;
```

What `createBluetooth` needs; every port can be swapped, for tests or a custom store or sink.

#### Type Declaration [#type-declaration]

| Name | Type | Description |
| ------ | ------ | ------ |
| `ovok` | [`OvokSinkClient`](#ovoksinkclient) | The Ovok client readings are saved through. |
| `savesFor?` | [`SavesFor`](#savesfor) | The patient readings are saved for when the person measuring isn't the patient, such as a clinician; see `SavesFor`. |
| `storage` | `OvokStorage` | Where paired devices are kept between app starts. |

***

### DeviceAction [#deviceaction]

```ts
type DeviceAction = "sync" | "records" | "fetch" | "live" | "setClock" | "change";
```

A button a device may offer.

***

### DeviceChange [#devicechange]

```ts
type DeviceChange = HearingAidChange;
```

One setting to change on a device, one shape per kind of device.

***

### DeviceErrorCode [#deviceerrorcode]

```ts
type DeviceErrorCode =
  | "unsupported"
  | "adapter-off"
  | "permission"
  | "connect-failed"
  | "timeout"
  | "protocol"
  | "disconnected"
  | "save-failed";
```

Why a device action failed.

***

### DeviceEvent [#deviceevent]

```ts
type DeviceEvent =
  | {
  kind: "state";
  snapshot: DeviceSnapshot;
}
  | {
  kind: "record";
  reading: Reading;
}
  | {
  kind: "reading";
  reading: Reading;
}
  | {
  kind: "live";
  values: LiveValues;
}
  | {
  kind: "waveform";
  waveform: Waveform;
};
```

What a device handle reports: its new snapshot, and readings to save or show.

#### Union Members [#union-members-1]

##### Type Literal [#type-literal-3]

```ts
{
  kind: "state";
  snapshot: DeviceSnapshot;
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"state"` | The snapshot changed. |
| `snapshot` | [`DeviceSnapshot`](#devicesnapshot-1) | The snapshot after the change. |

***

##### Type Literal [#type-literal-4]

```ts
{
  kind: "record";
  reading: Reading;
}
```

Stored on the device; acknowledge it once saved.

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"record"` | A record stored on the device; save it, then `acknowledge` it. |
| `reading` | [`Reading`](#reading-2) | The decoded record; `source.recordId` names it. |

***

##### Type Literal [#type-literal-5]

```ts
{
  kind: "reading";
  reading: Reading;
}
```

A finished measurement the device does not store.

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"reading"` | A finished measurement; save it, there is nothing to acknowledge. |
| `reading` | [`Reading`](#reading-2) | The measurement; `source.recordId` is `null`. |

***

##### Type Literal [#type-literal-6]

```ts
{
  kind: "live";
  values: LiveValues;
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"live"` | Streaming numbers for display only; never saved. |
| `values` | [`LiveValues`](#livevalues) | The numbers one notification carried. |

***

##### Type Literal [#type-literal-7]

```ts
{
  kind: "waveform";
  waveform: Waveform;
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"waveform"` | Streaming samples for display only; never saved. |
| `waveform` | [`Waveform`](#waveform-2) | One batch of samples, as one notification delivered it. |

***

### DeviceFlag [#deviceflag]

```ts
type DeviceFlag = object;
```

A flag exactly as the device reported it; never an interpretation.

#### Properties [#properties-8]

##### code [#code]

```ts
code: string;
```

The flag's name, as the device defines it.

##### raw [#raw]

```ts
raw: number;
```

The raw bits or value the device sent for it.

***

### DeviceIdentity [#deviceidentity]

```ts
type DeviceIdentity = object;
```

What a device reports about itself; a field is `null` when it leaves it out.

#### Properties [#properties-9]

##### at [#at-1]

```ts
at: Date;
```

When it was read.

##### firmware [#firmware]

```ts
firmware: string | null;
```

The firmware version.

##### hardware [#hardware]

```ts
hardware: string | null;
```

The hardware revision.

##### manufacturer [#manufacturer]

```ts
manufacturer: string | null;
```

The maker, as the device names itself.

##### model [#model-1]

```ts
model: string | null;
```

The model, as the device names itself; it may differ from the catalog's name.

##### serial [#serial]

```ts
serial: string | null;
```

The serial number.

***

### DeviceModel [#devicemodel]

```ts
type DeviceModel = object;
```

One device model the SDK knows.

#### Properties [#properties-10]

##### direction [#direction]

```ts
direction: "phone_connects" | "device_connects" | "cloud";
```

Who opens the connection: the phone, the device, or nobody because the data is in a cloud.

##### generic [#generic]

```ts
generic: boolean;
```

No named vendor, such as a generic heart-rate strap; a specific match always wins over it.

##### id [#id]

```ts
id: string;
```

Our model slug, e.g. `viatom/bp2`.

##### imageUrl? [#imageurl]

```ts
imageUrl?: string;
```

Picture of the device, when one is known.

##### links [#links]

```ts
links: readonly LinkOption[];
```

How it is found and read; this SDK runs a model only when one link reads over `ble`.

##### match [#match]

```ts
match: MatchRule;
```

What picks it out of the advertisements.

##### measures [#measures]

```ts
measures: readonly MeasurementType[];
```

What it measures.

##### name [#name]

```ts
name: string;
```

The name people know it by, e.g. `DuoEK-S`.

##### nameCheck [#namecheck]

```ts
nameCheck: "none" | "exact" | "last4";
```

How a paired device is re-checked when it is seen again: no check, the exact name, or its last 4 characters.

##### pin [#pin]

```ts
pin: Pin;
```

What its pairing prompt expects.

##### protocol [#protocol]

```ts
protocol: string;
```

The `DeviceProtocol.id` that talks to it.

##### serialPairing [#serialpairing]

```ts
serialPairing: boolean;
```

Pairing is tied to the serial number of the device.

##### userBound [#userbound]

```ts
userBound: boolean;
```

The device belongs to one user rather than being shared.

##### vendor [#vendor]

```ts
vendor: Vendor;
```

Who sells it.

***

### DeviceSecret [#devicesecret]

```ts
type DeviceSecret = object;
```

A value a device hands over when it pairs and wants back on later links, such as a password; kept with the paired device.

#### Properties [#properties-11]

##### read [#read-1]

```ts
read: () => Promise<string | null>;
```

The kept value, `null` before the device gave one.

###### Returns [#returns-100]

`Promise`\<`string` \| `null`\>

##### write [#write-1]

```ts
write: (value) => Promise<void>;
```

Keeps the value the device gave.

###### Parameters [#parameters-66]

| Parameter | Type |
| ------ | ------ |
| `value` | `string` |

###### Returns [#returns-101]

`Promise`\<`void`\>

***

### DeviceSelector [#deviceselector]

```ts
type DeviceSelector = object;
```

Narrows models: fields combine with AND, the values within one field with OR.

#### Properties [#properties-12]

##### model? [#model-2]

```ts
model?: string | readonly string[];
```

Model ids to keep.

##### type? [#type]

```ts
type?:
  | MeasurementType
  | readonly MeasurementType[];
```

Measurement types to keep; a model that measures any one of them stays.

##### vendor? [#vendor-1]

```ts
vendor?: string | readonly string[];
```

Vendor ids to keep.

***

### DeviceSettings [#devicesettings]

```ts
type DeviceSettings = Pick<PairedDevice, "autoSync" | "keepInBackground" | "record">;
```

The settings a user can change on a paired device.

***

### DeviceSnapshot [#devicesnapshot]

```ts
type DeviceSnapshot = object;
```

Everything a UI shows about one paired device; the same keys for every model.

#### Properties [#properties-13]

##### actions [#actions]

```ts
actions: readonly DeviceAction[];
```

The actions its protocol supports; offer a button for each.

##### activity [#activity]

```ts
activity: Exclude<DeviceAction, "live"> | null;
```

What the action queue is running; live runs beside it.

##### address [#address-1]

```ts
address: string;
```

The address it is paired under; `Bluetooth.device` takes it.

##### autoSync [#autosync-1]

```ts
autoSync: boolean;
```

Whether it syncs by itself when a scan sees it.

##### battery [#battery-2]

```ts
battery: Battery | null;
```

The latest battery report, `null` until the device gives one.

##### connection [#connection]

```ts
connection: ConnectionState;
```

The link's state; actions reconnect on demand, so `disconnected` between presses is normal.

##### deviceState [#devicestate]

```ts
deviceState: DeviceState | null;
```

What the device reports about itself while its stream runs, `null` otherwise.

##### deviceStatus [#devicestatus]

```ts
deviceStatus:
  | {
  at: Date;
  code: string;
}
  | null;
```

The device's own run status, raw; `null` until its protocol reports one.

###### Union Members [#union-members-2]

###### Type Literal [#type-literal-8]

```ts
{
  at: Date;
  code: string;
}
```

###### at [#at-2]

```ts
at: Date;
```

When the device reported it.

###### code [#code-1]

```ts
code: string;
```

The status code exactly as the device sent it.

***

`null`

##### identity [#identity]

```ts
identity: DeviceIdentity | null;
```

The latest serial, firmware and hardware report, `null` until read.

##### keepInBackground [#keepinbackground]

```ts
keepInBackground: boolean;
```

Whether its link stays open while the app is in the background.

##### lastConnectedAt [#lastconnectedat]

```ts
lastConnectedAt: Date | null;
```

When a link last opened.

##### lastError [#lasterror]

```ts
lastError: DeviceError | null;
```

Cleared by the next action that succeeds.

##### lastReadingAt [#lastreadingat]

```ts
lastReadingAt: Date | null;
```

When a record was last delivered.

##### lastSeenAt [#lastseenat]

```ts
lastSeenAt: Date | null;
```

When a scan last saw it this session.

##### lastSyncedAt [#lastsyncedat]

```ts
lastSyncedAt: Date | null;
```

When a sync last succeeded.

##### lastSyncOutcome [#lastsyncoutcome]

```ts
lastSyncOutcome: "success" | "failed" | null;
```

How the latest sync ended, `null` before the first.

##### live [#live-1]

```ts
live: boolean;
```

Whether a live stream is running.

##### measuringSince [#measuringsince]

```ts
measuringSince: Date | null;
```

Since when live frames have kept arriving, so the device is measuring; `null` once they stop for a few seconds.

##### model [#model-3]

```ts
model: object;
```

The catalog model, flattened for display.

###### id [#id-1]

```ts
id: string;
```

The catalog id, e.g. `viatom/bp2`.

###### name [#name-1]

```ts
name: string;
```

The model's display name.

###### vendor [#vendor-2]

```ts
vendor: string;
```

The vendor's display name.

##### name [#name-2]

```ts
name: string;
```

The title to show: the user's, else the advertised name, else the model's.

##### pairedAt [#pairedat]

```ts
pairedAt: Date;
```

When it was first paired.

##### progress [#progress]

```ts
progress:
  | {
  done: number;
  total: number | null;
}
  | null;
```

How far a running sync has got; `null` when none is running.

###### Union Members [#union-members-3]

###### Type Literal [#type-literal-9]

```ts
{
  done: number;
  total: number | null;
}
```

###### done [#done]

```ts
done: number;
```

Records fetched so far.

###### total [#total]

```ts
total: number | null;
```

Records the sync will fetch, `null` when unknown.

***

`null`

##### record [#record]

```ts
record: boolean;
```

Whether what it streams while measuring is recorded and saved, as well as shown.

##### rssi [#rssi]

```ts
rssi: number | null;
```

Signal strength in dBm from that scan.

##### unacknowledged [#unacknowledged]

```ts
unacknowledged: number;
```

Records delivered and not yet acknowledged.

***

### DeviceState [#devicestate-1]

```ts
type DeviceState = HearingAidState;
```

What a device reports about itself beyond its battery and identity, one shape per kind of device.

***

### DiscoverOptions [#discoveroptions]

```ts
type DiscoverOptions = object;
```

How `Bluetooth.discover` scans.

#### Properties [#properties-14]

##### chooser? [#chooser]

```ts
chooser?: boolean;
```

In a browser, whether to open its device chooser, which it allows only from a click; without it the scan lists only the devices the site may already use. Defaults to `true`.

***

### DiscoverySnapshot [#discoverysnapshot]

```ts
type DiscoverySnapshot = object;
```

What a scan shows right now.

#### Properties [#properties-15]

##### error [#error-1]

```ts
error: DeviceError | null;
```

Why the scan failed, `null` when it has not.

##### found [#found]

```ts
found: readonly Found[];
```

One row per device, without the ones that went silent.

##### scanning [#scanning]

```ts
scanning: boolean;
```

Whether the radio is scanning.

***

### EarSide [#earside]

```ts
type EarSide = "left" | "right";
```

One ear of a pair.

***

### EarState [#earstate]

```ts
type EarState = object;
```

One ear of a hearing aid pair as it last reported itself; a field is `null` until the ear answers.

#### Properties [#properties-16]

##### battery [#battery-3]

```ts
battery: number | null;
```

Charge level from 0 to 100.

##### charging [#charging-1]

```ts
charging: boolean | null;
```

Whether it is charging.

##### inCase [#incase]

```ts
inCase: boolean | null;
```

Whether it sits in its charging case.

##### inEar [#inear]

```ts
inEar: boolean | null;
```

Whether its sensor says it sits in the ear.

***

### FactoryReset [#factoryreset]

```ts
type FactoryReset = object;
```

The maker's defaults restored on a hearing aid: volume 9, noise reduction on, mixed mode, Chinese prompts.

#### Properties [#properties-17]

##### kind [#kind]

```ts
kind: "factory-reset";
```

Which setting changes.

***

### ForegroundServiceOptions [#foregroundserviceoptions]

```ts
type ForegroundServiceOptions = object;
```

What the service watches and reports besides its text.

#### Properties [#properties-18]

##### logger? [#logger-2]

```ts
logger?: Logger;
```

Where structured events go; silent by default.

##### outbox? [#outbox-1]

```ts
outbox?: OutboxWatch;
```

The offline queue whose waiting readings the notification counts; with none, it never shows a count.

***

### ForegroundServiceText [#foregroundservicetext]

```ts
type ForegroundServiceText = object;
```

The notification Android shows while the service runs.

#### Properties [#properties-19]

##### notificationBody? [#notificationbody]

```ts
notificationBody?: string;
```

The notification's body.

##### notificationTitle? [#notificationtitle]

```ts
notificationTitle?: string;
```

The notification's title.

##### unsentBody? [#unsentbody]

```ts
unsentBody?: (unsent) => string;
```

The body while readings wait to upload, given how many; "3 readings waiting to upload" by default.

###### Parameters [#parameters-67]

| Parameter | Type |
| ------ | ------ |
| `unsent` | `number` |

###### Returns [#returns-102]

`string`

***

### Found [#found-1]

```ts
type Found = object;
```

A device a scan found, one row per address.

#### Extended by [#extended-by]

- [`PairableDevice`](ui.mdx#pairabledevice)

#### Properties [#properties-20]

##### address [#address-2]

```ts
address: string;
```

Its address, in the one-spelling form `addressKey` makes.

##### lastSeenAt [#lastseenat-1]

```ts
lastSeenAt: Date;
```

When its latest advertisement arrived.

##### match [#match-1]

```ts
match: Identification;
```

What the catalog makes of it.

##### name [#name-3]

```ts
name: string | null;
```

The advertised name, `null` when it has none.

##### rssi [#rssi-1]

```ts
rssi: number | null;
```

Signal strength in dBm, `null` when the platform gives none.

***

### HearingAidChange [#hearingaidchange]

```ts
type HearingAidChange =
  | VolumeChange
  | ModeChange
  | NoiseReductionChange
  | MicrophoneChange
  | InEarDetectionChange
  | PromptLanguageChange
  | FactoryReset;
```

One setting to change on a hearing aid.

***

### HearingAidMode [#hearingaidmode]

```ts
type HearingAidMode = "mixed" | "hearing-aid" | "earphone";
```

How a hearing aid plays sound: amplifying what it hears, playing Bluetooth audio, or both.

***

### HearingAidState [#hearingaidstate]

```ts
type HearingAidState = object;
```

A hearing aid pair as it reports itself while linked, every value as the aid sent it.

#### Properties [#properties-21]

##### ears [#ears]

```ts
ears: Partial<Record<EarSide, EarState>>;
```

The linked ears.

##### inEarDetection [#ineardetection]

```ts
inEarDetection: boolean | null;
```

Whether it pauses when taken out of the ear, `null` until read.

##### kind [#kind-1]

```ts
kind: "hearing-aid";
```

The kind of device the state comes from.

##### mainEar [#mainear]

```ts
mainEar: EarSide;
```

The ear that speaks for the pair.

##### microphone [#microphone]

```ts
microphone: MicrophoneDirection | null;
```

Where it listens, `null` until changed, since the aid cannot be asked.

##### mode [#mode]

```ts
mode: HearingAidMode | null;
```

How it plays sound, `null` until read or for a value the aid reserves.

##### noiseReduction [#noisereduction]

```ts
noiseReduction: boolean | null;
```

Whether noise reduction is on, `null` until read.

##### noiseScene [#noisescene]

```ts
noiseScene: NoiseScene | null;
```

The surroundings noise reduction is tuned for, `null` until read.

##### promptLanguage [#promptlanguage]

```ts
promptLanguage: PromptLanguage | null;
```

The language of its voice prompts, `null` until read.

##### volume [#volume]

```ts
volume: VolumeStep | null;
```

The volume step and the highest step, `null` until read.

***

### HistoryRecord [#historyrecord]

```ts
type HistoryRecord = object;
```

A stored record read in order by a device that does not address its records one by one.

#### Properties [#properties-22]

##### id [#id-2]

```ts
id: string;
```

The device's stable id for it, such as a sequence number or its time; the cursor stores it.

##### reading [#reading]

```ts
reading: DecodedReading | null;
```

`null` for a record the protocol cannot decode, which then counts as handled.

***

### Identification [#identification]

```ts
type Identification =
  | {
  device: PairedDevice;
  kind: "paired";
}
  | {
  kind: "supported";
  variants: readonly [DeviceModel, ...DeviceModel[]];
}
  | {
  kind: "unsupported";
  known: readonly DeviceModel[];
};
```

What an advertisement is: a paired device, the models it matches, or known models this platform cannot run.

#### Union Members [#union-members-4]

##### Type Literal [#type-literal-10]

```ts
{
  device: PairedDevice;
  kind: "paired";
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `device` | [`PairedDevice`](#paireddevice) | Its stored record. |
| `kind` | `"paired"` | Already paired, and its stored name and bytes still agree. |

***

##### Type Literal [#type-literal-11]

```ts
{
  kind: "supported";
  variants: readonly [DeviceModel, ...DeviceModel[]];
}
```

The first variant is the default.

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"supported"` | Not paired, in the catalog, and runnable here. |
| `variants` | readonly \[[`DeviceModel`](#devicemodel), `...DeviceModel[]`\] | The models it may be. |

***

##### Type Literal [#type-literal-12]

```ts
{
  kind: "unsupported";
  known: readonly DeviceModel[];
}
```

Known models this platform cannot run.

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"unsupported"` | Not paired and in the catalog, but nothing here can run it. |
| `known` | readonly [`DeviceModel`](#devicemodel)[] | The models it matches. |

***

### InEarDetectionChange [#ineardetectionchange]

```ts
type InEarDetectionChange = object;
```

Whether a hearing aid pauses when taken out of the ear.

#### Properties [#properties-23]

##### kind [#kind-2]

```ts
kind: "in-ear-detection";
```

Which setting changes.

##### on [#on]

```ts
on: boolean;
```

Whether in-ear detection is on.

***

### LinkOption [#linkoption]

```ts
type LinkOption = object;
```

One way to reach a model: how it is found, and how its data is read.

#### Properties [#properties-24]

##### data [#data]

```ts
data: Transport;
```

What its data is read over.

##### discover [#discover-1]

```ts
discover: Transport;
```

What the device advertises over.

***

### LiveFrame [#liveframe]

```ts
type LiveFrame = object;
```

What one live notification carries.

#### Properties [#properties-25]

##### measuring? [#measuring]

```ts
measuring?: boolean;
```

Whether the device says it is measuring; without it, a frame with numbers or samples counts as measuring.

##### result? [#result]

```ts
result?: LiveResult;
```

A measurement that finished during the stream, saved like a synced record.

##### state? [#state-1]

```ts
state?: DeviceState;
```

What the device reports about itself, for a device whose stream is its state rather than a measurement.

##### values? [#values]

```ts
values?: LiveValues;
```

Numbers to show, when the notification had any.

##### waveform? [#waveform]

```ts
waveform?: Waveform;
```

Samples to trace, when it had any.

***

### LiveResult [#liveresult]

```ts
type LiveResult = object;
```

A finished measurement a live stream carries, such as a bedside monitor's cuff result.

#### Properties [#properties-26]

##### id [#id-3]

```ts
id: string;
```

Stays the same while the device repeats one result, so the result is delivered once.

##### reading [#reading-1]

```ts
reading: DecodedReading;
```

The measurement, as the protocol decoded it.

***

### LiveSpan [#livespan]

```ts
type LiveSpan = object;
```

A stretch of a live stream the app recorded; a stored record that covers it replaces it.

#### Properties [#properties-27]

##### channel [#channel]

```ts
channel: string | null;
```

The waveform channel it holds, `null` for numbers.

##### from [#from]

```ts
from: Date;
```

When its first value or sample was taken.

##### metric [#metric]

```ts
metric: MetricCode | Waveform["metric"];
```

What was recorded: a number's metric, or a waveform's.

##### to [#to]

```ts
to: Date;
```

When it ends.

***

### LiveValues [#livevalues]

```ts
type LiveValues = object;
```

Streaming numbers for display, such as the heart rate a strap sends every second.

#### Properties [#properties-28]

##### at [#at-3]

```ts
at: Date;
```

When the notification arrived.

##### deviceFlags [#deviceflags]

```ts
deviceFlags: readonly DeviceFlag[];
```

The device's raw flags, never interpretations.

##### rrIntervalsMs? [#rrintervalsms]

```ts
rrIntervalsMs?: readonly number[];
```

Beat-to-beat intervals in milliseconds, when the device sends them.

##### values [#values-1]

```ts
values: Partial<Record<MetricCode, Quantity>>;
```

The streamed numbers.

***

### MatchRule [#matchrule]

```ts
type MatchRule = object;
```

How an advertisement is recognised as a model.

#### Properties [#properties-29]

##### names? [#names]

```ts
names?: readonly string[];
```

Whole-string globs; any one matching is enough. Without names, `requires` alone decides.

##### requires? [#requires]

```ts
requires?: readonly AdvertisementTest[];
```

Every test must pass.

##### services? [#services]

```ts
services?: readonly string[];
```

Confirm-only: a hit narrows the candidates, a miss never rejects.

***

### MeasurementType [#measurementtype]

```ts
type MeasurementType = typeof MEASUREMENT_TYPES[number];
```

What a device measures.

***

### MetricCode [#metriccode]

```ts
type MetricCode =
  | "systolic"
  | "diastolic"
  | "mean_arterial_pressure"
  | "cuff_pressure"
  | "pulse_rate"
  | "heart_rate"
  | "fetal_heart_rate"
  | "ecg_qrs_duration"
  | "ecg_qtc_interval"
  | "pvc_count"
  | "energy_expended"
  | "blood_glucose"
  | "blood_ketone"
  | "blood_uric_acid"
  | "blood_cholesterol"
  | "hdl_cholesterol"
  | "ldl_cholesterol"
  | "triglycerides"
  | "blood_lactate"
  | "hemoglobin"
  | "hematocrit"
  | "body_weight"
  | "body_height"
  | "bmi"
  | "body_fat_percent"
  | "body_water_percent"
  | "muscle_percent"
  | "muscle_mass"
  | "fat_free_mass"
  | "soft_lean_mass"
  | "body_water_mass"
  | "bone_mass"
  | "visceral_fat"
  | "basal_metabolic_rate"
  | "metabolic_age"
  | "impedance"
  | "body_temperature"
  | "spo2"
  | "perfusion_index"
  | "pulse_amplitude_index"
  | "respiration_rate"
  | "fvc"
  | "fev1"
  | "fev1_fvc_ratio"
  | "pef"
  | "fef25_75"
  | "steps"
  | "distance"
  | "active_energy"
  | "urine_urobilinogen"
  | "urine_blood"
  | "urine_bilirubin"
  | "urine_ketones"
  | "urine_glucose"
  | "urine_protein"
  | "urine_ph"
  | "urine_nitrite"
  | "urine_leukocytes"
  | "urine_specific_gravity"
  | "urine_ascorbic_acid"
  | "urine_microalbumin"
  | "urine_creatinine"
  | "urine_calcium";
```

What one value in a reading is.

***

### MicrophoneChange [#microphonechange]

```ts
type MicrophoneChange = object;
```

Where a hearing aid listens.

#### Properties [#properties-30]

##### direction [#direction-1]

```ts
direction: MicrophoneDirection;
```

The direction to set.

##### kind [#kind-3]

```ts
kind: "microphone";
```

Which setting changes.

***

### MicrophoneDirection [#microphonedirection]

```ts
type MicrophoneDirection = "all-around" | "front";
```

Where a hearing aid listens: all around with one microphone, or ahead with two.

***

### ModeChange [#modechange]

```ts
type ModeChange = object;
```

A new way for a hearing aid to play sound.

#### Properties [#properties-31]

##### kind [#kind-4]

```ts
kind: "mode";
```

Which setting changes.

##### mode [#mode-1]

```ts
mode: HearingAidMode;
```

The mode to set.

***

### NoiseReductionChange [#noisereductionchange]

```ts
type NoiseReductionChange = object;
```

Noise reduction turned on or off, tuned for a scene.

#### Properties [#properties-32]

##### kind [#kind-5]

```ts
kind: "noise-reduction";
```

Which setting changes.

##### on [#on-1]

```ts
on: boolean;
```

Whether noise reduction is on.

##### scene [#scene]

```ts
scene: NoiseScene;
```

The surroundings it is tuned for.

***

### NoiseScene [#noisescene-1]

```ts
type NoiseScene = "general" | "outdoor" | "meeting" | "cinema";
```

The surroundings a hearing aid's noise reduction is tuned for.

***

### OutboxView [#outboxview]

```ts
type OutboxView = object;
```

Where each outbox item stands, by id, at one moment.

#### Properties [#properties-33]

##### rejected [#rejected]

```ts
rejected: ReadonlySet<string>;
```

Items the server refused; they wait for a resend or a discard.

##### sent [#sent]

```ts
sent: ReadonlySet<string>;
```

Items the server accepted lately; an item that is in none of the three sets was discarded, or is another account's.

##### waiting [#waiting]

```ts
waiting: ReadonlySet<string>;
```

Items still to be sent, including the one in flight.

***

### OvokSinkClient [#ovoksinkclient]

```ts
type OvokSinkClient = SupersessionClient;
```

What the sink saves with: the measurements API, the outbox that deletes, and the session that names the patient.

***

### PairedDevice [#paireddevice]

```ts
type PairedDevice = object;
```

A paired device as it is stored, so it survives an app restart.

#### Properties [#properties-34]

##### address [#address-3]

```ts
address: string;
```

The address in the form `addressKey` makes; the store key.

##### autoSync [#autosync-2]

```ts
autoSync: boolean;
```

Whether it syncs by itself when a scan sees it, as well as on a button press.

##### battery [#battery-4]

```ts
battery: Battery | null;
```

The latest battery report.

##### cursor [#cursor]

```ts
cursor: readonly string[];
```

Ids of the device's records that were saved, kept only while the device still holds them.

##### identity [#identity-1]

```ts
identity: DeviceIdentity | null;
```

The latest identity report.

##### keepInBackground [#keepinbackground-1]

```ts
keepInBackground: boolean;
```

Whether its link stays open while the app is in the background, reconnecting when it drops.

##### lastConnectedAt [#lastconnectedat-1]

```ts
lastConnectedAt: Date | null;
```

When a link last opened.

##### lastReadingAt [#lastreadingat-1]

```ts
lastReadingAt: Date | null;
```

When a record was last delivered.

##### lastSyncedAt [#lastsyncedat-1]

```ts
lastSyncedAt: Date | null;
```

When a sync last succeeded.

##### lastSyncOutcome [#lastsyncoutcome-1]

```ts
lastSyncOutcome: "success" | "failed" | null;
```

How the latest sync ended, `null` before the first.

##### modelId [#modelid]

```ts
modelId: string;
```

The catalog model it was paired as.

##### name [#name-4]

```ts
name: string | null;
```

The user's title, else the advertised name.

##### pairedAt [#pairedat-1]

```ts
pairedAt: Date;
```

When it was first paired.

##### record [#record-1]

```ts
record: boolean;
```

Whether what it streams live is recorded and saved, as well as shown.

##### secret [#secret]

```ts
secret: string | null;
```

The value the device handed over when it paired, such as a password; `null` when it gave none.

***

### Pin [#pin-1]

```ts
type Pin =
  | {
  kind: "none";
}
  | {
  kind: "fixed";
  value: string;
}
  | {
  kind: "ask";
};
```

The PIN a model expects when it pairs.

#### Union Members [#union-members-5]

##### Type Literal [#type-literal-13]

```ts
{
  kind: "none";
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"none"` | Pairing asks for no PIN. |

***

##### Type Literal [#type-literal-14]

```ts
{
  kind: "fixed";
  value: string;
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"fixed"` | Pairing asks for one PIN, the same on every device. |
| `value` | `string` | That PIN. |

***

##### Type Literal [#type-literal-15]

```ts
{
  kind: "ask";
}
```

| Name | Type | Description |
| ------ | ------ | ------ |
| `kind` | `"ask"` | Pairing asks the user to type a PIN. |

***

### PromptLanguage [#promptlanguage-1]

```ts
type PromptLanguage = "chinese" | "english";
```

The language of a hearing aid's voice prompts.

***

### PromptLanguageChange [#promptlanguagechange]

```ts
type PromptLanguageChange = object;
```

The language of a hearing aid's voice prompts.

#### Properties [#properties-35]

##### kind [#kind-6]

```ts
kind: "prompt-language";
```

Which setting changes.

##### language [#language]

```ts
language: PromptLanguage;
```

The language to set.

***

### ProtocolContext [#protocolcontext]

```ts
type ProtocolContext = object;
```

What a protocol gets when a link opens.

#### Properties [#properties-36]

##### advertisement? [#advertisement]

```ts
advertisement?: Advertisement;
```

The latest advertisement a scan saw from the device; absent when none has since the app started.

##### link [#link]

```ts
link: GattLink;
```

The open connection to talk over.

##### logger [#logger-3]

```ts
logger: Logger;
```

For structured events; never readings, frames or secrets.

##### now [#now-1]

```ts
now: () => Date;
```

The clock, for protocols that stamp what they read.

###### Returns [#returns-103]

`Date`

##### secret [#secret-1]

```ts
secret: DeviceSecret;
```

Where the device's pairing secret is kept between links.

***

### Quantity [#quantity]

```ts
type Quantity = object;
```

A value with its UCUM unit.

#### Properties [#properties-37]

##### unit [#unit]

```ts
unit: string;
```

The UCUM unit code, e.g. `mm[Hg]`.

##### value [#value]

```ts
value: number;
```

The number, in `unit`.

***

### Reading [#reading-2]

```ts
type Reading = object;
```

One measurement, keyed by metric.

#### Properties [#properties-38]

##### deviceFlags [#deviceflags-1]

```ts
deviceFlags: readonly DeviceFlag[];
```

The device's raw flags, never interpretations.

##### live? [#live-2]

```ts
live?: LiveSpan;
```

Set when the app recorded this from a live stream, with the time it covers.

##### series? [#series]

```ts
series?: Series;
```

Values at a fixed interval, for a measurement that records them, such as a heart rate per second.

##### source [#source]

```ts
source: ReadingSource;
```

The model, protocol, address and record it came from.

##### supersedes? [#supersedes]

```ts
supersedes?: readonly LiveSpan[];
```

The live recordings a stored record replaces; the sink removes them before it saves the record.

##### takenAt [#takenat]

```ts
takenAt: Date | null;
```

When the device took it, `null` when it sends no time.

##### type [#type-1]

```ts
type: MeasurementType;
```

What was measured.

##### values [#values-2]

```ts
values: Partial<Record<MetricCode, Quantity>>;
```

The measured numbers; only the metrics this measurement has.

##### waveform? [#waveform-1]

```ts
waveform?: Waveform;
```

The raw trace, for a measurement that records one, such as an ECG.

***

### ReadingSource [#readingsource]

```ts
type ReadingSource = object;
```

Where a reading came from; `recordId` names a record stored on the device, `null` for a live value.

#### Properties [#properties-39]

##### address [#address-4]

```ts
address: string;
```

The device's address.

##### modelId [#modelid-1]

```ts
modelId: string;
```

The catalog model id.

##### protocolId [#protocolid]

```ts
protocolId: string;
```

The protocol that decoded it.

##### recordId [#recordid]

```ts
recordId: string | null;
```

The device's id for the stored record, `null` for a live value or a measurement it does not store.

***

### ReceivedReading [#receivedreading]

```ts
type ReceivedReading = object;
```

A reading received this session and how its save went.

#### Properties [#properties-40]

##### id [#id-4]

```ts
id: string;
```

Unique in the log: the address and record id, or the receive time for a reading with no record.

##### queueIds? [#queueids]

```ts
queueIds?: readonly string[];
```

The outbox items that hold the reading while it is queued or rejected, as `ovok.outbox.items` lists them.

##### reading [#reading-3]

```ts
reading: Reading;
```

The reading as the device delivered it.

##### receivedAt [#receivedat]

```ts
receivedAt: Date;
```

When this session received it.

##### save [#save-2]

```ts
save: SaveState;
```

How its save is going.

***

### RecordInfo [#recordinfo]

```ts
type RecordInfo = object;
```

A record the device stores, such as a Viatom file.

#### Properties [#properties-41]

##### id [#id-5]

```ts
id: string;
```

The device's own name for the record; the cursor stores it.

##### takenAt [#takenat-1]

```ts
takenAt: Date | null;
```

When it was measured, `null` when the device does not say.

***

### SaveOutcome [#saveoutcome]

```ts
type SaveOutcome = "saved" | "queued";
```

How a sink took a reading: saved, or kept in an offline queue that will save it.

***

### SaveReceipt [#savereceipt]

```ts
type SaveReceipt = object;
```

What a sink says about a save: how it went and, for a queued reading, which outbox items hold it.

#### Properties [#properties-42]

##### queueIds? [#queueids-1]

```ts
queueIds?: readonly string[];
```

The outbox items that hold the queued part of the reading, as `ovok.outbox.items` lists them; one per queued measurement.

##### status [#status]

```ts
status: SaveOutcome;
```

Saved, or kept in the outbox.

***

### SavesFor [#savesfor]

```ts
type SavesFor = (reading, device) => string | typeof HOLD | undefined;
```

Names the patient a reading is saved for, when the person measuring isn't the patient (a clinician): read at every
save, so it follows whoever is chosen now. `HOLD` keeps the reading until a patient is assigned, and `undefined`
means nobody is chosen, so the reading is not saved.

#### Parameters [#parameters-68]

| Parameter | Type |
| ------ | ------ |
| `reading` | [`Reading`](#reading-2) |
| `device` | [`DeviceSnapshot`](#devicesnapshot-1) |

#### Returns [#returns-104]

`string` \| *typeof* [`HOLD`](#hold) \| `undefined`

***

### SaveState [#savestate]

```ts
type SaveState = "saving" | "queued" | "saved" | "rejected" | "failed";
```

`queued` means the reading waits in the outbox, and `saved` that the server has it. `rejected` means the server
refused it there; it waits for a resend or a discard. `failed` means the sink threw; a stored record is then
released, so the next sync delivers it again.

***

### ScanFilter [#scanfilter]

```ts
type ScanFilter = object;
```

What to scan for, worked out from the wanted models.

#### Properties [#properties-43]

##### chooser [#chooser-1]

```ts
chooser: readonly ChooserFilter[] | null;
```

Name prefixes or services that show the wanted models in a browser's chooser; `null` when it can show none.

##### optionalServices [#optionalservices]

```ts
optionalServices: readonly string[];
```

Services the protocols use after connecting, which a browser needs to know up front.

##### services [#services-1]

```ts
services: readonly string[] | null;
```

Services that cover every wanted model; `null` when some model is recognised by name only.

***

### ScanHandlers [#scanhandlers]

```ts
type ScanHandlers = object;
```

What a scan reports; `onEnd` fires when the platform ends it, as a browser chooser does after one pick.

#### Properties [#properties-44]

##### onAdvertisement [#onadvertisement]

```ts
onAdvertisement: (ad) => void;
```

Called for every advertisement the radio reports, repeats included.

###### Parameters [#parameters-69]

| Parameter | Type |
| ------ | ------ |
| `ad` | `Advertisement` |

###### Returns [#returns-105]

`void`

##### onEnd [#onend]

```ts
onEnd: () => void;
```

Called when the platform ends the scan itself.

###### Returns [#returns-106]

`void`

##### onError [#onerror]

```ts
onError: (error) => void;
```

Called when the scan fails; no `onEnd` follows.

###### Parameters [#parameters-70]

| Parameter | Type |
| ------ | ------ |
| `error` | [`DeviceError`](#deviceerror) |

###### Returns [#returns-107]

`void`

***

### Series [#series-1]

```ts
type Series = object;
```

One value per fixed interval, such as a heart rate per second; `null` for an empty slot.

#### Properties [#properties-45]

##### intervalMs [#intervalms]

```ts
intervalMs: number;
```

Milliseconds between values.

##### metric [#metric-1]

```ts
metric: MetricCode;
```

What the values measure.

##### start [#start-2]

```ts
start: Date;
```

When the first value was taken.

##### unit [#unit-1]

```ts
unit: string;
```

The UCUM unit of every value.

##### values [#values-3]

```ts
values: readonly (number | null)[];
```

The values in time order, `null` for an empty slot.

***

### SyncSummary [#syncsummary]

```ts
type SyncSummary = object;
```

What one sync found and read.

#### Properties [#properties-46]

##### fetched [#fetched]

```ts
fetched: number;
```

Records this sync delivered.

##### onDevice [#ondevice]

```ts
onDevice: number;
```

Records the device held when the sync listed them.

***

### Transport [#transport]

```ts
type Transport =
  | "ble"
  | "classic"
  | "mfi"
  | "nfc"
  | "ant"
  | "cloud"
  | "phone"
  | "vendor_sdk";
```

A radio or path a model can be reached through.

***

### Vendor [#vendor-3]

```ts
type Vendor = object;
```

The brand on the box.

#### Properties [#properties-47]

##### id [#id-6]

```ts
id: string;
```

A stable lower-case slug, e.g. `viatom`.

##### name [#name-5]

```ts
name: string;
```

The brand as printed, e.g. `Viatom`.

***

### VolumeChange [#volumechange]

```ts
type VolumeChange = object;
```

A new volume for a hearing aid.

#### Properties [#properties-48]

##### kind [#kind-7]

```ts
kind: "volume";
```

Which setting changes.

##### level [#level]

```ts
level: number;
```

The step to set; one past the aid's range is kept within it.

***

### VolumeStep [#volumestep]

```ts
type VolumeStep = object;
```

A volume step and the highest step the device has.

#### Properties [#properties-49]

##### level [#level-1]

```ts
level: number;
```

The step it is set to.

##### max [#max]

```ts
max: number;
```

The highest step.

***

### Waveform [#waveform-2]

```ts
type Waveform = object;
```

Samples at a fixed rate, one array per channel; while streaming, one batch per device notification.

#### Properties [#properties-50]

##### channels [#channels]

```ts
channels: readonly string[];
```

One name per channel, in the order of `samples`.

##### firstSampleAt [#firstsampleat]

```ts
firstSampleAt: Date | null;
```

When the first sample was taken, `null` when the device sends no time.

##### metric [#metric-2]

```ts
metric: "ecg_waveform" | "pleth_waveform";
```

Which trace this is.

##### sampleRateHz [#sampleratehz]

```ts
sampleRateHz: number;
```

Samples per second, in each channel.

##### samples [#samples]

```ts
samples: readonly Int16Array[];
```

Raw counts, one array per channel.

##### scale [#scale]

```ts
scale: number;
```

`unit` per raw count.

##### unit [#unit-2]

```ts
unit: string;
```

What `scale` converts a raw count to, e.g. `mV`.

***

### WaveformBuffer [#waveformbuffer]

```ts
type WaveformBuffer = object;
```

The last `seconds` of a streamed waveform, one array per channel.

#### Properties [#properties-51]

##### channels [#channels-1]

```ts
channels: readonly (readonly number[])[];
```

One array of raw counts per channel, newest last.

##### sampleRateHz [#sampleratehz-1]

```ts
sampleRateHz: number;
```

Samples per second, in each channel.

##### scale [#scale-1]

```ts
scale: number;
```

`unit` per raw count.

##### unit [#unit-3]

```ts
unit: string;
```

What `scale` converts a raw count to.

## Variables [#variables]

### BUILT\_IN\_MODELS [#built_in_models]

```ts
const BUILT_IN_MODELS: readonly DeviceModel[];
```

Every model the SDK ships with; a new device on a known protocol is one more row here.

***

### BUILT\_IN\_PROTOCOLS [#built_in_protocols]

```ts
const BUILT_IN_PROTOCOLS: readonly DeviceProtocol[];
```

The protocols the built-in models use.

***

### HOLD [#hold]

```ts
const HOLD: typeof HOLD;
```

What `savesFor` returns to keep a reading on the device, unsent, until `ovok.outbox.assign` names who was measured:
for a shared monitor set to ask each time.
