Module: cordova-plugin-ble

Name	Type	Optional	Description
1			PERMISSION_READ
2			PERMISSION_READ_ENCRYPTED
4			PERMISSION_READ_ENCRYPTED_MITM
16			PERMISSION_WRITE
32			PERMISSION_WRITE_ENCRYPTED
64			PERMISSION_WRITE_ENCRYPTED_MITM
128			PERMISSION_WRITE_SIGNED
256			PERMISSION_WRITE_SIGNED_MITM
PERMISSION_READ			1
PERMISSION_READ_ENCRYPTED			2
PERMISSION_READ_ENCRYPTED_MITM			4
PERMISSION_WRITE			16
PERMISSION_WRITE_ENCRYPTED			32
PERMISSION_WRITE_ENCRYPTED_MITM			64
PERMISSION_WRITE_SIGNED			128
PERMISSION_WRITE_SIGNED_MITM			256

read-only static

property

A map describing possible property flags.

Properties

Name	Type	Optional	Description
1			PROPERTY_BROADCAST
2			PROPERTY_READ
4			PROPERTY_WRITE_NO_RESPONSE
8			PROPERTY_WRITE
16			PROPERTY_NOTIFY
32			PROPERTY_INDICATE
64			PROPERTY_SIGNED_WRITE
128			PROPERTY_EXTENDED_PROPS
PROPERTY_BROADCAST			1
PROPERTY_READ			2
PROPERTY_WRITE_NO_RESPONSE			4
PROPERTY_WRITE			8
PROPERTY_NOTIFY			16
PROPERTY_INDICATE			32
PROPERTY_SIGNED_WRITE			64
PROPERTY_EXTENDED_PROPS			128

read-only static

serviceType

A map describing possible service types.

Properties

Name	Type	Optional	Description
0			SERVICE_TYPE_PRIMARY
1			SERVICE_TYPE_SECONDARY
SERVICE_TYPE_PRIMARY			0
SERVICE_TYPE_SECONDARY			1

read-only static

writeType

A map describing possible write types.

Properties

Name	Type	Optional	Description
1			WRITE_TYPE_NO_RESPONSE
2			WRITE_TYPE_DEFAULT
4			WRITE_TYPE_SIGNED
WRITE_TYPE_NO_RESPONSE			1
WRITE_TYPE_DEFAULT			2
WRITE_TYPE_SIGNED			4

Methods

static

bond(device, success, fail)

Bond with device. This function shows a pairing UI on Android. Does nothing on iOS (on iOS paring cannot be requested programatically).

Example

evothings.ble.bond(
    { address: uuidOrMacAddress }
    function(newState)
    {
        console.log('New bond state: ' + newState);
    },
    function(errorCode)
    {
        console.log('bond error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Object with address of the device (a device object that contains just the address field may be used). On iOS the address is a UUID, on Android the address is a MAC address. This value can be found in the device objects obtained using startScan().
success	bondCallback	Callback function called with the new bond state (a string). On iOS the result is always 'unknown'.
fail	failCallback	Error callback function.

static

characteristics(device, service, success, fail)

Fetch information about a service's characteristics.

Example

evothings.ble.characteristics(
    device,
    service,
    function(characteristics)
    {
      console.log('found characteristics:');
      for (var i = 0; i < characteristics.length; i++)
      {
        var characteristic = characteristics[i];
        console.log('  characteristic: ' + characteristic.uuid);
      }
    },
    function(errorCode)
    {
      console.log('characteristics error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
service	Service	Service object or handle from serviceCallback.
success	characteristicCallback	Called with array of Characteristic objects.
fail	failCallback

static

close(device)

Close the connection to a remote device.

Frees any native resources associated with the device.

Does not cause any callbacks to the function passed to connect().

Example

evothings.ble.close(device);

Parameter

Name	Type	Optional	Description
device	DeviceInfo		Device object or a device handle from connectCallback.

static

connect(device, success, fail)

Connect to a remote device. It is recommended that you use the high-level function {evothings.ble.connectToDevice} in place of this function. On Android connect may fail with error 133. If this happens, wait about 500ms and connect again.

Example

evothings.ble.connect(
    device,
    function(connectInfo)
    {
        console.log('Connect status for device: '
            + connectInfo.device.name
            + ' state: '
            + connectInfo.state);
    },
    function(errorCode)
    {
        console.log('Connect error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Device object from scanCallback (for backwards compatibility, this parameter may also be the address string of the device object).
success	connectCallback
fail	failCallback

static

connectToDevice(device, connected, disconnected, fail, options)

Connect to a BLE device and discover services. This is a more high-level function than {evothings.ble.connect}. You can configure which services to discover and also turn off automatic service discovery by supplying an options parameter. On Android connect may fail with error 133. If this happens, wait about 500ms and connect again.

Example

evothings.ble.connectToDevice(
    device,
    function(device)
    {
      console.log('Connected to device: ' + device.name);
    },
    function(device)
    {
      console.log('Disconnected from device: ' + device.name);
    },
    function(errorCode)
    {
      console.log('Connect error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Device object from {scanCallback}.
connected	connectedCallback	Called when connected to the device.
disconnected	disconnectedCallback	Called when disconnected from the device.
fail	failCallback	Called on error.
options	ConnectOptions	Optional connect options object.

static

descriptors(device, characteristic, success, fail)

Fetch information about a characteristic's descriptors.

Example

evothings.ble.descriptors(
    device,
    characteristic,
    function(descriptors)
    {
      console.log('found descriptors:');
      for (var i = 0; i < descriptors.length; i++)
      {
        var descriptor = descriptors[i];
        console.log('  descriptor: ' + descriptor.uuid);
      }
    },
    function(errorCode)
    {
      console.log('descriptors error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
characteristic	Characteristic	Characteristic object or handle from characteristicCallback.
success	descriptorCallback	Called with array of Descriptor objects.
fail	failCallback

static

disableNotification(device, characteristic, success, fail, options)

Disable notification or indication of a characteristic's value.

Example

// Example call:
  evothings.ble.disableNotification(
    device,
    characteristic,
    function()
    {
      console.log('characteristic notification disabled');
    },
    function(errorCode)
    {
      console.log('disableNotification error: ' + errorCode);
    });

  // To disable automatic writing of the config descriptor
  // supply this as last parameter to enableNotification:
  { writeConfigDescriptor: false }

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
characteristic	Characteristic	Characteristic object or handle from characteristicCallback.
success	emptyCallback	Success callback.
fail	failCallback	Error callback.
options	NotificationOptions	Android only: Optional object with options. Set field writeConfigDescriptor to false to disable automatic writing of notification or indication descriptor value. This is useful if full control of writing the config descriptor is needed.

static

enableNotification(device, characteristic, success, fail, options)

Request notification or indication on changes to a characteristic's value. This is more efficient than polling the value using readCharacteristic(). This function automatically detects if the characteristic supports notification or indication.

Android only: To disable this functionality and write the configuration descriptor yourself, supply an options object as last parameter, see example below.

Example

// Example call:
  evothings.ble.enableNotification(
    device,
    characteristic,
    function(data)
    {
      console.log('characteristic data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
      console.log('enableNotification error: ' + errorCode);
    });

  // To disable automatic writing of the config descriptor
  // supply this as last parameter to enableNotification:
  { writeConfigDescriptor: false }

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
characteristic	Characteristic	Characteristic object or handle from characteristicCallback.
success	dataCallback	Called every time the value changes.
fail	failCallback	Error callback.
options	NotificationOptions	Android only: Optional object with options. Set field writeConfigDescriptor to false to disable automatic writing of notification or indication descriptor value. This is useful if full control of writing the config descriptor is needed.

static

fromUtf8(a)

Converts an ArrayBuffer containing UTF-8 data to a JavaScript String.

Parameter

Name	Type	Optional	Description
a	ArrayBuffer

Returns: string

static

getBondedDevices(success, fail, options)

Get a list of bonded devices.

Example

evothings.ble.getBondedDevices(
    function(devices)
    {
        console.log('Bonded devices: ' + JSON.stringify(devices));
    },
    function(errorCode)
    {
        console.log('getBondedDevices error: ' + errorCode);
    },
    { serviceUUIDs: ['0000180a-0000-1000-8000-00805f9b34fb'] });

Parameters

Name	Type	Description
success	getBondedDevicesCallback	Callback function called with list of bonded devices.
fail	failCallback	Error callback function.
options	GetBondedDevicesOptions	Mandatory object that specifies service UUIDs to search for.

static

getBondState(device, success, fail, options)

Get bond state for device.

Example

evothings.ble.getBondState(
    { address: uuidOrMacAddress }
    function(state)
    {
        console.log('Bond state: ' + state);
    },
    function(errorCode)
    {
        console.log('getBondState error: ' + errorCode);
    },
    { serviceUUID: '0000180a-0000-1000-8000-00805f9b34fb' });

Parameters

Name	Type	Description
device	DeviceInfo	Object with address of the device (a device object that contains just the address field may be used). On iOS the address is a UUID, on Android the address is a MAC address. This value can be found in the device objects obtained using startScan().
success	getBondStateCallback	Callback function called with the current bond state (a string).
fail	failCallback	Error callback function.
options	GetBondStateOptions	Mandatory on iOS where a serviceUUID of the device must be specified. Ignored on Android.

static

getCanonicalUUID(uuid)

Returns a canonical UUID.

Code adopted from the Bleat library by Rob Moran (@thegecko), see this file: https://github.com/thegecko/bleat/blob/master/dist/bluetooth.helpers.js

Parameter

Name	Type	Optional	Description
uuid	(string or number)		The UUID to turn into canonical form.

Returns: Canonical UUID.

static

getCharacteristic(device, uuid)

Get a characteristic object of a service. (Characteristics within a service that share the same UUID (rare case) must be retrieved by manually traversing the characteristics array of the service. This function will return the first characteristic found, which may not be the one you want. Note that this is a rare case.)

Parameters

Name	Type	Optional	Description
device	Service		Service object.
uuid	string		UUID of characteristic to get.

static

getDescriptor(characteristic, uuid)

Get a descriptor object of a characteristic.

Parameters

Name	Type	Optional	Description
characteristic	Characteristic		Characteristic object.
uuid	string		UUID of descriptor to get.

static

getService(device, uuid)

Get a service object from a device or array.

Parameters

Name	Type	Optional	Description
device	DeviceInfo		Device object (or array of Service objects).
uuid	string		UUID of service to get.

static

parseAdvertisementData(device)

Parse the advertisement data in the scan record. If device already has AdvertisementData, does nothing. If device instead has scanRecord, creates AdvertisementData. See AdvertisementData for reference documentation.

Parameter

Name	Type	Optional	Description
device	DeviceInfo		Device object.

static

readAllServiceData(device, success, fail)

Read all services, and associated characteristics and descriptors for the given device.

This function is an easy-to-use wrapper of the low-level functions ble.services(), ble.characteristics() and ble.descriptors().

Parameters

Name	Type	Description
device	DeviceInfo	Device object or device handle from connectCallback.
success	serviceCallback	Called with array of Service objects. Those Service objects each have an additional field "characteristics", which is an array of Characteristic objects. Those Characteristic objects each have an additional field "descriptors", which is an array of Descriptor objects.
fail	failCallback	Error callback.

static

readCharacteristic(device, characteristic, success, fail)

Reads a characteristic's value from a remote device.

Example

evothings.ble.readCharacteristic(
    device,
    characteristic,
    function(data)
    {
      console.log('characteristic data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
      console.log('readCharacteristic error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
characteristic	Characteristic	Characteristic object or handle from characteristicCallback.
success	dataCallback
fail	failCallback

static

readDescriptor(device, descriptor, success, fail)

Reads a descriptor's value from a remote device.

Example

evothings.ble.readDescriptor(
  device,
  descriptor,
  function(data)
  {
    console.log('descriptor data: ' + evothings.ble.fromUtf8(data));
  },
  function(errorCode)
  {
    console.log('readDescriptor error: ' + errorCode);
  });

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
descriptor	Descriptor	Descriptor object or handle from descriptorCallback.
success	dataCallback
fail	failCallback

static

readServiceData(device, success, fail, options)

Read services, and associated characteristics and descriptors for the given device. Which services to read may be specified in the options parameter. Leaving out the options parameter with read all services.

Parameters

Name	Type	Description
device	DeviceInfo	Device object or device handle from connectCallback.
success	serviceCallback	Called with array of Service objects. Those Service objects each have an additional field "characteristics", which is an array of Characteristic objects. Those Characteristic objects each have an additional field "descriptors", which is an array of Descriptor objects.
fail	failCallback	Error callback.
options	ReadServiceDataOptions	Object with options (optional parameter). If left out, all services are read.

static

reset(success, fail)

Resets the device's Bluetooth system. This is useful on some buggy devices where BLE functions stops responding until reset. Available on Android 4.3+. This function takes 3-5 seconds to reset BLE. On iOS this function stops any ongoing scan operation and disconnects all connected devices.

Parameters

Name	Type	Optional	Description
success	emptyCallback
fail	failCallback

static

rssi(device, success, fail)

Fetch the remote device's RSSI (signal strength).

Example

evothings.ble.rssi(
    device,
    function(rssi)
    {
      console.log('rssi: ' + rssi);
    },
    function(errorCode)
    {
      console.log('rssi error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
success	rssiCallback
fail	failCallback

static

services(device, success, fail)

Fetch information about a remote device's services.

Example

evothings.ble.services(
    device,
    function(services)
    {
      console.log('found services:');
      for (var i = 0; i < services.length; i++)
      {
        var service = services[i];
        console.log('  service:');
        console.log('    ' + service.handle);
        console.log('    ' + service.uuid);
        console.log('    ' + service.serviceType);
      }
    },
    function(errorCode)
    {
      console.log('services error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
success	serviceCallback	Called with array of Service objects.
fail	failCallback

static

startScan(success, fail, options)

Start scanning for devices.

An array of service UUID strings may be given in the options object parameter. One or more service UUIDs must be specified for iOS background scanning to work.

Found devices and errors are reported to the supplied callback functions.

Will keep scanning until you call stopScan().

To conserve energy, call stopScan() as soon as you've found the device you're looking for.

Call stopScan() before calling startScan() again.

Example

// Scan for all services.
  evothings.ble.startScan(
      function(device)
      {
          console.log('startScan found device named: ' + device.name);
      },
      function(errorCode)
      {
          console.log('startScan error: ' + errorCode);
      }
  );

  // Scan for specific service (Eddystone Service UUID).
  evothings.ble.startScan(
      function(device)
      {
          console.log('startScan found device named: ' + device.name);
      },
      function(errorCode)
      {
          console.log('startScan error: ' + errorCode);
      },
      { serviceUUIDs: ['0000feaa-0000-1000-8000-00805f9b34fb'] }
  );

Parameters

Name	Type	Description
success	scanCallback	Success callback, called repeatedly for each found device.
fail	failCallback	Error callback.
options	ScanOptions	Optional object with options. Set field serviceUUIDs to an array of service UUIDs to scan for. Set field parseAdvertisementData to false to disable automatic parsing of advertisement data.

static

stopScan()

Stops scanning for devices.

Example

evothings.ble.stopScan();

static

testCharConversion(i, success)

i is an integer. It is converted to byte and put in an array[1]. The array is returned.

assert(string.charCodeAt(0) == i).

Parameters

Name	Type	Optional	Description
i	number
success	dataCallback		Called every time the value changes.

static

toUtf8(s)

Converts a JavaScript String to an Uint8Array containing UTF-8 data.

Parameter

Name	Type	Optional	Description
s	string

Returns: Uint8Array

static

unbond(device, success, fail)

Unbond with device. This function does nothing on iOS.

Example

evothings.ble.unbond(
    { address: uuidOrMacAddress }
    function(newState)
    {
        console.log('New bond state: ' + newState);
    },
    function(errorCode)
    {
        console.log('bond error: ' + errorCode);
    });

Parameters

Name	Type	Description
device	DeviceInfo	Object with address of the device (a device object that contains just the address field may be used). On iOS the address is a UUID, on Android the address is a MAC address. This value can be found in the device objects obtained using startScan().
success	unbondCallback	Callback function called with the new bond state (a string). On iOS the result is always 'unknown'.
fail	failCallback	Error callback function.

static

writeCharacteristic(device, characteristic, data, success, fail)

Write a characteristic's value to the remote device.

Writes with response, the remote device sends back a confirmation message. This is safe but slower than writing without response.

Example

TODO: Add example.

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
characteristic	Characteristic	Characteristic object or handle from characteristicCallback.
data	ArrayBufferView	The value to be written.
success	emptyCallback	Called when the remote device has confirmed the write.
fail	failCallback	Called if the operation fails.

static

writeCharacteristicWithoutResponse(device, characteristic, data, success, fail)

Write a characteristic's value without response.

Asks the remote device to NOT send a confirmation message. This may be used for increased data throughput.

If the application needs to ensure data integrity, a separate safety protocol would be required. Design of such protocols is beyond the scope of this document.

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
characteristic	Characteristic	Characteristic object or handle from characteristicCallback.
data	ArrayBufferView	The value to be written.
success	emptyCallback	Called when the data has been sent.
fail	failCallback	Called if the operation fails.

static

writeDescriptor(device, descriptor, data, success, fail)

Write a descriptor's value to a remote device.

Example

TODO: Add example.

Parameters

Name	Type	Description
device	DeviceInfo	Device object or a device handle from connectCallback.
descriptor	Descriptor	Descriptor object or handle from descriptorCallback.
data	ArrayBufferView	The value to be written.
success	emptyCallback
fail	failCallback

Abstract types

inner

AdvertiseData Object

Describes BLE advertisement data.

Data size is limited to 31 bytes. Each property set consumes some bytes. If too much data is added, startAdvertise will fail with "ADVERTISE_FAILED_DATA_TOO_LARGE" or something similar.

All properties are optional. UUIDs must be formatted according to RFC 4122, all lowercase. Normally, UUIDs take up 16 bytes. However, UUIDs that use the Bluetooth Base format can be compressed to 4 or 2 bytes. The Bluetooth Base UUID is "00000000-0000-1000-8000-00805f9b34fb". For 2 bytes, use this format, where "x" is any hexadecimal digit: "0000xxxx-0000-1000-8000-00805f9b34fb". For 4 bytes, use this format: "xxxxxxxx-0000-1000-8000-00805f9b34fb".

Properties

Name	Type	Description
includeDeviceName	boolean	If true, the device's Bluetooth name is added to the advertisement. The name is set by the user in the device's Settings. The name cannot be changed by the app. The default is false.
includeTxPowerLevel	boolean	If true, the txPowerLevel found in AdvertiseSettings is added to the advertisement. The default is false.
serviceUUIDs	Array	Array of strings. Each string is the UUID of a service that should be available in the device's GattServer.
serviceData	Object	Map of string to string. Each key is a service UUID. The value is base64-encoded data associated with the service.
manufacturerData	Object	Map of int to string. Each key is a manufacturer ID. Manufacturer IDs are assigned by the Bluetooth Special Interest Group. The value is base64-encoded data associated with the manufacturer.

inner

AdvertisementData Object

Information extracted from a scanRecord. Some or all of the fields may be undefined. This varies between BLE devices. Depending on OS version and BLE device, additional fields, not documented here, may be present.

Properties

Name	Type	Description
kCBAdvDataLocalName	string	The device's name. Might or might not be equal to DeviceInfo.name. iOS caches DeviceInfo.name which means if the name is changed on the device, the new name might not be visible. kCBAdvDataLocalName is not cached and is therefore safer to use, when available.
kCBAdvDataTxPowerLevel	number	Transmission power level as advertised by the device.
kCBAdvDataChannel	number	A positive integer, the BLE channel on which the device listens for connections. Ignore this number.
kCBAdvDataIsConnectable	boolean	True if the device accepts connections. False if it doesn't.
kCBAdvDataServiceUUIDs	array	Array of strings, the UUIDs of services advertised by the device. Formatted according to RFC 4122, all lowercase.
kCBAdvDataServiceData	object	Dictionary of strings to strings. The keys are service UUIDs. The values are base-64-encoded binary data.
kCBAdvDataManufacturerData	string	Base-64-encoded binary data. This field is used by BLE devices to advertise custom data that don't fit into any of the other fields.

inner

AdvertiseSettings Object

Describes a BLE advertisement.

All the properties are optional, except broadcastData.

Properties

Name	Type	Description
advertiseMode	string	ADVERTISE_MODE_LOW_POWER, ADVERTISE_MODE_BALANCED, or ADVERTISE_MODE_LOW_LATENCY. The default is ADVERTISE_MODE_LOW_POWER.
connectable	boolean	Advertise as connectable or not. Has no bearing on whether the device is actually connectable. The default is true if there is a GattServer running, false if there isn't.
timeoutMillis	int	Advertising time limit. May not exceed 180000 milliseconds. A value of 0 will disable the time limit. The default is 0.
txPowerLevel	string	ADVERTISE_TX_POWER_ULTRA_LOW, ADVERTISE_TX_POWER_LOW, ADVERTISE_TX_POWER_MEDIUM or ADVERTISE_TX_POWER_HIGH. The default is ADVERTISE_TX_POWER_MEDIUM.
broadcastData	AdvertiseData	The data which will be broadcast. Passive scanners will see this data.
scanResponseData	AdvertiseData	The data with which the device will respond to active scans. Should be an extension to the broadcastData; should not contain the same data.

inner

bondCallback(newState)

Success callback function for bond. On iOS the bond state returned will always be 'unknown' (this function is a NOP on iOS). Note that bonding on Android may fail and then this function is called with 'unbonded' as the new state.

Parameter

Name	Type	Optional	Description
newState	string		The new bond state of the device. Possible values are: 'bonded' (Android), 'bonding' (Android), 'unbonded' (Android), and 'unknown' (iOS).

inner

Characteristic Object

Describes a GATT characteristic.

Properties

Name	Type	Description
handle	number
uuid	string	Formatted according to RFC 4122, all lowercase.
permissions	module:cordova-plugin-ble.permission	Bitmask of zero or more permission flags.
properties	module:cordova-plugin-ble.property	Bitmask of zero or more property flags.
writeType	module:cordova-plugin-ble.writeType

inner

characteristicCallback(characteristics)

Parameter

Name	Type	Optional	Description
characteristics	Array		Array of Characteristic objects.

inner

connectCallback(info)

Will be called whenever the device's connection state changes.

Parameter

Name	Type	Optional	Description
info	ConnectInfo

inner

ConnectInfo Object

Info about connection events and state.

Properties

Name	Type	Description
device	DeviceInfo	The device object is available in the ConnectInfo if a device object was passed to connect; passing the address string to connect is allowed for backwards compatibility, but this does not set the device field.
deviceHandle	number	Handle to the device.
state	number	One of the module:cordova-plugin-ble.connectionState keys.

inner

connectionStateChangeCallback(deviceHandle, connected)

This function is a part of GattSettings and is called when a remote device connects to, or disconnects from, your server.

Parameters

Name	Type	Optional	Description
deviceHandle	int		Will be used in other callbacks.
connected	boolean		If true, the device just connected, and the handle is now valid for use in close() and other functions. If false, it just disconnected, and the handle is now invalid for use in close() and other functions.

inner

ConnectOptions Object

Options for connectToDevice.

Properties

Name	Type	Optional	Description
discoverServices	boolean		Set to false to disable automatic service discovery. Default is true.
serviceUUIDs	array		Array with service UUID strings for services to discover (optional). If empty or null, all services are read, this is the default.

inner

dataCallback(data)

Parameter

Name	Type	Optional	Description
data	ArrayBuffer

inner

Descriptor Object

Describes a GATT descriptor.

Properties

Name	Type	Description
handle	number
uuid	string	Formatted according to RFC 4122, all lowercase.
permissions	module:cordova-plugin-ble.permission	Bitmask of zero or more permission flags.

inner

descriptorCallback(descriptors)

Parameter

Name	Type	Optional	Description
descriptors	Array		Array of Descriptor objects.

inner

DeviceInfo Object

Info about a BLE device.

Properties

Name	Type	Description
address	string	Uniquely identifies the device. Pass this to connect(). The form of the address depends on the host platform.
rssi	number	A negative integer, the signal strength in decibels.
name	string	The device's name, or nil.
scanRecord	string	Base64-encoded binary data. Its meaning is device-specific. Not available on iOS.
advertisementData	AdvertisementData	Object containing some of the data from the scanRecord. Available natively on iOS. Available on Android by parsing the scanRecord, which is implemented in the library EasyBLE: https://github.com/evothings/evothings-libraries/blob/master/libs/evothings/easyble/easyble.js.

inner

emptyCallback()

inner

failCallback(errorString)

This function is called when an operation fails.

Parameter

Name	Type	Optional	Description
errorString	string		A human-readable string that describes the error that occurred.

inner

GattCharacteristic Object

Describes a GATT characteristic.

Properties

Name	Type	Description
handle	int	Optional. Used in notify(). If set, must be unique among all other GattCharacteristic handles.
uuid	string	Formatted according to RFC 4122, all lowercase.
permissions	module:cordova-plugin-ble.permission	Bitmask of zero or more permission flags.
properties	property	Bitmask of zero or more property flags.
writeType	writeType
onReadRequest	readRequestCallback
onWriteRequest	writeRequestCallback
descriptors	Array	Optional. An array of GattDescriptor objects.

inner

GattDescriptor Object

Describes a GATT descriptor.

Properties

Name	Type	Description
uuid	string	Formatted according to RFC 4122, all lowercase.
permissions	module:cordova-plugin-ble.permission	Bitmask of zero or more permission flags.
onReadRequest	readRequestCallback
onWriteRequest	writeRequestCallback

inner

GattService Object

Describes a GATT service.

Properties

Name	Type	Description
uuid	string	Formatted according to RFC 4122, all lowercase.
type	serviceType
characteristics	Array	An array of GattCharacteristic objects.

inner

GattSettings Object

Describes a GATT server.

Properties

Name	Type	Optional	Description
services	Array		An array of GattService objects.
onConnectionStateChange	connectionStateChangeCallback

inner

getBondedDevicesCallback(devices)

Success callback function for getBondedDevices. Called with array of bonded devices (may be empty).

Parameter

Name	Type	Optional	Description
devices	Array		Array of {DeviceInfo} objects. Note that only fields name and address are available in the device info object.

inner

GetBondedDevicesOptions Object

Options for getBondedDevices.

Parameter

Name	Type	Optional	Description
serviceUUIDs	array		Array with or or more service UUID strings (mandatory).

inner

getBondStateCallback(state)

Success callback function for getBondState.

Parameter

Name	Type	Optional	Description
state	string		The bond state of the device. Possible values are: 'bonded', 'bonding' (Android only), 'unbonded', and 'unknown'.

inner

GetBondStateOptions Object

Options for getBondState.

Parameter

Name	Type	Optional	Description
serviceUUID	string		String with service UUID (mandatory on iOS, ignored on Android).

inner

NotificationOptions Object

Options for enableNotification and disableNotification.

Property

Name	Type	Optional	Description
writeConfigDescriptor	boolean		set to false to disable automatic writing of the notification or indication descriptor. This is useful if full control of writing the config descriptor is needed.

inner

readRequestCallback(deviceHandle, requestId)

Called when a remote device asks to read a characteristic or descriptor. You must call sendResponse() to complete the request.

Parameters

Name	Type	Optional	Description
deviceHandle	int
requestId	int

inner

ReadServiceDataOptions Object

Options for readServiceData.

Property

Name	Type	Optional	Description
serviceUUIDs	array		Array with service UUID strings for services to discover (optional). If absent or null, all services are read, this is the default.

inner

rssiCallback(rssi)

This function is called with an RSSI value.

Parameter

Name	Type	Optional	Description
rssi	number		A negative integer, the signal strength in decibels.

inner

scanCallback(device)

This function is a parameter to startScan() and is called when a new device is discovered.

Parameter

Name	Type	Optional	Description
device	DeviceInfo

inner

ScanOptions Object

Options for startScan.

Parameter

Name	Type	Optional	Description
serviceUUIDs	array		Array with service UUID strings (optional). On iOS multiple UUIDs are scanned for using logical OR operator, any UUID that matches any of the UUIDs adverticed by the device will count as a match. On Android, multiple UUIDs are scanned for using AND logic, the device must advertise all of the given UUIDs to produce a match. (The matching logic will be unified in future versions of the plugin.) When providing one service UUID, behaviour is the same on Android and iOS. Learning out this parameter or setting it to null, will scan for all devices, regardless of advertised services.

Property

Name	Type	Optional	Description
parseAdvertisementData	boolean		Set to false to disable automatic parsing of advertisement data from the scan record. Default is true.

inner

Service Object

Describes a GATT service.

Properties

Name	Type	Description
handle	number
uuid	string	Formatted according to RFC 4122, all lowercase.
type	module:cordova-plugin-ble.serviceType

inner

serviceCallback(services)

Parameter

Name	Type	Optional	Description
services	Array		Array of Service objects.

inner

unbondCallback(newState)

Success callback function for unbond. On iOS the bond state returned will always be 'unknown' (this function is a NOP on iOS). On Anroid the result should be 'unbonded', but other states are possible. Check the state to make sure the function was successful.

Parameter

Name	Type	Optional	Description
newState	string		The new bond state of the device. Possible values are: 'unbonded' (Android), 'bonding' (Android), 'bonded' (Android), and 'unknown' (iOS).

inner

writeRequestCallback(deviceHandle, requestId, data)

Called when a remote device asks to write a characteristic or descriptor. You must call sendResponse() to complete the request.

Parameters

Name	Type	Optional	Description
deviceHandle	int
requestId	int
data	ArrayBuffer