namespace static

evothings.easyble

Source: evothings-libraries/libs/evothings/easyble/easyble.js:17

Library for making BLE programming easier.

An all-in-one file with this library and helper libraries included is available in file easyble.dist.js. Include this file in index.html (recommended).

If you include easyble.js rather than easyble.dist.js it is safe practise to call function evothings.scriptsLoaded to ensure dependent libraries are loaded before calling functions in this library (in this case you also need to have the dependent library folders).

Namespaces

EasyBLEDevice

error

Property

printObject

Methods

closeConnectedDevices()
filterDevicesByService(services)

reportDeviceOnce(reportOnce)
reset()

startScan(success, fail[, options])
stopScan()

Abstract types

AdvertisementData
connectCallback(device)
dataCallback(data)
emptyCallback()

failCallback(errorString)
NotificationOptions
ReadServicesOptions
rssiCallback(rssi)

scanCallback(device)
ScanOptions
servicesCallback(device)

Namespaces

EasyBLEDevice

error

Property

public static

printObject

Prints and object for debugging purposes.

Methods

static

closeConnectedDevices()

Disconnect and close all connected BLE devices.

Example

evothings.easyble.closeConnectedDevices();

public static

filterDevicesByService(services)

Set to an Array of UUID strings to enable filtering of devices found by startScan().

Parameter

Name	Type	Optional	Description
services			Array of UUID strings. Set to false to disable filtering. The default is no filtering. An empty array will cause no devices to be reported.

public static

reportDeviceOnce(reportOnce)

Deprecated. Set whether to report devices once or continuously during scan. The default is to report continously.

Parameter

Name	Type	Optional	Description
reportOnce	boolean		Set to true to report found devices only once. Set to false to report continuously.

Deprecated: Use the options parameter evothings.easyble.ScanOptions in function evothings.easyble.startScan.

public static

reset()

Reset the BLE hardware. Can be time consuming.

public static

startScan(success, fail[, options])

Start scanning for devices. Note that the optional parameter serviceUUIDs has been deprecated. Please use the options parmameter evothings.easyble.ScanOptions instead to specify any specific service UUID to scan for.

Example

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

  // Scan for specific service.
  evothings.easyble.startScan(
      function(device)
      {
          console.log('Found device named: ' + device.name);
      },
      function(errorCode)
      {
          console.log('startScan error: ' + errorCode);
      },
      // Eddystone service UUID specified in options.
      { serviceUUIDs: ['0000FEAA-0000-1000-8000-00805F9B34FB'] }
  );

Parameters

Name	Type	Optional	Description
success	evothings.easyble.scanCallback		Success function called when a device is found. Format: success(evothings.easyble.EasyBLEDevice).
fail	evothings.easyble.failCallback		Error callback: fail(error).
options	evothings.easyble.ScanOptions	Yes	Object with scan options.

static

stopScan()

Stop scanning for devices.

Example

evothings.easyble.stopScan();

Abstract types

static

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. Use this field rather than device.name, since on iOS the device name is cached and changes are not reflected in device.name.
kCBAdvDataTxPowerLevel	number	Transmission power level as advertised by the device.
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.

static

connectCallback(device)

Called when successfully connected to a device.

Parameter

Name	Type	Optional	Description
device	evothings.easyble.EasyBLEDevice		EasyBLE devices object.

static

dataCallback(data)

Function when data is available.

Parameter

Name	Type	Optional	Description
data	ArrayBuffer		The data is an array buffer. Use an ArrayBufferView to access the data.

static

emptyCallback()

This callback indicates that an operation was successful, without specifying and additional information.

static

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.

static

NotificationOptions Object

Options object for functions evothings.easyble.EasyBLEDevice#enableNotification and evothings.easyble.EasyBLEDevice#disableNotification.

Property

Name	Type	Optional	Description
writeConfigDescriptor	boolean		Supported on Android, ignored on iOS. Set to false to disable automatic writing of notification or indication config descriptor value. This is useful in special cases when full control of writing the config descriptor is needed.

static

ReadServicesOptions Object

Options object for function evothings.easyble.EasyBLEDevice#readServices

Property

Name	Type	Optional	Description
serviceUUIDs	array		Array of service UUID strings.

static

rssiCallback(rssi)

Called with RSSI value.

Parameter

Name	Type	Optional	Description
rssi	number		A negative integer, the signal strength in decibels. This value may be 127 which indicates an unknown value.

static

scanCallback(device)

Called during scanning when a BLE device is found.

Parameter

Name	Type	Optional	Description
device	evothings.easyble.EasyBLEDevice		EasyBLE device object found during scanning.

static

ScanOptions Object

Options for function {evothings.easyble.startScan}

Properties

Name	Type	Optional	Description
serviceUUIDs	array		Array with strings of service UUIDs to scan for. When providing one service UUID, behaviour is the same on Android and iOS, when providing multiple UUIDs behaviour differs between platforms. 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. Leaving out this parameter or setting it to null will scan for all devices regardless of advertised services (default behaviour).
allowDuplicates	boolean		If true same device will be reported repeatedly during scanning, if false it will only be reported once. Default is true.

static

servicesCallback(device)

Called when services are successfully read.

Parameter

Name	Type	Optional	Description
device	evothings.easyble.EasyBLEDevice		EasyBLE devices object.