Background Bluetooth Low Energy

Run a BLE scan in the background, and display seen devices in a notification.

Android only

Install

yarn add background-bluetooth-le
npx cap sync

Permissions

Android

The following permissions are required:

<uses-permission
  android:name="android.permission.ACCESS_COARSE_LOCATION"
  android:maxSdkVersion="30" />
<uses-permission
  android:name="android.permission.ACCESS_FINE_LOCATION"
  android:maxSdkVersion="30" />
<uses-permission
  android:name="android.permission.BLUETOOTH"
  android:maxSdkVersion="30" />
<uses-permission
  android:name="android.permission.BLUETOOTH_SCAN"
  android:usesPermissionFlags="neverForLocation"
  tools:targetApi="31" />
<uses-permission
  android:name="android.permission.BLUETOOTH_CONNECT"
  tools:targetApi="31" />
  
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" />

<uses-feature
  android:name="android.hardware.bluetooth_le"
  android:required="false" />

To use the foreground service, you must also add the following to your AndroidManifest.xml :

<application>
  <!-- Other application details -->
  <service
    android:name="com.halleyassist.backgroundble.BackgroundBLEService"
    android:foregroundServiceType="connectedDevice" />
</application>

A drawable resource is also required for the notification icon. this should use the name ic_notification .

API

• checkPermissions()
• requestPermissions()
• initialise()
• getDevices()
• setDevices(...)
• clearDevices()
• startForegroundService()
• stopForegroundService()
• isRunning()
• setScanMode(...)
• Interfaces
• Type Aliases
• Enums

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Returns: Promise<PermissionStatus>

---

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Returns: Promise<PermissionStatus>

---

initialise()

initialise() => Promise<void>

Initialise the background scanner

Since: 1.0.0

---

getDevices()

getDevices() => Promise<Result<'devices', Device[]>>

Get the current list of devices

Returns: Promise<Result<'devices', Device[]>>

Since: 1.0.0

---

setDevices(...)

setDevices(options: AddDevicesOptions) => Promise<Result<'devices', Device[]>>

Set the list of devices to scan for

Param	Type
options	AddDevicesOptions

Returns: Promise<Result<'devices', Device[]>>

Since: 1.0.0

---

clearDevices()

clearDevices() => Promise<Result<'devices', Device[]>>

Clear the list of devices to scan for

Returns: Promise<Result<'devices', Device[]>>

Since: 1.0.0

---

startForegroundService()

startForegroundService() => Promise<Result<'result', string>>

Start the background scanner

Returns: Promise<Result<'result', string>>

Since: 1.0.0

---

stopForegroundService()

stopForegroundService() => Promise<void>

Stop the background scanner

Since: 1.0.0

---

isRunning()

isRunning() => Promise<Result<'running', boolean>>

Is the background scanner running

Returns: Promise<Result<'running', boolean>>

Since: 1.0.0

---

setScanMode(...)

setScanMode(options: SetScanModeOptions) => Promise<Result<'result', ScanMode>>

Set the scan mode

The scan mode can be one of the following:

• OPPORTUNISTIC: A special Bluetooth LE scan mode. Applications using this scan mode will passively listen for other scan results without starting BLE scans themselves.
• LOW_POWER: Perform Bluetooth LE scan in low power mode. This is the default scan mode as it consumes the least power.
• BALANCED: Perform Bluetooth LE scan in balanced power mode. Scan results are returned at a rate that provides a good trade-off between scan frequency and power consumption.
• LOW_LATENCY: Scan for Bluetooth LE devices using a high duty cycle. It's recommended to only use this mode when the application is running in the foreground.

Param	Type	Description
options	SetScanModeOptions	The options to set the scan mode

Returns: Promise<Result<'result', ScanMode>>

Since: 1.0.0

---

Interfaces

PermissionStatus

The permission state

The permission state is a string that can be one of the following:

• 'granted': The permission is granted
• 'denied': The permission is denied
• 'prompt': The permission is prompt
• 'unavailable': The permission is unavailable

Prop	Type
bluetooth	PermissionState
notifications	PermissionState

Device

A device

Prop	Type	Description	Since
serial	string	The serial of the device	1.0.0
name	string	The display name of the device	1.0.0
rssi	number	The RSSI of the device 0 = device is not in range	1.0.0
txPower	number	The TX power of the device -127 = unknown TX power	1.0.0
lastUpdated	number	The last time the device was updated in milliseconds since epoch	1.0.0

AddDevicesOptions

The options to add multiple devices

Prop	Type	Description	Since
devices	AddDeviceOptions[]	The devices to add to the list of devices to scan for	1.0.0

AddDeviceOptions

The options to add a device

Only requires the serial and name of the device

Prop	Type	Description	Since
serial	string	The serial of the device	1.0.0
name	string	The display name of the device	1.0.0

SetScanModeOptions

The options to set the scan mode

Prop	Type	Description	Default	Since
mode	ScanMode	The scan mode to set	LOW_POWER	1.0.0

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Result

The result type is used to define the result of a function

{ [key in Key]: T; }

Enums

ScanMode

Members	Value	Description
OPPORTUNISTIC	-1	A special Bluetooth LE scan mode. Applications using this scan mode will passively listen for other scan results without starting BLE scans themselves.
LOW_POWER	0	Perform Bluetooth LE scan in low power mode. This is the default scan mode as it consumes the least power.
BALANCED	1	Perform Bluetooth LE scan in balanced power mode. Scan results are returned at a rate that provides a good trade-off between scan frequency and power consumption.
LOW_LATENCY	2	Scan for Bluetooth LE devices using a high duty cycle. It's recommended to only use this mode when the application is running in the foreground.