diff --git a/dist/plugins/ble.d.ts b/dist/plugins/ble.d.ts index 8357b9b1e..2f69e32b4 100644 --- a/dist/plugins/ble.d.ts +++ b/dist/plugins/ble.d.ts @@ -1,10 +1,337 @@ +import { Observable } from 'rxjs/Observable'; +/** + * This plugin enables communication between a phone and Bluetooth Low Energy (BLE) peripherals. + * + * The plugin provides a simple JavaScript API for iOS and Android. + * + * - Scan for peripherals + * - Connect to a peripheral + * - Read the value of a characteristic + * - Write new value to a characteristic + * - Get notified when characteristic's value changes + * + * Advertising information is returned when scanning for peripherals. Service, characteristic, and property info is returned when connecting to a peripheral. All access is via service and characteristic UUIDs. The plugin manages handles internally. + * + * Simultaneous connections to multiple peripherals are supported. + * + * ## Peripheral Data + * + * Peripheral Data is passed to the success callback when scanning and connecting. Limited data is passed when scanning. + * ``` + * { + * "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" + * } + * ] + * } + * ] + * } + * ``` + * + * ## Advertising Data + * Bluetooth advertising data is returned in when scanning for devices. The format format varies depending on your platform. On Android advertising data will be the raw advertising bytes. iOS does not allow access to raw advertising data, so a dictionary of data is returned. + * + * The advertising information for both Android and iOS appears to be a combination of advertising data and scan response data. + * + * ### Android + * ``` + * { + * "name": "demo", + * "id": "00:1A:7D:DA:71:13", + * "advertising": ArrayBuffer, + * "rssi": -37 + * } + * ``` + * + * Convert the advertising info to a Uint8Array for processing. `var adData = new Uint8Array(peripheral.advertising)` + * + * ### iOS + * + * Note that iOS uses the string value of the constants for the [Advertisement Data Retrieval Keys](https://developer.apple.com/library/ios/documentation/CoreBluetooth/Reference/CBCentralManagerDelegate_Protocol/index.html#//apple_ref/doc/constant_group/Advertisement_Data_Retrieval_Keys). This will likely change in the future. + * ``` + * { + * "name": "demo", + * "id": "D8479A4F-7517-BCD3-91B5-3302B2F81802", + * "advertising": { + * "kCBAdvDataChannel": 37, + * "kCBAdvDataServiceData": { + * "FED8": { + * "byteLength": 7 // data not shown + * } + * }, + * "kCBAdvDataLocalName": "demo", + * "kCBAdvDataServiceUUIDs": ["FED8"], + * "kCBAdvDataManufacturerData": { + * "byteLength": 7 // data not shown + * }, + * "kCBAdvDataTxPowerLevel": 32, + * "kCBAdvDataIsConnectable": true + * }, + * "rssi": -53 + * } + * ``` + * + * ## Typed Arrays + * + * This plugin uses typed Arrays or ArrayBuffers for sending and receiving data. + * + * This means that you need convert your data to ArrayBuffers before sending and from ArrayBuffers when receiving. + * ``` + * // 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)); + * } + * ``` + * 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/). + * + * ## UUIDs + * + * UUIDs are always strings and not numbers. Some 16-bit UUIDs, such as '2220' look like integers, but they're not. (The integer 2220 is 0x8AC in hex.) This isn't a problem with 128 bit UUIDs since they look like strings 82b9e6e1-593a-456f-be9b-9215160ebcac. All 16-bit UUIDs should also be passed to methods as strings. + * + */ export declare class BLE { - static scan(services: any[], seconds: number): void; - static startScan(services: any[]): void; - static stopScan(): void; - static connect(deviceId: string): void; - static disconnect(deviceId: string): void; - static read(deviceId: string, serviceUUID: string, characteristicUUID: string): void; - static write(deviceId: string, serviceUUID: string, characteristicUUID: string, value: ArrayBuffer): void; - static writeWithoutResponse(deviceId: string, serviceUUID: string, characteristicUUID: string, value: ArrayBuffer): void; + /** + * Scan and discover BLE peripherals for the specified amount of time. + * + * @usage + * ``` + * BLE.scan([], 5).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * ``` + * @param {string[]} services List of service UUIDs to discover, or `[]` to find all devices + * @param {number} seconds Number of seconds to run discovery + * @return Returns an Observable that notifies of each peripheral that is discovered during the specified time. + */ + static scan(services: string[], seconds: number): Observable; + /** + * Scan and discover BLE peripherals until `stopScan` is called. + * + * @usage + * ``` + * BLE.startScan([]).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * + * setTimeout(() => { + * BLE.stopScan(); + * }, 5000); + * ``` + * @param {string[]} services List of service UUIDs to discover, or `[]` to find all devices + * @return Returns an Observable that notifies of each peripheral discovered. + */ + static startScan(services: string[]): Observable; + /** + * Stop a scan started by `startScan`. + * + * @usage + * ``` + * BLE.startScan([]).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * setTimeout(() => { + * BLE.stopScan().then(() => { console.log('scan stopped'); }); + * }, 5000); + * ``` + * @return returns a Promise. + */ + static stopScan(): Promise; + /** + * Connect to a peripheral. + * @usage + * ``` + * BLE.connect('12:34:56:78:9A:BC').subscribe(peripheralData => { + * console.log(peripheralData); + * }, + * peripheralData => { + * console.log('disconnected'); + * }); + * ``` + * @param deviceId {string} UUID or MAC address of the peripheral + * @return Returns an Observable that notifies of connect/disconnect. + */ + static connect(deviceId: string): Observable; + /** + * Disconnect from a peripheral. + * @usage + * ``` + * BLE.disconnect('12:34:56:78:9A:BC').then(() => { + * console.log('Disconnected'); + * }); + * ``` + * @param deviceId {string} UUID or MAC address of the peripheral + * @return Returns a Promise + */ + static disconnect(deviceId: string): Promise; + /** + * Read the value of a characteristic. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns a Promise + */ + static read(deviceId: string, serviceUUID: string, characteristicUUID: string): Promise; + /** + * Write the value of a characteristic. + * @usage + * ``` + * // send 1 byte to switch a light on + * var data = new Uint8Array(1); + * data[0] = 1; + * BLE.write(device_id, "FF10", "FF11", data.buffer); + * + * // send a 3 byte value with RGB color + * var data = new Uint8Array(3); + * data[0] = 0xFF; // red + * data[0] = 0x00; // green + * data[0] = 0xFF; // blue + * BLE.write(device_id, "ccc0", "ccc1", data.buffer); + * + * // send a 32 bit integer + * var data = new Uint32Array(1); + * data[0] = counterInput.value; + * BLE.write(device_id, SERVICE, CHARACTERISTIC, data.buffer); + * + * ``` + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @param {ArrayBuffer} value Data to write to the characteristic, as an ArrayBuffer. + * @return Returns a Promise + */ + static write(deviceId: string, serviceUUID: string, characteristicUUID: string, value: ArrayBuffer): Promise; + /** + * Write the value of a characteristic without waiting for confirmation from the peripheral. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @param {ArrayBuffer} value Data to write to the characteristic, as an ArrayBuffer. + * @return Returns a Promise + */ + static writeWithoutResponse(deviceId: string, serviceUUID: string, characteristicUUID: string, value: ArrayBuffer): Promise; + /** + * Register to be notified when the value of a characteristic changes. + * + * @usage + * ``` + * BLE.startNotification(device_id, "FF10", "FF11").subscribe(buffer => { + * console.log(String.fromCharCode.apply(null, new Uint8Array(buffer)); + * }); + * ``` + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns an Observable that notifies of characteristic changes. + */ + static startNotification(deviceId: string, serviceUUID: string, characteristicUUID: string): Observable; + /** + * Stop being notified when the value of a characteristic changes. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns a Promise. + */ + static stopNotification(deviceId: string, serviceUUID: string, characteristicUUID: string): Promise; + /** + * Report the connection status. + * + * @usage + * ``` + * BLE.isConnected('FFCA0B09-CB1D-4DC0-A1EF-31AFD3EDFB53').then( + * () => { console.log('connected'); }, + * () => { console.log('not connected'); } + * ); + * ``` + * @param {string} device_id UUID or MAC address of the peripheral + * @return Returns a Promise. + */ + static isConnected(deviceId: string): Promise; + /** + * Report if bluetooth is enabled. + * + * @usage + * ``` + * BLE.isEnabled().then( + * () => { console.log('enabled'); }, + * () => { console.log('not enabled'); } + * ); + * ``` + * @return Returns a Promise. + */ + static isEnabled(): Promise; + /** + * Open System Bluetooth settings (Android only). + * + * @return Returns a Promise. + */ + static showBluetoothSettings(): Promise; + /** + * Enable Bluetooth on the device (Android only). + * + * @return Returns a Promise. + */ + static enable(): Promise; } diff --git a/dist/plugins/ble.js b/dist/plugins/ble.js index ea61ab6a7..1ee119cf0 100644 --- a/dist/plugins/ble.js +++ b/dist/plugins/ble.js @@ -5,35 +5,472 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key, return c > 3 && r && Object.defineProperty(target, key, r), r; }; var plugin_1 = require('./plugin'); +var Observable_1 = require('rxjs/Observable'); +/** + * This plugin enables communication between a phone and Bluetooth Low Energy (BLE) peripherals. + * + * The plugin provides a simple JavaScript API for iOS and Android. + * + * - Scan for peripherals + * - Connect to a peripheral + * - Read the value of a characteristic + * - Write new value to a characteristic + * - Get notified when characteristic's value changes + * + * Advertising information is returned when scanning for peripherals. Service, characteristic, and property info is returned when connecting to a peripheral. All access is via service and characteristic UUIDs. The plugin manages handles internally. + * + * Simultaneous connections to multiple peripherals are supported. + * + * ## Peripheral Data + * + * Peripheral Data is passed to the success callback when scanning and connecting. Limited data is passed when scanning. + * ``` + * { + * "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" + * } + * ] + * } + * ] + * } + * ``` + * + * ## Advertising Data + * Bluetooth advertising data is returned in when scanning for devices. The format format varies depending on your platform. On Android advertising data will be the raw advertising bytes. iOS does not allow access to raw advertising data, so a dictionary of data is returned. + * + * The advertising information for both Android and iOS appears to be a combination of advertising data and scan response data. + * + * ### Android + * ``` + * { + * "name": "demo", + * "id": "00:1A:7D:DA:71:13", + * "advertising": ArrayBuffer, + * "rssi": -37 + * } + * ``` + * + * Convert the advertising info to a Uint8Array for processing. `var adData = new Uint8Array(peripheral.advertising)` + * + * ### iOS + * + * Note that iOS uses the string value of the constants for the [Advertisement Data Retrieval Keys](https://developer.apple.com/library/ios/documentation/CoreBluetooth/Reference/CBCentralManagerDelegate_Protocol/index.html#//apple_ref/doc/constant_group/Advertisement_Data_Retrieval_Keys). This will likely change in the future. + * ``` + * { + * "name": "demo", + * "id": "D8479A4F-7517-BCD3-91B5-3302B2F81802", + * "advertising": { + * "kCBAdvDataChannel": 37, + * "kCBAdvDataServiceData": { + * "FED8": { + * "byteLength": 7 // data not shown + * } + * }, + * "kCBAdvDataLocalName": "demo", + * "kCBAdvDataServiceUUIDs": ["FED8"], + * "kCBAdvDataManufacturerData": { + * "byteLength": 7 // data not shown + * }, + * "kCBAdvDataTxPowerLevel": 32, + * "kCBAdvDataIsConnectable": true + * }, + * "rssi": -53 + * } + * ``` + * + * ## Typed Arrays + * + * This plugin uses typed Arrays or ArrayBuffers for sending and receiving data. + * + * This means that you need convert your data to ArrayBuffers before sending and from ArrayBuffers when receiving. + * ``` + * // 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)); + * } + * ``` + * 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/). + * + * ## UUIDs + * + * UUIDs are always strings and not numbers. Some 16-bit UUIDs, such as '2220' look like integers, but they're not. (The integer 2220 is 0x8AC in hex.) This isn't a problem with 128 bit UUIDs since they look like strings 82b9e6e1-593a-456f-be9b-9215160ebcac. All 16-bit UUIDs should also be passed to methods as strings. + * + */ var BLE = (function () { function BLE() { } - BLE.scan = function (services, seconds) { }; - BLE.startScan = function (services) { }; + /** + * Scan and discover BLE peripherals for the specified amount of time. + * + * @usage + * ``` + * BLE.scan([], 5).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * ``` + * @param {string[]} services List of service UUIDs to discover, or `[]` to find all devices + * @param {number} seconds Number of seconds to run discovery + * @return Returns an Observable that notifies of each peripheral that is discovered during the specified time. + */ + BLE.scan = function (services, seconds) { + // This Observable is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Observable, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Observable_1.Observable(function (observer) { }); + }; + /** + * Scan and discover BLE peripherals until `stopScan` is called. + * + * @usage + * ``` + * BLE.startScan([]).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * + * setTimeout(() => { + * BLE.stopScan(); + * }, 5000); + * ``` + * @param {string[]} services List of service UUIDs to discover, or `[]` to find all devices + * @return Returns an Observable that notifies of each peripheral discovered. + */ + BLE.startScan = function (services) { + // This Observable is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Observable, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Observable_1.Observable(function (observer) { }); + }; ; - BLE.stopScan = function () { }; + /** + * Stop a scan started by `startScan`. + * + * @usage + * ``` + * BLE.startScan([]).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * setTimeout(() => { + * BLE.stopScan().then(() => { console.log('scan stopped'); }); + * }, 5000); + * ``` + * @return returns a Promise. + */ + BLE.stopScan = function () { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; ; - BLE.connect = function (deviceId) { }; + /** + * Connect to a peripheral. + * @usage + * ``` + * BLE.connect('12:34:56:78:9A:BC').subscribe(peripheralData => { + * console.log(peripheralData); + * }, + * peripheralData => { + * console.log('disconnected'); + * }); + * ``` + * @param deviceId {string} UUID or MAC address of the peripheral + * @return Returns an Observable that notifies of connect/disconnect. + */ + BLE.connect = function (deviceId) { + // This Observable is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Observable, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Observable_1.Observable(function (observer) { }); + }; ; - BLE.disconnect = function (deviceId) { }; + /** + * Disconnect from a peripheral. + * @usage + * ``` + * BLE.disconnect('12:34:56:78:9A:BC').then(() => { + * console.log('Disconnected'); + * }); + * ``` + * @param deviceId {string} UUID or MAC address of the peripheral + * @return Returns a Promise + */ + BLE.disconnect = function (deviceId) { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; ; - BLE.read = function (deviceId, serviceUUID, characteristicUUID) { }; + /** + * Read the value of a characteristic. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns a Promise + */ + BLE.read = function (deviceId, serviceUUID, characteristicUUID) { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; ; - BLE.write = function (deviceId, serviceUUID, characteristicUUID, value) { }; + /** + * Write the value of a characteristic. + * @usage + * ``` + * // send 1 byte to switch a light on + * var data = new Uint8Array(1); + * data[0] = 1; + * BLE.write(device_id, "FF10", "FF11", data.buffer); + * + * // send a 3 byte value with RGB color + * var data = new Uint8Array(3); + * data[0] = 0xFF; // red + * data[0] = 0x00; // green + * data[0] = 0xFF; // blue + * BLE.write(device_id, "ccc0", "ccc1", data.buffer); + * + * // send a 32 bit integer + * var data = new Uint32Array(1); + * data[0] = counterInput.value; + * BLE.write(device_id, SERVICE, CHARACTERISTIC, data.buffer); + * + * ``` + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @param {ArrayBuffer} value Data to write to the characteristic, as an ArrayBuffer. + * @return Returns a Promise + */ + BLE.write = function (deviceId, serviceUUID, characteristicUUID, value) { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; ; - BLE.writeWithoutResponse = function (deviceId, serviceUUID, characteristicUUID, value) { }; + /** + * Write the value of a characteristic without waiting for confirmation from the peripheral. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @param {ArrayBuffer} value Data to write to the characteristic, as an ArrayBuffer. + * @return Returns a Promise + */ + BLE.writeWithoutResponse = function (deviceId, serviceUUID, characteristicUUID, value) { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; ; + /** + * Register to be notified when the value of a characteristic changes. + * + * @usage + * ``` + * BLE.startNotification(device_id, "FF10", "FF11").subscribe(buffer => { + * console.log(String.fromCharCode.apply(null, new Uint8Array(buffer)); + * }); + * ``` + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns an Observable that notifies of characteristic changes. + */ + BLE.startNotification = function (deviceId, serviceUUID, characteristicUUID) { + // This Observable is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Observable, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Observable_1.Observable(function (observer) { }); + }; + ; + /** + * Stop being notified when the value of a characteristic changes. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns a Promise. + */ + BLE.stopNotification = function (deviceId, serviceUUID, characteristicUUID) { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; + ; + /** + * Report the connection status. + * + * @usage + * ``` + * BLE.isConnected('FFCA0B09-CB1D-4DC0-A1EF-31AFD3EDFB53').then( + * () => { console.log('connected'); }, + * () => { console.log('not connected'); } + * ); + * ``` + * @param {string} device_id UUID or MAC address of the peripheral + * @return Returns a Promise. + */ + BLE.isConnected = function (deviceId) { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; + /** + * Report if bluetooth is enabled. + * + * @usage + * ``` + * BLE.isEnabled().then( + * () => { console.log('enabled'); }, + * () => { console.log('not enabled'); } + * ); + * ``` + * @return Returns a Promise. + */ + BLE.isEnabled = function () { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; + /** + * Open System Bluetooth settings (Android only). + * + * @return Returns a Promise. + */ + BLE.showBluetoothSettings = function () { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; + /** + * Enable Bluetooth on the device (Android only). + * + * @return Returns a Promise. + */ + BLE.enable = function () { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise(function (res, rej) { }); + }; __decorate([ - plugin_1.Cordova() + plugin_1.Cordova({ + observable: true + }) ], BLE, "scan", null); __decorate([ - plugin_1.Cordova() + plugin_1.Cordova({ + observable: true, + clearFunction: 'stopScan', + clearWithArgs: true + }) ], BLE, "startScan", null); __decorate([ plugin_1.Cordova() ], BLE, "stopScan", null); __decorate([ - plugin_1.Cordova() + plugin_1.Cordova({ + observable: true, + clearFunction: 'disconnect', + clearWithArgs: true + }) ], BLE, "connect", null); __decorate([ plugin_1.Cordova() @@ -47,9 +484,31 @@ var BLE = (function () { __decorate([ plugin_1.Cordova() ], BLE, "writeWithoutResponse", null); + __decorate([ + plugin_1.Cordova({ + observable: true, + clearFunction: 'stopNotification', + clearWithArgs: true + }) + ], BLE, "startNotification", null); + __decorate([ + plugin_1.Cordova() + ], BLE, "stopNotification", null); + __decorate([ + plugin_1.Cordova() + ], BLE, "isConnected", null); + __decorate([ + plugin_1.Cordova() + ], BLE, "isEnabled", null); + __decorate([ + plugin_1.Cordova() + ], BLE, "showBluetoothSettings", null); + __decorate([ + plugin_1.Cordova() + ], BLE, "enable", null); BLE = __decorate([ plugin_1.Plugin({ - name: 'BluetoothLowEnergy', + name: 'BLE', plugin: 'cordova-plugin-ble-central', pluginRef: 'ble', pluginRepo: 'https://github.com/don/cordova-plugin-ble-central' diff --git a/dist/plugins/ble.js.map b/dist/plugins/ble.js.map index 402fe4816..fe76cbca6 100644 --- a/dist/plugins/ble.js.map +++ b/dist/plugins/ble.js.map @@ -1 +1 @@ -{"version":3,"file":"ble.js","sourceRoot":"","sources":["../../src/plugins/ble.ts"],"names":["BLE","BLE.constructor","BLE.scan","BLE.startScan","BLE.stopScan","BLE.connect","BLE.disconnect","BLE.read","BLE.write","BLE.writeWithoutResponse"],"mappings":";;;;;;AAAA,uBAA8B,UAAU,CAAC,CAAA;AAEzC;IAAAA;IA8BAC,CAACA;IAtBQD,QAAIA,GADXA,UACYA,QAAcA,EAAEA,OAAcA,IAAGE,CAACA;IAGvCF,aAASA,GADhBA,UACiBA,QAAcA,IAAEG,CAACA;;IAG3BH,YAAQA,GADfA,cACkBI,CAACA;;IAGZJ,WAAOA,GADdA,UACeA,QAAeA,IAAEK,CAACA;;IAG1BL,cAAUA,GADjBA,UACkBA,QAAeA,IAAEM,CAACA;;IAG7BN,QAAIA,GADXA,UACYA,QAAeA,EAAEA,WAAkBA,EAAEA,kBAAyBA,IAAEO,CAACA;;IAGtEP,SAAKA,GADZA,UACaA,QAAeA,EAAEA,WAAkBA,EAAEA,kBAAyBA,EAAEA,KAAiBA,IAAEQ,CAACA;;IAG1FR,wBAAoBA,GAD3BA,UAC4BA,QAAeA,EAAEA,WAAkBA,EAAEA,kBAAyBA,EAAEA,KAAiBA,IAAES,CAACA;;IAtBhHT;QAACA,gBAAOA,EAAEA;OACHA,WAAIA,QAAmCA;IAE9CA;QAACA,gBAAOA,EAAEA;OACHA,gBAASA,QAAkBA;IAElCA;QAACA,gBAAOA,EAAEA;OACHA,eAAQA,QAAIA;IAEnBA;QAACA,gBAAOA,EAAEA;OACHA,cAAOA,QAAmBA;IAEjCA;QAACA,gBAAOA,EAAEA;OACHA,iBAAUA,QAAmBA;IAEpCA;QAACA,gBAAOA,EAAEA;OACHA,WAAIA,QAAkEA;IAE7EA;QAACA,gBAAOA,EAAEA;OACHA,YAAKA,QAAqFA;IAEjGA;QAACA,gBAAOA,EAAEA;OACHA,2BAAoBA,QAAqFA;IA7BlHA;QAACA,eAAMA,CAACA;YACNA,IAAIA,EAAEA,oBAAoBA;YAC1BA,MAAMA,EAAEA,4BAA4BA;YACpCA,SAASA,EAAEA,KAAKA;YAChBA,UAAUA,EAAEA,mDAAmDA;SAChEA,CAACA;YAyBDA;IAADA,UAACA;AAADA,CAACA,AA9BD,IA8BC;AAxBY,WAAG,MAwBf,CAAA"} \ No newline at end of file +{"version":3,"file":"ble.js","sourceRoot":"","sources":["../../src/plugins/ble.ts"],"names":["BLE","BLE.constructor","BLE.scan","BLE.startScan","BLE.stopScan","BLE.connect","BLE.disconnect","BLE.read","BLE.write","BLE.writeWithoutResponse","BLE.startNotification","BLE.stopNotification","BLE.isConnected","BLE.isEnabled","BLE.showBluetoothSettings","BLE.enable"],"mappings":"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"} \ No newline at end of file diff --git a/src/plugins/ble.ts b/src/plugins/ble.ts index 6e039d4ae..4e69ff04c 100644 --- a/src/plugins/ble.ts +++ b/src/plugins/ble.ts @@ -1,33 +1,484 @@ import {Plugin, Cordova} from './plugin'; +import {Observable} from 'rxjs/Observable'; +/** + * This plugin enables communication between a phone and Bluetooth Low Energy (BLE) peripherals. + * + * The plugin provides a simple JavaScript API for iOS and Android. + * + * - Scan for peripherals + * - Connect to a peripheral + * - Read the value of a characteristic + * - Write new value to a characteristic + * - Get notified when characteristic's value changes + * + * Advertising information is returned when scanning for peripherals. Service, characteristic, and property info is returned when connecting to a peripheral. All access is via service and characteristic UUIDs. The plugin manages handles internally. + * + * Simultaneous connections to multiple peripherals are supported. + * + * ## Peripheral Data + * + * Peripheral Data is passed to the success callback when scanning and connecting. Limited data is passed when scanning. + * ``` + * { + * "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" + * } + * ] + * } + * ] + * } + * ``` + * + * ## Advertising Data + * Bluetooth advertising data is returned in when scanning for devices. The format format varies depending on your platform. On Android advertising data will be the raw advertising bytes. iOS does not allow access to raw advertising data, so a dictionary of data is returned. + * + * The advertising information for both Android and iOS appears to be a combination of advertising data and scan response data. + * + * ### Android + * ``` + * { + * "name": "demo", + * "id": "00:1A:7D:DA:71:13", + * "advertising": ArrayBuffer, + * "rssi": -37 + * } + * ``` + * + * Convert the advertising info to a Uint8Array for processing. `var adData = new Uint8Array(peripheral.advertising)` + * + * ### iOS + * + * Note that iOS uses the string value of the constants for the [Advertisement Data Retrieval Keys](https://developer.apple.com/library/ios/documentation/CoreBluetooth/Reference/CBCentralManagerDelegate_Protocol/index.html#//apple_ref/doc/constant_group/Advertisement_Data_Retrieval_Keys). This will likely change in the future. + * ``` + * { + * "name": "demo", + * "id": "D8479A4F-7517-BCD3-91B5-3302B2F81802", + * "advertising": { + * "kCBAdvDataChannel": 37, + * "kCBAdvDataServiceData": { + * "FED8": { + * "byteLength": 7 // data not shown + * } + * }, + * "kCBAdvDataLocalName": "demo", + * "kCBAdvDataServiceUUIDs": ["FED8"], + * "kCBAdvDataManufacturerData": { + * "byteLength": 7 // data not shown + * }, + * "kCBAdvDataTxPowerLevel": 32, + * "kCBAdvDataIsConnectable": true + * }, + * "rssi": -53 + * } + * ``` + * + * ## Typed Arrays + * + * This plugin uses typed Arrays or ArrayBuffers for sending and receiving data. + * + * This means that you need convert your data to ArrayBuffers before sending and from ArrayBuffers when receiving. + * ``` + * // 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)); + * } + * ``` + * 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/). + * + * ## UUIDs + * + * UUIDs are always strings and not numbers. Some 16-bit UUIDs, such as '2220' look like integers, but they're not. (The integer 2220 is 0x8AC in hex.) This isn't a problem with 128 bit UUIDs since they look like strings 82b9e6e1-593a-456f-be9b-9215160ebcac. All 16-bit UUIDs should also be passed to methods as strings. + * + */ @Plugin({ - name: 'BluetoothLowEnergy', + name: 'BLE', plugin: 'cordova-plugin-ble-central', pluginRef: 'ble', pluginRepo: 'https://github.com/don/cordova-plugin-ble-central' }) export class BLE { - @Cordova() - static scan(services:any[], seconds:number) {} + /** + * Scan and discover BLE peripherals for the specified amount of time. + * + * @usage + * ``` + * BLE.scan([], 5).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * ``` + * @param {string[]} services List of service UUIDs to discover, or `[]` to find all devices + * @param {number} seconds Number of seconds to run discovery + * @return Returns an Observable that notifies of each peripheral that is discovered during the specified time. + */ + @Cordova({ + observable: true + }) + static scan(services:string[], seconds:number) { + // This Observable is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Observable, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Observable(observer => {}); + } - @Cordova() - static startScan(services:any[]){}; + /** + * Scan and discover BLE peripherals until `stopScan` is called. + * + * @usage + * ``` + * BLE.startScan([]).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * + * setTimeout(() => { + * BLE.stopScan(); + * }, 5000); + * ``` + * @param {string[]} services List of service UUIDs to discover, or `[]` to find all devices + * @return Returns an Observable that notifies of each peripheral discovered. + */ + @Cordova({ + observable: true, + clearFunction: 'stopScan', + clearWithArgs: true + }) + static startScan(services:string[]){ + // This Observable is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Observable, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Observable(observer => {}); + }; + /** + * Stop a scan started by `startScan`. + * + * @usage + * ``` + * BLE.startScan([]).subscribe(device => { + * console.log(JSON.stringify(device)); + * }); + * setTimeout(() => { + * BLE.stopScan().then(() => { console.log('scan stopped'); }); + * }, 5000); + * ``` + * @return returns a Promise. + */ @Cordova() - static stopScan(){}; + static stopScan(){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + }; - @Cordova() - static connect(deviceId:string){}; + /** + * Connect to a peripheral. + * @usage + * ``` + * BLE.connect('12:34:56:78:9A:BC').subscribe(peripheralData => { + * console.log(peripheralData); + * }, + * peripheralData => { + * console.log('disconnected'); + * }); + * ``` + * @param deviceId {string} UUID or MAC address of the peripheral + * @return Returns an Observable that notifies of connect/disconnect. + */ + @Cordova({ + observable: true, + clearFunction: 'disconnect', + clearWithArgs: true + }) + static connect(deviceId:string){ + // This Observable is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Observable, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Observable(observer => {}); + }; + /** + * Disconnect from a peripheral. + * @usage + * ``` + * BLE.disconnect('12:34:56:78:9A:BC').then(() => { + * console.log('Disconnected'); + * }); + * ``` + * @param deviceId {string} UUID or MAC address of the peripheral + * @return Returns a Promise + */ @Cordova() - static disconnect(deviceId:string){}; + static disconnect(deviceId:string) { + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + }; + /** + * Read the value of a characteristic. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns a Promise + */ @Cordova() - static read(deviceId:string, serviceUUID:string, characteristicUUID:string){}; + static read(deviceId:string, serviceUUID:string, characteristicUUID:string){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + }; + /** + * Write the value of a characteristic. + * @usage + * ``` + * // send 1 byte to switch a light on + * var data = new Uint8Array(1); + * data[0] = 1; + * BLE.write(device_id, "FF10", "FF11", data.buffer); + * + * // send a 3 byte value with RGB color + * var data = new Uint8Array(3); + * data[0] = 0xFF; // red + * data[0] = 0x00; // green + * data[0] = 0xFF; // blue + * BLE.write(device_id, "ccc0", "ccc1", data.buffer); + * + * // send a 32 bit integer + * var data = new Uint32Array(1); + * data[0] = counterInput.value; + * BLE.write(device_id, SERVICE, CHARACTERISTIC, data.buffer); + * + * ``` + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @param {ArrayBuffer} value Data to write to the characteristic, as an ArrayBuffer. + * @return Returns a Promise + */ @Cordova() - static write(deviceId:string, serviceUUID:string, characteristicUUID:string, value:ArrayBuffer){}; + static write(deviceId:string, serviceUUID:string, characteristicUUID:string, value:ArrayBuffer){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + }; + /** + * Write the value of a characteristic without waiting for confirmation from the peripheral. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @param {ArrayBuffer} value Data to write to the characteristic, as an ArrayBuffer. + * @return Returns a Promise + */ @Cordova() - static writeWithoutResponse(deviceId:string, serviceUUID:string, characteristicUUID:string, value:ArrayBuffer){}; + static writeWithoutResponse(deviceId:string, serviceUUID:string, characteristicUUID:string, value:ArrayBuffer){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + }; + + /** + * Register to be notified when the value of a characteristic changes. + * + * @usage + * ``` + * BLE.startNotification(device_id, "FF10", "FF11").subscribe(buffer => { + * console.log(String.fromCharCode.apply(null, new Uint8Array(buffer)); + * }); + * ``` + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns an Observable that notifies of characteristic changes. + */ + @Cordova({ + observable: true, + clearFunction: 'stopNotification', + clearWithArgs: true + }) + static startNotification(deviceId:string, serviceUUID:string, characteristicUUID:string){ + // This Observable is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Observable, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Observable(observer => {}); + }; + + /** + * Stop being notified when the value of a characteristic changes. + * + * @param {string} device_id UUID or MAC address of the peripheral + * @param {string} service_uuid UUID of the BLE service + * @param {string} characteristic_uuid UUID of the BLE characteristic + * @return Returns a Promise. + */ + @Cordova() + static stopNotification(deviceId:string, serviceUUID:string, characteristicUUID:string){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + }; + + /** + * Report the connection status. + * + * @usage + * ``` + * BLE.isConnected('FFCA0B09-CB1D-4DC0-A1EF-31AFD3EDFB53').then( + * () => { console.log('connected'); }, + * () => { console.log('not connected'); } + * ); + * ``` + * @param {string} device_id UUID or MAC address of the peripheral + * @return Returns a Promise. + */ + @Cordova() + static isConnected(deviceId:string){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + } + + /** + * Report if bluetooth is enabled. + * + * @usage + * ``` + * BLE.isEnabled().then( + * () => { console.log('enabled'); }, + * () => { console.log('not enabled'); } + * ); + * ``` + * @return Returns a Promise. + */ + @Cordova() + static isEnabled(){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + } + + /** + * Open System Bluetooth settings (Android only). + * + * @return Returns a Promise. + */ + @Cordova() + static showBluetoothSettings(){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + } + + /** + * Enable Bluetooth on the device (Android only). + * + * @return Returns a Promise. + */ + @Cordova() + static enable(){ + // This Promise is replaced by one from the @Cordova decorator that wraps + // the plugin's callbacks. We provide a dummy one here so TypeScript + // knows that the correct return type is Promise, because there's no way + // for it to know the return type from a decorator. + // See https://github.com/Microsoft/TypeScript/issues/4881 + return new Promise((res, rej) => {}); + } }