Namespace: EasyBLEDevice

Methods

public

close()

Close the device. This disconnects from the BLE device.

Example

device.close();

public

connect(success, fail)

Connect to the device.

Example

device.connect(
    function(device)
    {
      console.log('device connected.');
      // Read services here.
    },
    function(errorCode)
    {
      console.log('connect error: ' + errorCode);
    });

Parameters

Name	Type	Optional	Description
success	evothings.easyble.connectCallback		Called when connected: success(device).
fail	evothings.easyble.failCallback		Called on error and if a disconnect happens. Format: error(errorMessage)

public

disableNotification(serviceUUID, serviceUUID, characteristicUUID, success, fail[, options])

Unsubscribe from characteristic updates to stop notifications.

On Android you can disable automatic write of notify/indicate and write the configuration descriptor yourself, supply an options object as last parameter, see example below.

Example

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

Parameters

Name	Type	Optional	Description
serviceUUID	string		UUID of service that has the given characteristic (previous versions of this library allowed leaving out the service UUID, this is unsafe practice and has been deprecated, always specify the service UUID).
serviceUUID			UUID of service that has the given characteristic.
characteristicUUID			UUID of characteristic to unsubscribe from.
success	evothings.easyble.emptyCallback		Success callback: success()
fail	evothings.easyble.failCallback		Error callback: fail(error)
options	evothings.easyble.NotificationOptions	Yes	Optional settings.

disableServiceNotification()

Deprecated. Use function evothings.easyble.EasyBLEDevice#disableNotification

Deprecated

public

enableNotification(serviceUUID, characteristicUUID, success, fail[, options])

Subscribe to value updates of a characteristic. The success function will be called repeatedly whenever there is new data available.

On Android you can disable automatic write of notify/indicate and write the configuration descriptor yourself, supply an options object as last parameter, see example below.

Example

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

// Turn off automatic writing of the config descriptor (for special cases):
device.enableNotification(
  serviceUUID,
  characteristicUUID,
  function(data)
  {
    console.log('characteristic data: ' + evothings.ble.fromUtf8(data));
  },
  function(errorCode)
  {
    console.log('enableNotification error: ' + errorCode);
  },
  { writeConfigDescriptor: false });

Parameters

Name	Type	Optional	Description
serviceUUID	string		UUID of service that has the given characteristic (previous versions of this library allowed leaving out the service UUID, this is unsafe practice and has been deprecated, always specify the service UUID).
characteristicUUID	string		UUID of characteristic to subscribe to.
success	evothings.easyble.dataCallback		Success callback: success(data).
fail	evothings.easyble.failCallback		Error callback: fail(error).
options	evothings.easyble.NotificationOptions	Yes	Optional settings.

enableServiceNotification()

Deprecated. Use function evothings.easyble.EasyBLEDevice#enableNotification

Deprecated

public

getName()

Get device name. If there is a device name present in advertisement data, this is returned. Otherwise the value of the device.name field is returned. Note that iOS caches the device.name field, but not the name in advertisement data. If you change name of the device, it is more reliable to use the field in advertisement data (this name is set in the device firmware code).

Example

var name = device.getName();

Returns: Name of the device.

public

hasName(name)

Match device name. First checks the device name present in advertisement data, if not present checks device.name field.

Example

device.hasName('MyBLEDevice');

Parameter

Name	Type	Optional	Description
name			The name to match.

Returns: true if device has the given name, false if not.

public

isConnected()

Check if device is connected.

Example

var connected = device.isConnected();

Returns: true if connected, false if not connected.

public

readCharacteristic(serviceUUID, characteristicUUID, success, fail)

Read value of characteristic.

Example

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

Parameters

Name	Type	Description
serviceUUID	string	UUID of service that has the given characteristic (previous versions of this library allowed leaving out the service UUID, this is unsafe practice and has been deprecated, always specify the service UUID).
characteristicUUID	string	UUID of characteristic to read.
success	evothings.easyble.dataCallback	Success callback: success(data).
fail	evothings.easyble.failCallback	Error callback: fail(error).

public

readDescriptor(serviceUUID, characteristicUUID, descriptorUUID, success, fail)

Read value of descriptor.

Example

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

Parameters

Name	Type	Description
serviceUUID	string	UUID of service that has the given characteristic (previous versions of this library allowed leaving out the service UUID, this is unsafe practice and has been deprecated, always specify the service UUID).
characteristicUUID	string	UUID of characteristic for descriptor.
descriptorUUID	string	UUID of descriptor to read.
success	evothings.easyble.dataCallback	Success callback: success(data).
fail	evothings.easyble.failCallback	Error callback: fail(error).

public

readRSSI(success, fail)

Read devices RSSI. Device must be connected.

Parameters

Name	Type	Optional	Description
success	evothings.easyble.rssiCallback		Callback called with RSSI value: success(rssi).
fail	evothings.easyble.failCallback		Called on error: fail(error).

readServiceCharacteristic()

Deprecated. Use function evothings.easyble.EasyBLEDevice#readCharacteristic

Deprecated

readServiceDescriptor()

Deprecated. Use function evothings.easyble.EasyBLEDevice#readDescriptor

Deprecated

public

readServices(success, fail[, options])

Read services, characteristics and descriptors for the specified service UUIDs. Services must be read be able to access characteristics and descriptors. Call this function before reading and writing characteristics/descriptors. (This function took an array of service UUIDs as first parameter in previous versions of this library, that is still supported for backwards compatibility but has ben deprecated.)

Example

// Read all services
  device.readServices(
    function(device)
    {
      console.log('Services available.');
      // Read/write/enable notifications here.
    },
    function(errorCode)
    {
      console.log('readServices error: ' + errorCode);
    });

  // Read specific service
  device.readServices(
    function(device)
    {
      console.log('Services available.');
      // Read/write/enable notifications here.
    },
    function(errorCode)
    {
      console.log('readServices error: ' + errorCode);
    },
    { serviceUUIDs: ['19b10000-e8f2-537e-4f6c-d104768a1214'] });

Parameters

Name	Type	Optional	Description
success	evothings.easyble.servicesCallback		Called when services are read: success(device)
fail	evothings.easyble.failCallback		error callback: error(errorMessage)
options	evothings.easyble.ReadServicesOptions	Yes	Optional object with setting that allow specification of which services to read. If left out, all services and related characteristics and descriptors are read (this can be time-consuming compared to reading selected services).

public

writeCharacteristic(serviceUUID, characteristicUUID, value, success, fail)

Write value of characteristic.

Example

device.writeCharacteristic(
    serviceUUID,
    characteristicUUID,
    new Uint8Array([1]), // Write byte with value 1.
    function()
    {
      console.log('characteristic written.');
    },
    function(errorCode)
    {
      console.log('writeCharacteristic error: ' + errorCode);
    });

Parameters

Name	Type	Description
serviceUUID	string	UUID of service that has the given characteristic (previous versions of this library allowed leaving out the service UUID, this is unsafe practice and has been deprecated, always specify the service UUID).
characteristicUUID	string	UUID of characteristic to write to.
value	ArrayBufferView	Value to write.
success	evothings.easyble.emptyCallback	Success callback: success().
fail	evothings.easyble.failCallback	Error callback: fail(error).

public

writeCharacteristicWithoutResponse(serviceUUID, characteristicUUID, value, success, fail)

Write value of a characteristic for a specific service without response. This faster but not as fail safe as writing with response. Asks the remote device to NOT send a confirmation message. Experimental, implemented on Android.

Example

device.writeCharacteristicWithoutResponse(
    serviceUUID,
    characteristicUUID,
    new Uint8Array([1]), // Write byte with value 1.
    function()
    {
      console.log('data sent.');
    },
    function(errorCode)
    {
      console.log('writeCharacteristicWithoutResponse error: ' + errorCode);
    });

Parameters

Name	Type	Description
serviceUUID	string	UUID of service that has the characteristic.
characteristicUUID	string	UUID of characteristic to write to.
value	ArrayBufferView	Value to write.
success	evothings.easyble.emptyCallback	Success callback: success().
fail	evothings.easyble.failCallback	Error callback: fail(error).

public

writeDescriptor(serviceUUID, characteristicUUID, descriptorUUID, value, success, fail)

Write value of descriptor.

Example

device.writeDescriptor(
    serviceUUID,
    characteristicUUID,
    descriptorUUID,
    new Uint8Array([1]), // Write byte with value 1.
    function()
    {
      console.log('descriptor written.');
    },
    function(errorCode)
    {
      console.log('writeDescriptor error: ' + errorCode);
    });

Parameters

Name	Type	Description
serviceUUID	string	UUID of service that has the given characteristic (previous versions of this library allowed leaving out the service UUID, this is unsafe practice and has been deprecated, always specify the service UUID).
characteristicUUID	string	UUID of characteristic for descriptor.
descriptorUUID	string	UUID of descriptor to write to.
value	ArrayBufferView	Value to write.
success	evothings.easyble.emptyCallback	Success callback: success().
fail	evothings.easyble.failCallback	Error callback: fail(error).

writeServiceCharacteristic()

Deprecated. Use function evothings.easyble.EasyBLEDevice#writeCharacteristic

Deprecated

writeServiceCharacteristicWithoutResponse()

Deprecated. Use function evothings.easyble.EasyBLEDevice#writeCharacteristicWithoutResponse

Deprecated

writeServiceDescriptor()

Deprecated. Use function evothings.easyble.EasyBLEDevice#writeDescriptor

Deprecated