Ble
Connect to and interact with Bluetooth LE peripherals.
Install / Use
/learn @nativescript-community/BleREADME
Table of Contents
- Installation
- API * Prerequisites * Discovery * Connectivity * Interaction * Debugging
- Demos and Development
- Contributing
- Questions
Installation
Run the following command from the root of your project:
ns plugin add @nativescript-community/ble
API
Want to dive in quickly? Check out the demo app! Otherwise, mix and match these functions as you see fit:
Prerequisites
Discovery
Connectivity
Interaction
Debugging
isBluetoothEnabled
Reports if bluetooth is enabled.
// require the plugin
import { Bluetooth } from '@nativescript-community/ble';
var bluetooth = new Bluetooth();
bluetooth.isBluetoothEnabled().then(
function(enabled) {
console.log("Enabled? " + enabled);
}
);
Permissions (Android)
On Android >= 6 and < 12 you need to request permissions to be able to interact with a Bluetooth peripheral (when the app is in the background) when targeting API level 23+. You need BLUETOOTH and ACCESS_FINE_LOCATION. You should read the doc here
On android >= 12 you need new permissions. You should read the doc here
Note that for BLUETOOTH and BLUETOOTH_ADMIN you don't require runtime permission; adding those to AndroidManifest.xml suffices.
Note that hasLocationPermission will return true when:
- You're running this on iOS, or
- You're targeting an API level lower than 23, or
- You're using a device running Android < 6, or
- You've already granted permission.
bluetooth.hasLocationPermission().then(
function(granted) {
// if this is 'false' you probably want to call 'requestLocationPermission' now
console.log("Has Location Permission? " + granted);
}
);
requestLocationPermission
Since plugin version 1.2.0 the startScanning function will handle this internally so it's no longer mandatory to add permission checks to your code.
// if no permission was granted previously this will open a user consent screen
bluetooth.requestLocationPermission().then(
function(granted) {
console.log("Location permission requested, user granted? " + granted);
}
);
enable (Android only)
The promise will be rejected on iOS
// This turns bluetooth on, will return false if the user denied the request.
bluetooth.enable().then(
function(enabled) {
// use Bluetooth features if enabled is true
}
);
startScanning
A few of the optional params require a bit of explanation:
seconds
Scanning for peripherals drains the battery quickly, so you better not scan any longer than necessary. If a peripheral is in range and not engaged in another connection it usually pops up in under a second. If you don't pass in a number of seconds you will need to manually call stopScanning.
avoidDuplicates
Set this to true if you don't want duplicates with the same serviceUUID reported in "onDiscovered" callback. If true, only the first discovered peripheral with the same serviceUUID will be reported.
skipPermissionCheck
Set this to true if you don't want the plugin to check (and request) the required Bluetooth permissions. Particularly useful if you're running this function on a non-UI thread (ie. a Worker). Relevant on Android only.
filters
It's inefficient to scan for all available Bluetooth peripherals and have them report all services they offer. Moreover on Android if we don't use filters we must have location permissions and have GPS enabled
If you're only interested in finding a heartrate peripheral for instance, pass in service UUID '180d' like this: filters: [{serviceUUID:'180d'}]. If you add 2 or more (comma separated) services then only peripherals supporting ALL those services will match.
Note that UUID's are ALWAYS strings; don't pass integers.
onDiscovered
While scanning the plugin will immediately report back uniquely discovered peripherals.
This function will receive an object representing the peripheral which contains these properties (and types):
UUID: stringname: stringRSSI: number(relative signal strength, can be used for distance measurement)services?:(optional - this is set once connected to the peripheral)manufacturerId?: number(optional)advertismentData?: { localName?:string manufacturerData?: ArrayBuffer; serviceUUIDs?: string[]; txPowerLevel?:number, flags?:number }(optional)
bluetooth.startScanning({
filters: [{serviceUUID:'180d'}],
seconds: 4,
onDiscovered: function (peripheral) {
console.log("Periperhal found with UUID: " + peripheral.UUID);
}
}).then(function() {
console.log("scanning complete");
}, function (err) {
console.log("error while scanning: " + err);
});
stopScanning
At any time during a scan, being one where you passed in a number or seconds or not, you can stop the scan by calling this function.
You may for instance want to stop scanning when the peripheral you found in startScanning's onDiscovered callback matches your criteria.
bluetooth.stopScanning().then(function() {
console.log("scanning stopped");
});
connect
Pass in the UUID of the peripheral you want to connect to and once a connection has been established the onConnected callback function will be invoked. This callback will received the peripheral object as before, but it's now enriched with a services property. An example of the returned peripheral object could be:
peripheral: {
UUID: '3424-542-4534-53454',
name: 'Polar P7 Heartrate Monitor',
RSSI: '-57',
services: [{
UUID: '180d',
name: 'Heartrate service',
characteristics: [{
UUID: '34534-54353-234324-343',
name: 'Heartrate characteristic',
properties: {
read: true,
write: false,
writeWithoutResponse: false,
notify: true
}
}]
}]
}
Here's the connect functio
