cordova-plugin-ble-central
Advanced tools
Comparing version 1.7.2 to 1.7.3
{ | ||
"name": "cordova-plugin-ble-central", | ||
"version": "1.7.2", | ||
"version": "1.7.3", | ||
"description": "Bluetooth Low Energy (BLE) Central Plugin", | ||
@@ -5,0 +5,0 @@ "scripts": { |
880
README.md
# Bluetooth Low Energy (BLE) Central Plugin for Apache Cordova | ||
[![npm version](https://img.shields.io/npm/v/cordova-plugin-ble-central.svg?style=flat)](https://www.npmjs.com/package/cordova-plugin-ble-central) | ||
[![npm version](https://img.shields.io/npm/v/cordova-plugin-ble-central.svg?style=flat)](https://www.npmjs.com/package/cordova-plugin-ble-central) ![maintained](https://img.shields.io/maintenance/yes/2024?style=flat-square) [![cordova builds](https://img.shields.io/github/actions/workflow/status/don/cordova-plugin-ble-central/.github/workflows/cordova.yml?branch=master&style=flat-square&label=cordova%20builds)](https://github.com/don/cordova-plugin-ble-central/actions/workflows/cordova.yml?query=branch%3Amaster) [![capacitor builds](https://img.shields.io/github/actions/workflow/status/don/cordova-plugin-ble-central/.github/workflows/capacitor.yaml?branch=master&style=flat-square&label=capacitor%20builds)](https://github.com/don/cordova-plugin-ble-central/actions/workflows/capacitor.yaml?query=branch%3Amaster) [![license](https://img.shields.io/npm/l/cordova-plugin-ble-central.svg?style=flat)](https://www.npmjs.com/package/cordova-plugin-ble-central) | ||
@@ -42,3 +42,3 @@ This plugin enables communication between a phone and Bluetooth Low Energy (BLE) peripherals. | ||
``` | ||
```typescript | ||
const config = { | ||
@@ -87,2 +87,10 @@ ... | ||
## TypeScript | ||
TypeScript definitions are provided by this plugin. These can be added to a file by adding a [triple-slash reference](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#-reference-types-) at the top of any file using this plugin: | ||
```typescript | ||
/// <reference types="cordova-plugin-ble-central" /> | ||
``` | ||
## Android permission conflicts | ||
@@ -94,3 +102,3 @@ | ||
``` | ||
```xml | ||
<config-file target="AndroidManifest.xml" parent="/manifest"> | ||
@@ -153,3 +161,5 @@ <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28" /> | ||
ble.scan(services, seconds, success, failure); | ||
```javascript | ||
ble.scan(services, seconds, success, failure); | ||
``` | ||
@@ -160,8 +170,10 @@ ### Description | ||
{ | ||
"name": "TI SensorTag", | ||
"id": "BD922605-1B07-4D55-8D09-B66653E51BBA", | ||
"rssi": -79, | ||
"advertising": /* ArrayBuffer or map */ | ||
} | ||
```json | ||
{ | ||
"name": "TI SensorTag", | ||
"id": "BD922605-1B07-4D55-8D09-B66653E51BBA", | ||
"rssi": -79, | ||
"advertising": /* ArrayBuffer or map */ | ||
} | ||
``` | ||
@@ -185,5 +197,12 @@ Advertising information format varies depending on your platform. See [Advertising Data](#advertising-data) for more information. | ||
ble.scan([], 5, function(device) { | ||
```javascript | ||
ble.scan( | ||
[], | ||
5, | ||
function (device) { | ||
console.log(JSON.stringify(device)); | ||
}, failure); | ||
}, | ||
failure | ||
); | ||
``` | ||
@@ -194,3 +213,5 @@ ## startScan | ||
ble.startScan(services, success, failure); | ||
```javascript | ||
ble.startScan(services, success, failure); | ||
``` | ||
@@ -201,8 +222,10 @@ ### Description | ||
{ | ||
"name": "TI SensorTag", | ||
"id": "BD922605-1B07-4D55-8D09-B66653E51BBA", | ||
"rssi": -79, | ||
"advertising": /* ArrayBuffer or map */ | ||
} | ||
```json | ||
{ | ||
"name": "TI SensorTag", | ||
"id": "BD922605-1B07-4D55-8D09-B66653E51BBA", | ||
"rssi": -79, | ||
"advertising": /* ArrayBuffer or map */ | ||
} | ||
``` | ||
@@ -221,11 +244,22 @@ Advertising information format varies depending on your platform. See [Advertising Data](#advertising-data) for more information. | ||
ble.startScan([], function(device) { | ||
```javascript | ||
ble.startScan( | ||
[], | ||
function (device) { | ||
console.log(JSON.stringify(device)); | ||
}, failure); | ||
}, | ||
failure | ||
); | ||
setTimeout(ble.stopScan, | ||
5000, | ||
function() { console.log("Scan complete"); }, | ||
function() { console.log("stopScan failed"); } | ||
); | ||
setTimeout( | ||
ble.stopScan, | ||
5000, | ||
function () { | ||
console.log('Scan complete'); | ||
}, | ||
function () { | ||
console.log('stopScan failed'); | ||
} | ||
); | ||
``` | ||
@@ -236,3 +270,5 @@ ## startScanWithOptions | ||
ble.startScanWithOptions(services, options, success, failure); | ||
```javascript | ||
ble.startScanWithOptions(services, options, success, failure); | ||
``` | ||
@@ -243,8 +279,10 @@ ### Description | ||
{ | ||
"name": "TI SensorTag", | ||
"id": "BD922605-1B07-4D55-8D09-B66653E51BBA", | ||
"rssi": -79, | ||
"advertising": /* ArrayBuffer or map */ | ||
} | ||
```json | ||
{ | ||
"name": "TI SensorTag", | ||
"id": "BD922605-1B07-4D55-8D09-B66653E51BBA", | ||
"rssi": -79, | ||
"advertising": /* ArrayBuffer or map */ | ||
} | ||
``` | ||
@@ -279,14 +317,16 @@ Advertising information format varies depending on your platform. See [Advertising Data](#advertising-data) for more information. | ||
ble.startScanWithOptions([], | ||
{ reportDuplicates: true } | ||
function(device) { | ||
console.log(JSON.stringify(device)); | ||
}, | ||
failure); | ||
```javascript | ||
ble.startScanWithOptions([], | ||
{ reportDuplicates: true } | ||
function(device) { | ||
console.log(JSON.stringify(device)); | ||
}, | ||
failure); | ||
setTimeout(ble.stopScan, | ||
5000, | ||
function() { console.log("Scan complete"); }, | ||
function() { console.log("stopScan failed"); } | ||
); | ||
setTimeout(ble.stopScan, | ||
5000, | ||
function() { console.log("Scan complete"); }, | ||
function() { console.log("stopScan failed"); } | ||
); | ||
``` | ||
@@ -297,5 +337,7 @@ ## stopScan | ||
ble.stopScan(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.stopScan() | ||
```javascript | ||
ble.stopScan(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.stopScan(); | ||
``` | ||
@@ -313,21 +355,32 @@ ### Description | ||
ble.startScan([], function(device) { | ||
```javascript | ||
ble.startScan( | ||
[], | ||
function (device) { | ||
console.log(JSON.stringify(device)); | ||
}, failure); | ||
}, | ||
failure | ||
); | ||
setTimeout(ble.stopScan, | ||
5000, | ||
setTimeout( | ||
ble.stopScan, | ||
5000, | ||
function () { | ||
console.log('Scan complete'); | ||
}, | ||
function () { | ||
console.log('stopScan failed'); | ||
} | ||
); | ||
/* Alternate syntax | ||
setTimeout(function() { | ||
ble.stopScan( | ||
function() { console.log("Scan complete"); }, | ||
function() { console.log("stopScan failed"); } | ||
); | ||
}, 5000); | ||
*/ | ||
``` | ||
/* Alternate syntax | ||
setTimeout(function() { | ||
ble.stopScan( | ||
function() { console.log("Scan complete"); }, | ||
function() { console.log("stopScan failed"); } | ||
); | ||
}, 5000); | ||
*/ | ||
## setPin | ||
@@ -337,5 +390,7 @@ | ||
ble.setPin(pin, [success], [failure]); | ||
// Or using await with promises | ||
await ble.withPromises.setPin(pin) | ||
```javascript | ||
ble.setPin(pin, [success], [failure]); | ||
// Or using await with promises | ||
await ble.withPromises.setPin(pin); | ||
``` | ||
@@ -356,6 +411,8 @@ ### Description | ||
ble.bond(device_id, [success], [failure], [options]); | ||
// Or using await with promises | ||
await ble.withPromises.bond(device_id); | ||
await ble.withPromises.bond(device_id, { usePairingDialog: true }); | ||
```javascript | ||
ble.bond(device_id, [success], [failure], [options]); | ||
// Or using await with promises | ||
await ble.withPromises.bond(device_id); | ||
await ble.withPromises.bond(device_id, { usePairingDialog: true }); | ||
``` | ||
@@ -383,5 +440,7 @@ ### Description | ||
ble.unbond(device_id, [success], [failure]); | ||
// Or using await with promises | ||
await ble.withPromises.unbond(device_id); | ||
```javascript | ||
ble.unbond(device_id, [success], [failure]); | ||
// Or using await with promises | ||
await ble.withPromises.unbond(device_id); | ||
``` | ||
@@ -407,5 +466,7 @@ ### Description | ||
ble.readBondState(device_id, [success], [failure]); | ||
// Or using await with promises | ||
const bondState = await ble.withPromises.readBondState(device_id); | ||
```javascript | ||
ble.readBondState(device_id, [success], [failure]); | ||
// Or using await with promises | ||
const bondState = await ble.withPromises.readBondState(device_id); | ||
``` | ||
@@ -436,3 +497,5 @@ ### Description | ||
ble.connect(device_id, connectCallback, disconnectCallback); | ||
```javascript | ||
ble.connect(device_id, connectCallback, disconnectCallback); | ||
``` | ||
@@ -461,3 +524,5 @@ ### Description | ||
ble.autoConnect(device_id, connectCallback, disconnectCallback); | ||
```javascript | ||
ble.autoConnect(device_id, connectCallback, disconnectCallback); | ||
``` | ||
@@ -486,5 +551,7 @@ ### Description | ||
ble.disconnect(device_id, [success], [failure]); | ||
// Or using await with promises | ||
await ble.withPromises.disconnect(device_id) | ||
```javascript | ||
ble.disconnect(device_id, [success], [failure]); | ||
// Or using await with promises | ||
await ble.withPromises.disconnect(device_id); | ||
``` | ||
@@ -505,3 +572,7 @@ ### Description | ||
ble.requestMtu(device_id, mtu, [success], [failure]); | ||
```javascript | ||
ble.requestMtu(device_id, new_mtu, [success], [failure]); | ||
// Or using await with promises | ||
const actual_mtu = await ble.withPromises.requestMtu(device_id, new_mtu); | ||
``` | ||
@@ -527,10 +598,14 @@ ### Description | ||
ble.requestMtu(device_id, new_mtu, | ||
function(mtu){ | ||
alert("MTU set to: " + mtu); | ||
}, | ||
function(failure){ | ||
alert("Failed to request MTU."); | ||
} | ||
); | ||
```javascript | ||
ble.requestMtu( | ||
device_id, | ||
new_mtu, | ||
function (mtu) { | ||
alert('MTU set to: ' + mtu); | ||
}, | ||
function (failure) { | ||
alert('Failed to request MTU.'); | ||
} | ||
); | ||
``` | ||
@@ -541,5 +616,7 @@ ## requestConnectionPriority | ||
ble.requestConnectionPriority(device_id, priority, [success], [failure]); | ||
// Or using await with promises | ||
await ble.withPromises.requestConnectionPriority(device_id, priority) | ||
```javascript | ||
ble.requestConnectionPriority(device_id, priority, [success], [failure]); | ||
// Or using await with promises | ||
await ble.withPromises.requestConnectionPriority(device_id, priority); | ||
``` | ||
@@ -569,10 +646,14 @@ ### Description | ||
ble.requestConnectionPriority(device_id, "high", | ||
function() { | ||
alert("success"); | ||
}, | ||
function(failure){ | ||
alert("Failed to request connection priority: " + failure); | ||
} | ||
); | ||
```javascript | ||
ble.requestConnectionPriority( | ||
device_id, | ||
'high', | ||
function () { | ||
alert('success'); | ||
}, | ||
function (failure) { | ||
alert('Failed to request connection priority: ' + failure); | ||
} | ||
); | ||
``` | ||
@@ -583,3 +664,5 @@ ## refreshDeviceCache | ||
ble.refreshDeviceCache(deviceId, timeoutMillis, [success], [failure]); | ||
```javascript | ||
ble.refreshDeviceCache(deviceId, timeoutMillis, [success], [failure]); | ||
``` | ||
@@ -609,5 +692,7 @@ ### Description | ||
ble.read(device_id, service_uuid, characteristic_uuid, success, failure); | ||
// Or using await with promises | ||
const data = await ble.withPromises.read(device_id, service_uuid, characteristic_uuid) | ||
```javascript | ||
ble.read(device_id, service_uuid, characteristic_uuid, success, failure); | ||
// Or using await with promises | ||
const data = await ble.withPromises.read(device_id, service_uuid, characteristic_uuid); | ||
``` | ||
@@ -632,12 +717,17 @@ ### Description | ||
// read data from a characteristic, do something with output data | ||
ble.read(device_id, service_uuid, characteristic_uuid, | ||
function(data){ | ||
console.log("Hooray we have data"+JSON.stringify(data)); | ||
alert("Successfully read data from device."+JSON.stringify(data)); | ||
}, | ||
function(failure){ | ||
alert("Failed to read characteristic from device."); | ||
} | ||
); | ||
```javascript | ||
// read data from a characteristic, do something with output data | ||
ble.read( | ||
device_id, | ||
service_uuid, | ||
characteristic_uuid, | ||
function (data) { | ||
console.log('Hooray we have data' + JSON.stringify(data)); | ||
alert('Successfully read data from device.' + JSON.stringify(data)); | ||
}, | ||
function (failure) { | ||
alert('Failed to read characteristic from device.'); | ||
} | ||
); | ||
``` | ||
@@ -648,5 +738,7 @@ ## write | ||
ble.write(device_id, service_uuid, characteristic_uuid, data, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.write(device_id, service_uuid, characteristic_uuid, data) | ||
```javascript | ||
ble.write(device_id, service_uuid, characteristic_uuid, data, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.write(device_id, service_uuid, characteristic_uuid, data); | ||
``` | ||
@@ -670,18 +762,20 @@ ### Description | ||
// send 1 byte to switch a light on | ||
var data = new Uint8Array(1); | ||
data[0] = 1; | ||
ble.write(device_id, "FF10", "FF11", data.buffer, success, failure); | ||
```javascript | ||
// send 1 byte to switch a light on | ||
var data = new Uint8Array(1); | ||
data[0] = 1; | ||
ble.write(device_id, 'FF10', 'FF11', data.buffer, success, failure); | ||
// send a 3 byte value with RGB color | ||
var data = new Uint8Array(3); | ||
data[0] = 0xFF; // red | ||
data[1] = 0x00; // green | ||
data[2] = 0xFF; // blue | ||
ble.write(device_id, "ccc0", "ccc1", data.buffer, success, failure); | ||
// send a 3 byte value with RGB color | ||
var data = new Uint8Array(3); | ||
data[0] = 0xff; // red | ||
data[1] = 0x00; // green | ||
data[2] = 0xff; // blue | ||
ble.write(device_id, 'ccc0', 'ccc1', data.buffer, success, failure); | ||
// send a 32 bit integer | ||
var data = new Uint32Array(1); | ||
data[0] = counterInput.value; | ||
ble.write(device_id, SERVICE, CHARACTERISTIC, data.buffer, success, failure); | ||
// send a 32 bit integer | ||
var data = new Uint32Array(1); | ||
data[0] = counterInput.value; | ||
ble.write(device_id, SERVICE, CHARACTERISTIC, data.buffer, success, failure); | ||
``` | ||
@@ -692,5 +786,7 @@ ## writeWithoutResponse | ||
ble.writeWithoutResponse(device_id, service_uuid, characteristic_uuid, data, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.writeWithoutResponse(device_id, service_uuid, characteristic_uuid, data) | ||
```javascript | ||
ble.writeWithoutResponse(device_id, service_uuid, characteristic_uuid, data, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.writeWithoutResponse(device_id, service_uuid, characteristic_uuid, data); | ||
``` | ||
@@ -714,6 +810,8 @@ ### Description | ||
ble.startNotification(device_id, service_uuid, characteristic_uuid, success, failure); | ||
// Or using await with promises | ||
// Note, initial promise resolves or rejects depending on whether the subscribe was successful | ||
await ble.withPromises.startNotification(device_id, success, failure) | ||
```javascript | ||
ble.startNotification(device_id, service_uuid, characteristic_uuid, success, failure); | ||
// Or using await with promises | ||
// Note, initial promise resolves or rejects depending on whether the subscribe was successful | ||
await ble.withPromises.startNotification(device_id, success, failure); | ||
``` | ||
@@ -738,9 +836,11 @@ ### Description | ||
var onData = function(buffer) { | ||
// Decode the ArrayBuffer into a typed Array based on the data you expect | ||
var data = new Uint8Array(buffer); | ||
alert("Button state changed to " + data[0]); | ||
} | ||
```javascript | ||
var onData = function (buffer) { | ||
// Decode the ArrayBuffer into a typed Array based on the data you expect | ||
var data = new Uint8Array(buffer); | ||
alert('Button state changed to ' + data[0]); | ||
}; | ||
ble.startNotification(device_id, "FFE0", "FFE1", onData, failure); | ||
ble.startNotification(device_id, 'FFE0', 'FFE1', onData, failure); | ||
``` | ||
@@ -751,5 +851,7 @@ ## stopNotification | ||
ble.stopNotification(device_id, service_uuid, characteristic_uuid, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.stopNotification(device_id) | ||
```javascript | ||
ble.stopNotification(device_id, service_uuid, characteristic_uuid, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.stopNotification(device_id); | ||
``` | ||
@@ -772,5 +874,7 @@ ### Description | ||
ble.isConnected(device_id, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.isConnected(device_id) | ||
```javascript | ||
ble.isConnected(device_id, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.isConnected(device_id); | ||
``` | ||
@@ -791,11 +895,13 @@ ### Description | ||
ble.isConnected( | ||
'FFCA0B09-CB1D-4DC0-A1EF-31AFD3EDFB53', | ||
function() { | ||
console.log("Peripheral is connected"); | ||
}, | ||
function() { | ||
console.log("Peripheral is *not* connected"); | ||
} | ||
); | ||
```javascript | ||
ble.isConnected( | ||
'FFCA0B09-CB1D-4DC0-A1EF-31AFD3EDFB53', | ||
function () { | ||
console.log('Peripheral is connected'); | ||
}, | ||
function () { | ||
console.log('Peripheral is *not* connected'); | ||
} | ||
); | ||
``` | ||
@@ -806,3 +912,5 @@ ## isEnabled | ||
ble.isEnabled(success, failure); | ||
```javascript | ||
ble.isEnabled(success, failure); | ||
``` | ||
@@ -820,10 +928,12 @@ ### Description | ||
ble.isEnabled( | ||
function() { | ||
console.log("Bluetooth is enabled"); | ||
}, | ||
function() { | ||
console.log("Bluetooth is *not* enabled"); | ||
} | ||
); | ||
```javascript | ||
ble.isEnabled( | ||
function () { | ||
console.log('Bluetooth is enabled'); | ||
}, | ||
function () { | ||
console.log('Bluetooth is *not* enabled'); | ||
} | ||
); | ||
``` | ||
@@ -834,3 +944,5 @@ ## isLocationEnabled | ||
ble.isLocationEnabled(success, failure); | ||
```javascript | ||
ble.isLocationEnabled(success, failure); | ||
``` | ||
@@ -852,10 +964,12 @@ ### Description | ||
ble.isLocationEnabled( | ||
function() { | ||
console.log("location services are enabled"); | ||
}, | ||
function() { | ||
console.log("location services are *not* enabled"); | ||
} | ||
); | ||
```javascript | ||
ble.isLocationEnabled( | ||
function () { | ||
console.log('location services are enabled'); | ||
}, | ||
function () { | ||
console.log('location services are *not* enabled'); | ||
} | ||
); | ||
``` | ||
@@ -866,6 +980,8 @@ ## startLocationStateNotifications | ||
ble.startLocationStateNotifications(success, failure); | ||
// Or using await with promises | ||
// Note, initial promise resolves or rejects depending on whether the subscribe was successful | ||
await ble.withPromises.startLocationStateNotifications(success, failure) | ||
```javascript | ||
ble.startLocationStateNotifications(success, failure); | ||
// Or using await with promises | ||
// Note, initial promise resolves or rejects depending on whether the subscribe was successful | ||
await ble.withPromises.startLocationStateNotifications(success, failure); | ||
``` | ||
@@ -887,7 +1003,7 @@ ### Description | ||
ble.startLocationStateNotifications( | ||
function(enabled) { | ||
console.log("Location is " + enabled); | ||
} | ||
); | ||
```javascript | ||
ble.startLocationStateNotifications(function (enabled) { | ||
console.log('Location is ' + enabled); | ||
}); | ||
``` | ||
@@ -898,5 +1014,7 @@ ## stopLocationStateNotifications | ||
ble.stopLocationStateNotifications(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.stopLocationStateNotifications() | ||
```javascript | ||
ble.stopLocationStateNotifications(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.stopLocationStateNotifications(); | ||
``` | ||
@@ -915,6 +1033,8 @@ ### Description | ||
ble.startStateNotifications(success, failure); | ||
// Or using await with promises | ||
// Note, initial promise resolves or rejects depending on whether the subscribe was successful | ||
await ble.withPromises.startStateNotifications(success, failure) | ||
```javascript | ||
ble.startStateNotifications(success, failure); | ||
// Or using await with promises | ||
// Note, initial promise resolves or rejects depending on whether the subscribe was successful | ||
await ble.withPromises.startStateNotifications(success, failure); | ||
``` | ||
@@ -948,7 +1068,7 @@ ### Description | ||
ble.startStateNotifications( | ||
function(state) { | ||
console.log("Bluetooth is " + state); | ||
} | ||
); | ||
```javascript | ||
ble.startStateNotifications(function (state) { | ||
console.log('Bluetooth is ' + state); | ||
}); | ||
``` | ||
@@ -959,5 +1079,7 @@ ## stopStateNotifications | ||
ble.stopStateNotifications(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.stopStateNotifications() | ||
```javascript | ||
ble.stopStateNotifications(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.stopStateNotifications(); | ||
``` | ||
@@ -977,5 +1099,7 @@ ### Description | ||
ble.showBluetoothSettings(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.showBluetoothSettings() | ||
```javascript | ||
ble.showBluetoothSettings(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.showBluetoothSettings(); | ||
``` | ||
@@ -999,3 +1123,5 @@ ### Description | ||
ble.showBluetoothSettings(); | ||
```javascript | ||
ble.showBluetoothSettings(); | ||
``` | ||
@@ -1006,5 +1132,7 @@ ## enable | ||
ble.enable(success, failure); | ||
// Or using await with promises | ||
ble.withPromises.enable(); | ||
```javascript | ||
ble.enable(success, failure); | ||
// Or using await with promises | ||
ble.withPromises.enable(); | ||
``` | ||
@@ -1030,10 +1158,12 @@ ### Description | ||
ble.enable( | ||
function() { | ||
console.log("Bluetooth is enabled"); | ||
}, | ||
function() { | ||
console.log("The user did *not* enable Bluetooth"); | ||
} | ||
); | ||
```javascript | ||
ble.enable( | ||
function () { | ||
console.log('Bluetooth is enabled'); | ||
}, | ||
function () { | ||
console.log('The user did *not* enable Bluetooth'); | ||
} | ||
); | ||
``` | ||
@@ -1044,3 +1174,5 @@ ## readRSSI | ||
ble.readRSSI(device_id, success, failure); | ||
```javascript | ||
ble.readRSSI(device_id, success, failure); | ||
``` | ||
@@ -1059,16 +1191,25 @@ ### Description | ||
var rssiSample; | ||
ble.connect(device_id, | ||
function(device) { | ||
rssiSample = setInterval(function() { | ||
ble.readRSSI(device_id, function(rssi) { | ||
console.log('read RSSI',rssi,'with device', device_id); | ||
}, function(err) { | ||
console.error('unable to read RSSI',err); | ||
clearInterval(rssiSample); | ||
}) | ||
}, 5000); | ||
}, | ||
function(err) { console.error('error connecting to device')} | ||
); | ||
```javascript | ||
var rssiSample; | ||
ble.connect( | ||
device_id, | ||
function (device) { | ||
rssiSample = setInterval(function () { | ||
ble.readRSSI( | ||
device_id, | ||
function (rssi) { | ||
console.log('read RSSI', rssi, 'with device', device_id); | ||
}, | ||
function (err) { | ||
console.error('unable to read RSSI', err); | ||
clearInterval(rssiSample); | ||
} | ||
); | ||
}, 5000); | ||
}, | ||
function (err) { | ||
console.error('error connecting to device'); | ||
} | ||
); | ||
``` | ||
@@ -1079,3 +1220,5 @@ ## connectedPeripheralsWithServices | ||
ble.connectedPeripheralsWithServices([service], success, failure); | ||
```javascript | ||
ble.connectedPeripheralsWithServices([service], success, failure); | ||
``` | ||
@@ -1100,3 +1243,5 @@ ### Description | ||
ble.peripheralsWithIdentifiers([uuids], success, failure); | ||
```javascript | ||
ble.peripheralsWithIdentifiers([uuids], success, failure); | ||
``` | ||
@@ -1121,5 +1266,7 @@ ### Description | ||
ble.restoredBluetoothState(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.restoredBluetoothState(); | ||
```javascript | ||
ble.restoredBluetoothState(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.restoredBluetoothState(); | ||
``` | ||
@@ -1147,5 +1294,7 @@ ### Description | ||
ble.list(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.list(); | ||
```javascript | ||
ble.list(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.list(); | ||
``` | ||
@@ -1169,5 +1318,7 @@ ### Description | ||
ble.bondedDevices(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.bondedDevices(); | ||
```javascript | ||
ble.bondedDevices(success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.bondedDevices(); | ||
``` | ||
@@ -1191,11 +1342,15 @@ ### Description | ||
ble.l2cap.open(device_id, psm, connectCallback, disconnectCallback); | ||
// Or using await with promises | ||
await ble.withPromises.l2cap.open(device_id, psm, disconnectCallback); | ||
```javascript | ||
ble.l2cap.open(device_id, psm, connectCallback, disconnectCallback); | ||
// Or using await with promises | ||
await ble.withPromises.l2cap.open(device_id, psm, disconnectCallback); | ||
``` | ||
Android supports additional arguments in the psm flag to select whether the L2CAP channel is insecure or secure (iOS does this automatically): | ||
ble.l2cap.open(device_id, { psm: psm, secureChannel: true }, connectCallback, disconnectCallback); | ||
// Or using await with promises | ||
await ble.withPromises.l2cap.open(device_id, { psm: psm, secureChannel: true }, disconnectCallback); | ||
```javascript | ||
ble.l2cap.open(device_id, { psm: psm, secureChannel: true }, connectCallback, disconnectCallback); | ||
// Or using await with promises | ||
await ble.withPromises.l2cap.open(device_id, { psm: psm, secureChannel: true }, disconnectCallback); | ||
``` | ||
@@ -1224,5 +1379,7 @@ ### Description | ||
ble.l2cap.close(device_id, psm, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.l2cap.close(device_id, psm); | ||
```javascript | ||
ble.l2cap.close(device_id, psm, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.l2cap.close(device_id, psm); | ||
``` | ||
@@ -1249,3 +1406,5 @@ ### Description | ||
ble.l2cap.receiveData(device_id, psm, dataCallback); | ||
```javascript | ||
ble.l2cap.receiveData(device_id, psm, dataCallback); | ||
``` | ||
@@ -1271,5 +1430,7 @@ ### Description | ||
ble.l2cap.write(device_id, psm, data, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.l2cap.write(device_id, psm, data); | ||
```javascript | ||
ble.l2cap.write(device_id, psm, data, success, failure); | ||
// Or using await with promises | ||
await ble.withPromises.l2cap.write(device_id, psm, data); | ||
``` | ||
@@ -1297,60 +1458,52 @@ ### Description | ||
{ | ||
"name": "Battery Demo", | ||
"id": "20:FF:D0:FF:D1:C0", | ||
"advertising": [2,1,6,3,3,15,24,8,9,66,97,116,116,101,114,121], | ||
"rssi": -55 | ||
} | ||
```json | ||
{ | ||
"name": "Battery Demo", | ||
"id": "20:FF:D0:FF:D1:C0", | ||
"advertising": [2, 1, 6, 3, 3, 15, 24, 8, 9, 66, 97, 116, 116, 101, 114, 121], | ||
"rssi": -55 | ||
} | ||
``` | ||
After connecting, the peripheral object also includes service, characteristic and descriptor information. | ||
{ | ||
"name": "Battery Demo", | ||
"id": "20:FF:D0:FF:D1:C0", | ||
"advertising": [2,1,6,3,3,15,24,8,9,66,97,116,116,101,114,121], | ||
"rssi": -55, | ||
"services": [ | ||
"1800", | ||
"1801", | ||
"180f" | ||
], | ||
"characteristics": [ | ||
{ | ||
"service": "1800", | ||
"characteristic": "2a00", | ||
"properties": [ | ||
"Read" | ||
] | ||
}, | ||
{ | ||
"service": "1800", | ||
"characteristic": "2a01", | ||
"properties": [ | ||
"Read" | ||
] | ||
}, | ||
{ | ||
"service": "1801", | ||
"characteristic": "2a05", | ||
"properties": [ | ||
"Read" | ||
] | ||
}, | ||
{ | ||
"service": "180f", | ||
"characteristic": "2a19", | ||
"properties": [ | ||
"Read" | ||
], | ||
"descriptors": [ | ||
{ | ||
"uuid": "2901" | ||
}, | ||
{ | ||
"uuid": "2904" | ||
} | ||
] | ||
} | ||
] | ||
} | ||
```json | ||
{ | ||
"name": "Battery Demo", | ||
"id": "20:FF:D0:FF:D1:C0", | ||
"advertising": [2, 1, 6, 3, 3, 15, 24, 8, 9, 66, 97, 116, 116, 101, 114, 121], | ||
"rssi": -55, | ||
"services": ["1800", "1801", "180f"], | ||
"characteristics": [ | ||
{ | ||
"service": "1800", | ||
"characteristic": "2a00", | ||
"properties": ["Read"] | ||
}, | ||
{ | ||
"service": "1800", | ||
"characteristic": "2a01", | ||
"properties": ["Read"] | ||
}, | ||
{ | ||
"service": "1801", | ||
"characteristic": "2a05", | ||
"properties": ["Read"] | ||
}, | ||
{ | ||
"service": "180f", | ||
"characteristic": "2a19", | ||
"properties": ["Read"], | ||
"descriptors": [ | ||
{ | ||
"uuid": "2901" | ||
}, | ||
{ | ||
"uuid": "2904" | ||
} | ||
] | ||
} | ||
] | ||
} | ||
``` | ||
@@ -1368,9 +1521,11 @@ # Advertising Data | ||
{ | ||
"name": "demo", | ||
"id": "00:1A:7D:DA:71:13", | ||
"advertising": ArrayBuffer, | ||
"rssi": -37 | ||
"connectable":"true" /*Only on Android >= API Level 26*/ | ||
} | ||
```json | ||
{ | ||
"name": "demo", | ||
"id": "00:1A:7D:DA:71:13", | ||
"advertising": ArrayBuffer, | ||
"rssi": -37 | ||
"connectable":"true" /*Only on Android >= API Level 26*/ | ||
} | ||
``` | ||
@@ -1383,34 +1538,37 @@ Convert the advertising info to a Uint8Array for processing. `var adData = new Uint8Array(peripheral.advertising)`. You application is responsible for parsing all the information out of the advertising ArrayBuffer using the [GAP type constants](https://www.bluetooth.com/specifications/assigned-numbers/generic-access-profile). For example to get the service data from the advertising info, I [parse the advertising info into a map](https://github.com/don/ITP-BluetoothLE/blob/887511c375b1ab2fbef3afe210d6a6b7db44cee9/phonegap/thermometer_v2/www/js/index.js#L18-L39) and then get the service data to retrieve a [characteristic value that is being broadcast](https://github.com/don/ITP-BluetoothLE/blob/887511c375b1ab2fbef3afe210d6a6b7db44cee9/phonegap/thermometer_v2/www/js/index.js#L93-L103). | ||
{ | ||
"name": "demo" | ||
"id": "15B4F1C5-C9C0-4441-BD9F-1A7ED8F7A365", | ||
"advertising": { | ||
"kCBAdvDataLocalName": "demo", | ||
"kCBAdvDataManufacturerData": {}, // arraybuffer data not shown | ||
"kCBAdvDataServiceUUIDs": [ | ||
"721b" | ||
], | ||
"kCBAdvDataIsConnectable": true, | ||
"kCBAdvDataServiceData": { | ||
"BBB0": {} // arraybuffer data not shown | ||
}, | ||
```json | ||
{ | ||
"name": "demo" | ||
"id": "15B4F1C5-C9C0-4441-BD9F-1A7ED8F7A365", | ||
"advertising": { | ||
"kCBAdvDataLocalName": "demo", | ||
"kCBAdvDataManufacturerData": {}, // arraybuffer data not shown | ||
"kCBAdvDataServiceUUIDs": [ | ||
"721b" | ||
], | ||
"kCBAdvDataIsConnectable": true, | ||
"kCBAdvDataServiceData": { | ||
"BBB0": {} // arraybuffer data not shown | ||
}, | ||
"rssi": -61 | ||
} | ||
}, | ||
"rssi": -61 | ||
} | ||
``` | ||
Some of the values such as kCBAdvDataManufacturerData are ArrayBuffers. The data won't print out, but you can convert it to bytes using `new Uint8Array(peripheral.advertisting.kCBAdvDataManufacturerData)`. Your application is responsible for parsing and decoding any binary data such as kCBAdvDataManufacturerData or kCBAdvDataServiceData. | ||
Some of the values such as `kCBAdvDataManufacturerData` are `ArrayBuffers`. The data won't print out, but you can convert it to bytes using `new Uint8Array(peripheral.advertisting.kCBAdvDataManufacturerData)`. Your application is responsible for parsing and decoding any binary data such as `kCBAdvDataManufacturerData` or `kCBAdvDataServiceData`. | ||
function onDiscoverDevice(device) { | ||
// log the device as JSON | ||
console.log('Found Device', JSON.stringify(device, null, 2)); | ||
```javascript | ||
function onDiscoverDevice(device) { | ||
// log the device as JSON | ||
console.log('Found Device', JSON.stringify(device, null, 2)); | ||
// on iOS, print the manufacturer data if it exists | ||
if (device.advertising && device.advertising.kCBAdvDataManufacturerData) { | ||
const mfgData = new Uint8Array(device.advertising.kCBAdvDataManufacturerData); | ||
console.log('Manufacturer Data is', mfgData); | ||
} | ||
// on iOS, print the manufacturer data if it exists | ||
if (device.advertising && device.advertising.kCBAdvDataManufacturerData) { | ||
const mfgData = new Uint8Array(device.advertising.kCBAdvDataManufacturerData); | ||
console.log('Manufacturer Data is', mfgData); | ||
} | ||
} | ||
ble.scan([], 5, onDiscoverDevice, onError); | ||
ble.scan([], 5, onDiscoverDevice, onError); | ||
``` | ||
@@ -1432,15 +1590,17 @@ ## Browser | ||
// ASCII only | ||
function stringToBytes(string) { | ||
var array = new Uint8Array(string.length); | ||
for (var i = 0, l = string.length; i < l; i++) { | ||
array[i] = string.charCodeAt(i); | ||
} | ||
return array.buffer; | ||
```javascript | ||
// ASCII only | ||
function stringToBytes(string) { | ||
var array = new Uint8Array(string.length); | ||
for (var i = 0, l = string.length; i < l; i++) { | ||
array[i] = string.charCodeAt(i); | ||
} | ||
return array.buffer; | ||
} | ||
// ASCII only | ||
function bytesToString(buffer) { | ||
return String.fromCharCode.apply(null, new Uint8Array(buffer)); | ||
} | ||
// ASCII only | ||
function bytesToString(buffer) { | ||
return String.fromCharCode.apply(null, new Uint8Array(buffer)); | ||
} | ||
``` | ||
@@ -1463,9 +1623,11 @@ You can read more about typed arrays in these articles on [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) and [HTML5 Rocks](http://www.html5rocks.com/en/tutorials/webgl/typed_arrays/). | ||
<platform name="ios"> | ||
<config-file parent="UIBackgroundModes" target="*-Info.plist"> | ||
<array> | ||
<string>bluetooth-central</string> | ||
</array> | ||
</config-file> | ||
</platform> | ||
```xml | ||
<platform name="ios"> | ||
<config-file parent="UIBackgroundModes" target="*-Info.plist"> | ||
<array> | ||
<string>bluetooth-central</string> | ||
</array> | ||
</config-file> | ||
</platform> | ||
``` | ||
@@ -1472,0 +1634,0 @@ See [ble-background](https://github.com/don/ble-background) example project for more details. |
@@ -187,2 +187,6 @@ declare namespace BLECentralPlugin { | ||
/* May be used to request (on Android) a larger MTU size to be able to send more data at once | ||
[iOS] requestMtu is not supported on iOS. */ | ||
requestMtu(device_id: string, mtu: number): Promise<number>; | ||
/* When Connecting to a peripheral android can request for the connection priority for faster communication. | ||
@@ -301,3 +305,3 @@ [iOS] requestConnectionPriority is not supported on iOS. */ | ||
[iOS] requestMtu is not supported on iOS. */ | ||
requestMtu(device_id: string, mtu: number, success?: () => any, failure?: () => any): void; | ||
requestMtu(device_id: string, mtu: number, success?: (mtu: number) => any, failure?: () => any): void; | ||
@@ -304,0 +308,0 @@ /* When Connecting to a peripheral android can request for the connection priority for faster communication. |
@@ -437,2 +437,8 @@ // (c) 2014-2016 Don Coleman | ||
requestMtu: function (device_id, mtu) { | ||
return new Promise(function (resolve, reject) { | ||
module.exports.requestMtu(device_id, mtu, resolve, reject); | ||
}); | ||
}, | ||
requestConnectionPriority: function (device_id, priority) { | ||
@@ -439,0 +445,0 @@ return new Promise(function (resolve, reject) { |
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
342004
1124
1644