Documentation

Namespace: EasyBLEDevice

.easyble. EasyBLEDevice

This is the BLE DeviceInfo object obtained by calling evothings.ble.startScan, with additional properties and functions added. Internal properties are prefixed with two underscores. Properties are also added to the Characteristic and Descriptor objects.

Methods

<static> hasName(name)

Match device name.
Parameters:
Name Type Description
name The name to match.
Returns:
true if device has the given name, false if not.
Example
device.hasName('MyBLEDevice');

close()

Close the device. This disconnects from the BLE device.
Example
device.close();

connect(success, fail)

Connect to the device.
Parameters:
Name Type 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)
Example
device.connect(
    function(device)
    {
      console.log('BLE device connected.');
      // TODO: Read services here.
    },
    function(errorCode)
    {
      console.log('BLE connect error: ' + errorCode);
    });

disableNotification(characteristicUUID, success, fail)

Unsubscribe from characteristic updates to stop notifications.
Parameters:
Name Type Description
characteristicUUID UUID of characteristic to unsubscribe from
success evothings.easyble.emptyCallback Success callback: success()
fail evothings.easyble.failCallback Error callback: fail(error)
Example
device.disableNotification(
   characteristicUUID,
   function()
   {
     console.log('BLE characteristic notification disabled');
   },
   function(errorCode)
   {
     console.log('BLE disableNotification error: ' + errorCode);
   });

enableNotification(characteristicUUID, success, fail)

Subscribe to characteristic value updates. The success function will be called repeatedly whenever there is new data available.
Parameters:
Name Type Description
characteristicUUID string UUID of characteristic to subscribe to.
success evothings.easyble.dataCallback Success callback: success(data).
fail evothings.easyble.failCallback Error callback: fail(error).
Example
device.enableNotification(
  characteristicUUID,
  function(data)
  {
    console.log('BLE characteristic data: ' + evothings.ble.fromUtf8(data));
  },
  function(errorCode)
  {
    console.log('BLE enableNotification error: ' + errorCode);
  });

readCharacteristic(characteristicUUID, success, fail)

Read value of characteristic.
Parameters:
Name Type Description
characteristicUUID string UUID of characteristic to read.
success evothings.easyble.dataCallback Success callback: success(data).
fail evothings.easyble.failCallback Error callback: fail(error).
Example
device.readCharacteristic(
    characteristicUUID,
    function(data)
    {
      console.log('BLE characteristic data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
      console.log('BLE readCharacteristic error: ' + errorCode);
    });

readDescriptor(characteristicUUID, descriptorUUID, success, fail)

Read value of descriptor.
Parameters:
Name Type Description
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).
Example
device.readDescriptor(
    characteristicUUID,
    descriptorUUID,
    function(data)
    {
      console.log('BLE descriptor data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
      console.log('BLE readDescriptor error: ' + errorCode);
    });

readRSSI(success, fail)

Read devices RSSI. Device must be connected.
Parameters:
Name Type Description
success evothings.easyble.rssiCallback Called with RSSI value: success(rssi).
fail evothings.easyble.failCallback Called on error: fail(error).

readServiceCharacteristic(serviceUUID, characteristicUUID, success, fail)

Read value of a specific characteristic.
Parameters:
Name Type Description
serviceUUID string UUID of service in which the characteristic is found.
characteristicUUID string UUID of characteristic to read.
success evothings.easyble.dataCallback Success callback: success(data).
fail evothings.easyble.failCallback Error callback: fail(error).
Example
device.readServiceCharacteristic(
    serviceUUID,
    characteristicUUID,
    function(data)
    {
      console.log('BLE characteristic data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
      console.log('BLE readServiceCharacteristic error: ' + errorCode);
    });

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

Read value of a specific descriptor.
Parameters:
Name Type Description
serviceUUID string UUID of service in which the characteristic is found.
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).
Example
device.readServiceDescriptor(
    serviceUUID,
    characteristicUUID,
    descriptorUUID,
    function(data)
    {
      console.log('BLE descriptor data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
      console.log('BLE readServiceDescriptor error: ' + errorCode);
    });

readServices(serviceUUIDs, success, fail)

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.
Parameters:
Name Type Description
serviceUUIDs array of UUID strings, if null all services are read (this can be time-consuming compared to reading selected services).
success evothings.easyble.servicesCallback Called when services are read: success(device).
fail evothings.easyble.failCallback error callback: error(errorMessage)
Example
device.readServices(
    null, // Read all services
    function(device)
    {
      console.log('BLE Services available.');
      // TODO: Read/write/enable notifications here.
    },
    function(errorCode)
    {
      console.log('BLE readServices error: ' + errorCode);
    });

writeCharacteristic(characteristicUUID, value, success, fail)

Write value of characteristic.
Parameters:
Name Type Description
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).
Example
device.writeCharacteristic(
    characteristicUUID,
    new Uint8Array([1]), // Write byte with value 1.
    function()
    {
      console.log('BLE characteristic written.');
    },
    function(errorCode)
    {
      console.log('BLE writeCharacteristic error: ' + errorCode);
    });

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

Write value of descriptor.
Parameters:
Name Type Description
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).
Example
device.writeDescriptor(
    characteristicUUID,
    descriptorUUID,
    new Uint8Array([1]), // Write byte with value 1.
    function()
    {
      console.log('BLE descriptor written.');
    },
    function(errorCode)
    {
      console.log('BLE writeDescriptor error: ' + errorCode);
    });

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

Write value of a specific characteristic.
Parameters:
Name Type Description
serviceUUID string UUID of service in which the characteristic is found.
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).
Example
device.writeServiceCharacteristic(
    serviceUUID,
    characteristicUUID,
    new Uint8Array([1]), // Write byte with value 1.
    function()
    {
      console.log('BLE characteristic written.');
    },
    function(errorCode)
    {
      console.log('BLE writeServiceCharacteristic error: ' + errorCode);
    });

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

Write value of a specific descriptor.
Parameters:
Name Type Description
serviceUUID string UUID of service in which the characteristic is found.
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).
Example
device.writeServiceDescriptor(
    serviceUUID,
    characteristicUUID,
    descriptorUUID,
    new Uint8Array([1]), // Write byte with value 1.
    function()
    {
      console.log('BLE descriptor written.');
    },
    function(errorCode)
    {
      console.log('BLE writeServiceDescriptor error: ' + errorCode);
    });