Run a BLE scan in the background, and display seen devices in a notification.
Android only
yarn add background-bluetooth-le
npx cap syncThe 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" />
<!-- Bluetooth Scan Reciver -->
<receiver android:name="com.halleyassist.backgroundble.BackgroundBLEReceiver"></receiver>
</application>A drawable resource is also required for the notification icon. this should use the name ic_notification .
checkPermissions()requestPermissions()initialise()enable()getDevices()setDevices(...)clearDevices()startForegroundService()stopForegroundService()isRunning()didUserStop()getActiveDevice()setActiveDevice(...)getConfig()setConfig(...)addListener('devicesChanged', ...)addListener('closeDevicesChanged', ...)- Interfaces
- Type Aliases
- Enums
The background BLE plugin
checkPermissions() => Promise<PermissionStatus>Returns: Promise<PermissionStatus>
requestPermissions() => Promise<PermissionStatus>Returns: Promise<PermissionStatus>
initialise() => Promise<void>Initialise the background scanner
enable() => Promise<void>Enable bluetooth
getDevices() => Promise<Devices>Get the current list of devices
Returns: Promise<Devices>
setDevices(options: AddDevicesOptions) => Promise<Devices>Set the list of devices to scan for
| Param | Type |
|---|---|
options |
AddDevicesOptions |
Returns: Promise<Devices>
clearDevices() => Promise<Devices>Clear the list of devices to scan for
Returns: Promise<Devices>
startForegroundService() => Promise<StartStopResult>Start the background scanner
Returns: Promise<StartStopResult>
stopForegroundService() => Promise<StartStopResult>Stop the background scanner
Returns: Promise<StartStopResult>
isRunning() => Promise<RunningResult>Is the background scanner running
Returns: Promise<RunningResult>
didUserStop() => Promise<UserStoppedResult>Did the user stop the background scanner from the notification
Returns: Promise<UserStoppedResult>
getActiveDevice() => Promise<{ device: Device | null; }>Get the active Device
Returns: Promise<{ device: Device | null; }>
setActiveDevice(device: Device | null) => Promise<void>Set a device as active
| Param | Type | Description |
|---|---|---|
device |
Device | null |
The device to set as active |
getConfig() => Promise<Config>Get the scanner configuration
Returns: Promise<Config>
setConfig(options: SetConfigOptions) => Promise<Config>Set the scanner configuration
| Param | Type | Description |
|---|---|---|
options |
SetConfigOptions |
The options to set the scanner configuration |
Returns: Promise<Config>
addListener(eventName: 'devicesChanged', event: DevicesChangedListener) => Promise<PluginListenerHandle>Add a listener for when the list of devices changes
| Param | Type | Description |
|---|---|---|
eventName |
'devicesChanged' |
|
event |
DevicesChangedListener |
The listener function to call when the list of devices changes |
Returns: Promise<PluginListenerHandle>
addListener(eventName: 'closeDevicesChanged', event: DevicesChangedListener) => Promise<PluginListenerHandle>Add a listener for when the list of close devices changes
This list only includes devices that are within the configured RSSI threshold.
| Param | Type | Description |
|---|---|---|
eventName |
'closeDevicesChanged' |
|
event |
DevicesChangedListener |
The listener function to call when the list of close devices changes |
Returns: Promise<PluginListenerHandle>
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 |
The list of devices
| Prop | Type | Description |
|---|---|---|
devices |
Device[] |
The list of devices |
A device
| Prop | Type | Description |
|---|---|---|
serial |
string |
The serial of the device |
name |
string |
The display name of the device |
rssi |
number |
The RSSI of the device -127 = device is not in range |
txPower |
number |
The TX power of the device -127 = unknown TX power |
lastUpdated |
number |
The last time the device was updated in milliseconds since epoch |
The options to add multiple devices
| Prop | Type | Description |
|---|---|---|
devices |
AddDeviceOptions[] |
The devices to add to the list of devices to scan for |
The options to add a device
Only requires the serial and name of the device
| Prop | Type | Description |
|---|---|---|
serial |
string |
The serial of the device |
name |
string |
The display name of the device |
The result of starting or stopping the background scanner
| Prop | Type | Description |
|---|---|---|
result |
string |
The result of starting or stopping the background scanner |
The result of checking if the background scanner is running
| Prop | Type | Description |
|---|---|---|
running |
boolean |
The result of checking if the background scanner is running |
The result of checking if the user stopped the background scanner
| Prop | Type | Description |
|---|---|---|
userStopped |
boolean |
The result of checking if the user stopped the background scanner |
The current configuration of the scanner
| Prop | Type | Description |
|---|---|---|
config |
ScanConfig |
The result of getting the scanner configuration |
The scan configuration
| Prop | Type | Description | Default |
|---|---|---|---|
mode |
ScanMode |
The scan mode | ScanMode.LOW_POWER |
debug |
boolean |
The debug mode | false |
deviceTimeout |
number |
The device timeout in milliseconds If a device has not had a scan result for this amount of time, it will be assumed to be out of range and will be pushed down the list | 30000 |
threshold |
number |
The minimum RSSI to consider a device in range If a device has an RSSI below this value, it will be considered out of range The value is clamped to the range of -10 to -100. | -100 |
The options to set the configuration
| Prop | Type | Description |
|---|---|---|
config |
Partial<ScanConfig> |
The configuration to set |
| Prop | Type |
|---|---|
remove |
() => Promise<void> |
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
Make all properties in T optional
{
[P in keyof T]?: T[P];
}
A listener that is called when the list of devices changes
(devices: Devices): void
| 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. |