module cordova-plugin-ble-central

module cordova-plugin-ble-central.BLECentralPlugin

function cordova-plugin-ble-central.BLECentralPlugin.connect (device_id, connectSuccess, connectFailure)

description and source-code

connect = function (device_id, connectSuccess, connectFailure) {
    notSupported();
    if (connectFailure) connectFailure();
}

example usage

...
    }, 5000);
    */

## connect

Connect to a peripheral.

    ble.connect(device_id, connectSuccess, connectFailure);

### Description

Function `connect` connects to a BLE peripheral. The callback is long running. Success will be called when the connection is successful
. Service and characteristic info will be passed to the success callback in the [peripheral object](#peripheral-data). Failure is
 called if the connection fails, or later if the peripheral disconnects. An peripheral object is passed to the failure callback.

[ble.scan](#scan) must be called before calling connect, so the plugin has a list of avaiable peripherals.
...

function cordova-plugin-ble-central.BLECentralPlugin.disconnect (device_id, connectSuccess, connectFailure)

description and source-code

disconnect = function (device_id, connectSuccess, connectFailure) {
    notSupported();
    if (connectFailure) connectFailure();
}

example usage

...
- __connectSuccess__: Success callback function that is invoked when the connection is successful.
- __connectFailure__: Error callback function, invoked when error occurs or the connection disconnects.

## disconnect

Disconnect.

    ble.disconnect(device_id, [success], [failure]);

### Description

Function `disconnect` disconnects the selected device.

### Parameters
...

function cordova-plugin-ble-central.BLECentralPlugin.enable (success, failure)

description and source-code

enable = function (success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...

    ble.showBluetoothSettings();

## enable

Enable Bluetooth on the device.

    ble.enable(success, failure);

### Description

Function `enable` prompts the user to enable Bluetooth.

#### Android
...

function cordova-plugin-ble-central.BLECentralPlugin.isConnected (device_id, success, failure)

description and source-code

isConnected = function (device_id, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
- __success__: Success callback function that is invoked when the notification is removed. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]

## isConnected

Reports the connection status.

    ble.isConnected(device_id, success, failure);

### Description

Function `isConnected` calls the success callback when the peripheral is connected and the failure callback when *not* connected
.

### Parameters
...

function cordova-plugin-ble-central.BLECentralPlugin.isEnabled (success, failure)

description and source-code

isEnabled = function (success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
        }
    );

## isEnabled

Reports if bluetooth is enabled.

    ble.isEnabled(success, failure);

### Description

Function `isEnabled` calls the success callback when Bluetooth is enabled and the failure callback when Bluetooth is *not* enabled
.

### Parameters
...

function cordova-plugin-ble-central.BLECentralPlugin.read (device_id, service_uuid, characteristic_uuid, success, failure)

description and source-code

read = function (device_id, service_uuid, characteristic_uuid, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]

## read

Reads the value of a characteristic.

    ble.read(device_id, service_uuid, characteristic_uuid, success, failure);

### Description

Function `read` reads the value of the characteristic.

Raw data is passed from native code to the callback as an [ArrayBuffer](#typed-arrays).
...

function cordova-plugin-ble-central.BLECentralPlugin.readRSSI (device_id, success, failure)

description and source-code

readRSSI = function (device_id, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
        }
    );

## readRSSI

Read the RSSI value on the device connection.

    ble.readRSSI(device_id, success, failure);

### Description

Samples the RSSI value (a measure of signal strength) on the connection to a bluetooth device. Requires that you have established
 a connection before invoking (otherwise an error will be raised).

### Parameters
...

function cordova-plugin-ble-central.BLECentralPlugin.scan (services, seconds, success, failure)

description and source-code

scan = function (services, seconds, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
- [ble.enable](#enable)
- [ble.readRSSI](#readrssi)

## scan

Scan and discover BLE peripherals.

ble.scan(services, seconds, success, failure);

### Description

Function `scan` scans for BLE devices.  The success callback is called each time a peripheral is discovered. Scanning automatically
 stops after the specified number of seconds.

{
    "name": "TI SensorTag",
...

function cordova-plugin-ble-central.BLECentralPlugin.showBluetoothSettings (success, failure)

description and source-code

showBluetoothSettings = function (success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...

Function `stopStateNotifications` calls the success callback when Bluetooth state notifications have been stopped.

## showBluetoothSettings

Show the Bluetooth settings on the device.

    ble.showBluetoothSettings(success, failure);

### Description

Function `showBluetoothSettings` opens the Bluetooth settings for the operating systems.

#### iOS
...

function cordova-plugin-ble-central.BLECentralPlugin.startNotification (device_id, service_uuid, characteristic_uuid, success, failure)

description and source-code

startNotification = function (device_id, service_uuid, characteristic_uuid, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]

## startNotification

Register to be notified when the value of a characteristic changes.

    ble.startNotification(device_id, service_uuid, characteristic_uuid, success, failure
);

### Description

Function `startNotification` registers a callback that is called *every time* the value of a characteristic changes. This method
 handles both `notifications` and `indications`. The success callback is called multiple times.

Raw data is passed from native code to the success callback as an [ArrayBuffer](#typed-arrays).
...

function cordova-plugin-ble-central.BLECentralPlugin.startScan (services, success, failure)

description and source-code

startScan = function (services, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
    console.log(JSON.stringify(device));
}, failure);

## startScan

Scan and discover BLE peripherals.

ble.startScan(services, success, failure);

### Description

Function `startScan` scans for BLE devices.  The success callback is called each time a peripheral is discovered. Scanning will
continue until `stopScan` is called.

{
    "name": "TI SensorTag",
...

function cordova-plugin-ble-central.BLECentralPlugin.startScanWithOptions (services, options, success, failure)

description and source-code

startScanWithOptions = function (services, options, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
    function() { console.log("stopScan failed"); }
);

## startScanWithOptions

Scan and discover BLE peripherals, specifying scan options.

ble.startScanWithOptions(services, options, success, failure);

### Description

Function `startScanWithOptions` scans for BLE devices. It operates similarly to the `startScan` function, but allows you to specify
 extra options (like allowing duplicate device reports).  The success callback is called each time a peripheral is discovered. Scanning
 will continue until `stopScan` is called.

{
    "name": "TI SensorTag",
...

function cordova-plugin-ble-central.BLECentralPlugin.startStateNotifications (success, failure)

description and source-code

startStateNotifications = function (success, failure) {
  notSupported();
  if (failure) failure();
}

example usage

...
        }
    );

## startStateNotifications

Registers to be notified when Bluetooth state changes on the device.

    ble.startStateNotifications(success, failure);

### Description

Function `startStateNotifications` calls the success callback when the Bluetooth is enabled or disabled on the device.

__States__
...

function cordova-plugin-ble-central.BLECentralPlugin.stopNotifcation (device_id, service_uuid, characteristic_uuid, success, failure)

description and source-code

stopNotifcation = function (device_id, service_uuid, characteristic_uuid, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage
```
n/a
```

function cordova-plugin-ble-central.BLECentralPlugin.stopScan (success, failure)

description and source-code

stopScan = function (success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
    );


## stopScan

Stop scanning for BLE peripherals.

    ble.stopScan(success, failure);

### Description

Function `stopScan` stops scanning for BLE devices.

### Parameters
...

function cordova-plugin-ble-central.BLECentralPlugin.stopStateNotifications (success, failure)

description and source-code

stopStateNotifications = function (success, failure) {
  notSupported();
  if (failure) failure();
}

example usage

...
        }
    );

## stopStateNotifications

Stops state notifications.

    ble.stopStateNotifications(success, failure);

### Description

Function `stopStateNotifications` calls the success callback when Bluetooth state notifications have been stopped.

## showBluetoothSettings
...

function cordova-plugin-ble-central.BLECentralPlugin.write (device_id, service_uuid, characteristic_uuid, data, success, failure)

description and source-code

write = function (device_id, service_uuid, characteristic_uuid, data, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]

## write

Writes data to a characteristic.

    ble.write(device_id, service_uuid, characteristic_uuid, data, success, failure);

### Description

Function `write` writes data to a characteristic.

### Parameters
- __device_id__: UUID or MAC address of the peripheral
...

function cordova-plugin-ble-central.BLECentralPlugin.writeWithoutResponse (device_id, service_uuid, characteristic_uuid, data, success, failure)

description and source-code

writeWithoutResponse = function (device_id, service_uuid, characteristic_uuid, data, success, failure) {
    notSupported();
    if (failure) failure();
}

example usage

...
    data[0] = counterInput.value;
    ble.write(device_id, SERVICE, CHARACTERISTIC, data.buffer, success, failure);

## writeWithoutResponse

Writes data to a characteristic without confirmation from the peripheral.

    ble.writeWithoutResponse(device_id, service_uuid, characteristic_uuid, data, success
, failure);

### Description

Function `writeWithoutResponse` writes data to a characteristic without a response from the peripheral. You are not notified if
the write fails in the BLE stack. The success callback is be called when the characteristic is written.

### Parameters
- __device_id__: UUID or MAC address of the peripheral
...

module cordova-plugin-ble-central.ble

function cordova-plugin-ble-central.ble.connect (device_id, success, failure)

description and source-code

connect = function (device_id, success, failure) {
    var successWrapper = function(peripheral) {
        convertToNativeJS(peripheral);
        success(peripheral);
    };
    cordova.exec(successWrapper, failure, 'BLE', 'connect', [device_id]);
}

example usage

...
    }, 5000);
    */

## connect

Connect to a peripheral.

    ble.connect(device_id, connectSuccess, connectFailure);

### Description

Function `connect` connects to a BLE peripheral. The callback is long running. Success will be called when the connection is successful
. Service and characteristic info will be passed to the success callback in the [peripheral object](#peripheral-data). Failure is
 called if the connection fails, or later if the peripheral disconnects. An peripheral object is passed to the failure callback.

[ble.scan](#scan) must be called before calling connect, so the plugin has a list of avaiable peripherals.
...

function cordova-plugin-ble-central.ble.disconnect (device_id, success, failure)

description and source-code

disconnect = function (device_id, success, failure) {
    cordova.exec(success, failure, 'BLE', 'disconnect', [device_id]);
}

example usage

...
- __connectSuccess__: Success callback function that is invoked when the connection is successful.
- __connectFailure__: Error callback function, invoked when error occurs or the connection disconnects.

## disconnect

Disconnect.

    ble.disconnect(device_id, [success], [failure]);

### Description

Function `disconnect` disconnects the selected device.

### Parameters
...

function cordova-plugin-ble-central.ble.enable (success, failure)

description and source-code

enable = function (success, failure) {
    cordova.exec(success, failure, "BLE", "enable", []);
}

example usage

...

    ble.showBluetoothSettings();

## enable

Enable Bluetooth on the device.

    ble.enable(success, failure);

### Description

Function `enable` prompts the user to enable Bluetooth.

#### Android
...

function cordova-plugin-ble-central.ble.isConnected (device_id, success, failure)

description and source-code

isConnected = function (device_id, success, failure) {
    cordova.exec(success, failure, 'BLE', 'isConnected', [device_id]);
}

example usage

...
- __success__: Success callback function that is invoked when the notification is removed. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]

## isConnected

Reports the connection status.

    ble.isConnected(device_id, success, failure);

### Description

Function `isConnected` calls the success callback when the peripheral is connected and the failure callback when *not* connected
.

### Parameters
...

function cordova-plugin-ble-central.ble.isEnabled (success, failure)

description and source-code

isEnabled = function (success, failure) {
    cordova.exec(success, failure, 'BLE', 'isEnabled', []);
}

example usage

...
        }
    );

## isEnabled

Reports if bluetooth is enabled.

    ble.isEnabled(success, failure);

### Description

Function `isEnabled` calls the success callback when Bluetooth is enabled and the failure callback when Bluetooth is *not* enabled
.

### Parameters
...

function cordova-plugin-ble-central.ble.list (success, failure)

description and source-code

list = function (success, failure) {
    cordova.exec(success, failure, 'BLE', 'list', []);
}

example usage
```
n/a
```

function cordova-plugin-ble-central.ble.notify (device_id, service_uuid, characteristic_uuid, success, failure)

description and source-code

notify = function (device_id, service_uuid, characteristic_uuid, success, failure) {
    console.log("WARNING: notify is deprecated, use startNotification");
    cordova.exec(success, failure, 'BLE', 'startNotification', [device_id, service_uuid, characteristic_uuid]);
}

example usage
```
n/a
```

function cordova-plugin-ble-central.ble.read (device_id, service_uuid, characteristic_uuid, success, failure)

description and source-code

read = function (device_id, service_uuid, characteristic_uuid, success, failure) {
    cordova.exec(success, failure, 'BLE', 'read', [device_id, service_uuid, characteristic_uuid]);
}

example usage

...
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]

## read

Reads the value of a characteristic.

    ble.read(device_id, service_uuid, characteristic_uuid, success, failure);

### Description

Function `read` reads the value of the characteristic.

Raw data is passed from native code to the callback as an [ArrayBuffer](#typed-arrays).
...

function cordova-plugin-ble-central.ble.readRSSI (device_id, success, failure)

description and source-code

readRSSI = function (device_id, success, failure) {
    cordova.exec(success, failure, 'BLE', 'readRSSI', [device_id]);
}

example usage

...
        }
    );

## readRSSI

Read the RSSI value on the device connection.

    ble.readRSSI(device_id, success, failure);

### Description

Samples the RSSI value (a measure of signal strength) on the connection to a bluetooth device. Requires that you have established
 a connection before invoking (otherwise an error will be raised).

### Parameters
...

function cordova-plugin-ble-central.ble.scan (services, seconds, success, failure)

description and source-code

scan = function (services, seconds, success, failure) {
    var successWrapper = function(peripheral) {
        convertToNativeJS(peripheral);
        success(peripheral);
    };
    cordova.exec(successWrapper, failure, 'BLE', 'scan', [services, seconds]);
}

example usage

...
- [ble.enable](#enable)
- [ble.readRSSI](#readrssi)

## scan

Scan and discover BLE peripherals.

ble.scan(services, seconds, success, failure);

### Description

Function `scan` scans for BLE devices.  The success callback is called each time a peripheral is discovered. Scanning automatically
 stops after the specified number of seconds.

{
    "name": "TI SensorTag",
...

function cordova-plugin-ble-central.ble.showBluetoothSettings (success, failure)

description and source-code

showBluetoothSettings = function (success, failure) {
    cordova.exec(success, failure, "BLE", "showBluetoothSettings", []);
}

example usage

...

Function `stopStateNotifications` calls the success callback when Bluetooth state notifications have been stopped.

## showBluetoothSettings

Show the Bluetooth settings on the device.

    ble.showBluetoothSettings(success, failure);

### Description

Function `showBluetoothSettings` opens the Bluetooth settings for the operating systems.

#### iOS
...

function cordova-plugin-ble-central.ble.startNotification (device_id, service_uuid, characteristic_uuid, success, failure)

description and source-code

startNotification = function (device_id, service_uuid, characteristic_uuid, success, failure) {
    cordova.exec(success, failure, 'BLE', 'startNotification', [device_id, service_uuid, characteristic_uuid]);
}

example usage

...
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]

## startNotification

Register to be notified when the value of a characteristic changes.

    ble.startNotification(device_id, service_uuid, characteristic_uuid, success, failure
);

### Description

Function `startNotification` registers a callback that is called *every time* the value of a characteristic changes. This method
 handles both `notifications` and `indications`. The success callback is called multiple times.

Raw data is passed from native code to the success callback as an [ArrayBuffer](#typed-arrays).
...

function cordova-plugin-ble-central.ble.startScan (services, success, failure)

description and source-code

startScan = function (services, success, failure) {
    var successWrapper = function(peripheral) {
        convertToNativeJS(peripheral);
        success(peripheral);
    };
    cordova.exec(successWrapper, failure, 'BLE', 'startScan', [services]);
}

example usage

...
    console.log(JSON.stringify(device));
}, failure);

## startScan

Scan and discover BLE peripherals.

ble.startScan(services, success, failure);

### Description

Function `startScan` scans for BLE devices.  The success callback is called each time a peripheral is discovered. Scanning will
continue until `stopScan` is called.

{
    "name": "TI SensorTag",
...

function cordova-plugin-ble-central.ble.startScanWithOptions (services, options, success, failure)

description and source-code

startScanWithOptions = function (services, options, success, failure) {
    var successWrapper = function(peripheral) {
        convertToNativeJS(peripheral);
        success(peripheral);
    };
    options = options || {};
    cordova.exec(successWrapper, failure, 'BLE', 'startScanWithOptions', [services, options]);
}

example usage

...
    function() { console.log("stopScan failed"); }
);

## startScanWithOptions

Scan and discover BLE peripherals, specifying scan options.

ble.startScanWithOptions(services, options, success, failure);

### Description

Function `startScanWithOptions` scans for BLE devices. It operates similarly to the `startScan` function, but allows you to specify
 extra options (like allowing duplicate device reports).  The success callback is called each time a peripheral is discovered. Scanning
 will continue until `stopScan` is called.

{
    "name": "TI SensorTag",
...

function cordova-plugin-ble-central.ble.startStateNotifications (success, failure)

description and source-code

startStateNotifications = function (success, failure) {
    cordova.exec(success, failure, "BLE", "startStateNotifications", []);
}

example usage

...
        }
    );

## startStateNotifications

Registers to be notified when Bluetooth state changes on the device.

    ble.startStateNotifications(success, failure);

### Description

Function `startStateNotifications` calls the success callback when the Bluetooth is enabled or disabled on the device.

__States__
...

function cordova-plugin-ble-central.ble.stopNotification (device_id, service_uuid, characteristic_uuid, success, failure)

description and source-code

stopNotification = function (device_id, service_uuid, characteristic_uuid, success, failure) {
    cordova.exec(success, failure, 'BLE', 'stopNotification', [device_id, service_uuid, characteristic_uuid]);
}

example usage

...

    ble.startNotification(device_id, "FFE0", "FFE1", onData, failure);

## stopNotification

Stop being notified when the value of a characteristic changes.

    ble.stopNotification(device_id, service_uuid, characteristic_uuid, success, failure
);

### Description

Function `stopNotification` stops a previously registered notification callback.

### Parameters
...

function cordova-plugin-ble-central.ble.stopScan (success, failure)

description and source-code

stopScan = function (success, failure) {
    cordova.exec(success, failure, 'BLE', 'stopScan', []);
}

example usage

...
    );


## stopScan

Stop scanning for BLE peripherals.

    ble.stopScan(success, failure);

### Description

Function `stopScan` stops scanning for BLE devices.

### Parameters
...

function cordova-plugin-ble-central.ble.stopStateNotifications (success, failure)

description and source-code

stopStateNotifications = function (success, failure) {
    cordova.exec(success, failure, "BLE", "stopStateNotifications", []);
}

example usage

...
        }
    );

## stopStateNotifications

Stops state notifications.

    ble.stopStateNotifications(success, failure);

### Description

Function `stopStateNotifications` calls the success callback when Bluetooth state notifications have been stopped.

## showBluetoothSettings
...

function cordova-plugin-ble-central.ble.write (device_id, service_uuid, characteristic_uuid, value, success, failure)

description and source-code

write = function (device_id, service_uuid, characteristic_uuid, value, success, failure) {
    cordova.exec(success, failure, 'BLE', 'write', [device_id, service_uuid, characteristic_uuid, value]);
}

example usage

...
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]

## write

Writes data to a characteristic.

    ble.write(device_id, service_uuid, characteristic_uuid, data, success, failure);

### Description

Function `write` writes data to a characteristic.

### Parameters
- __device_id__: UUID or MAC address of the peripheral
...

function cordova-plugin-ble-central.ble.writeCommand (device_id, service_uuid, characteristic_uuid, value, success, failure)

description and source-code

writeCommand = function (device_id, service_uuid, characteristic_uuid, value, success, failure) {
    console.log("WARNING: writeCommand is deprecated, use writeWithoutResponse");
    cordova.exec(success, failure, 'BLE', 'writeWithoutResponse', [device_id, service_uuid, characteristic_uuid, value]);
}

example usage
```
n/a
```

function cordova-plugin-ble-central.ble.writeWithoutResponse (device_id, service_uuid, characteristic_uuid, value, success, failure)

description and source-code

writeWithoutResponse = function (device_id, service_uuid, characteristic_uuid, value, success, failure) {
    cordova.exec(success, failure, 'BLE', 'writeWithoutResponse', [device_id, service_uuid, characteristic_uuid, value]);
}

example usage

...
    data[0] = counterInput.value;
    ble.write(device_id, SERVICE, CHARACTERISTIC, data.buffer, success, failure);

## writeWithoutResponse

Writes data to a characteristic without confirmation from the peripheral.

    ble.writeWithoutResponse(device_id, service_uuid, characteristic_uuid, data, success
, failure);

### Description

Function `writeWithoutResponse` writes data to a characteristic without a response from the peripheral. You are not notified if
the write fails in the BLE stack. The success callback is be called when the characteristic is written.

### Parameters
- __device_id__: UUID or MAC address of the peripheral
...

api documentation for cordova-plugin-ble-central (v1.1.4)

Bluetooth Low Energy (BLE) Central Plugin

table of contents