caf_iot_gatt/proxy_iot_gatt

A proxy to access BLE GATT services.

The typical workflow is:

  1. findServices to find devices that export a particular service. If reading advertised data is all it is needed, stop here.

  2. Otherwise, pick one of them. Use findCharacteristics to create a connnection and discover its characteristics.

  3. Read/Write/Subscribe/Unsubscribe to these characteristics.

  4. Disconnect, and if needed, go back to step 2 with a different device.

Note that to maintain compatibility with current WebBluetooth API we are not discovering all BLE services in a device. The service id needs to be known beforehand.

Source:

Extends

Methods

(static) newInstance()

Source:

Factory method to access GATT services.

compareId(x, y) → {boolean}

Source:

Utility function to compare characteristic ids.

Parameters:
Name Type Description
x string | number

A characteristic id to compare.
y string | number

Another characteristic id to compare.
Returns:

True if they map to the same characteristic.

Type
boolean

dirtyRead(characteristic) → {Promise.<Buffer>}

Source:

Dirty reads the value of a GATT characteristic, i.e., breaking the transaction.

The read timed out, rejecting the promise with an error, if it takes longer than RWCharactTimeout msec.

Parameters:
Name Type Description
characteristic noble.characteristic

A characteristic to read.
Returns:

A promise with the read value.

Type
Promise.<Buffer>

disconnect(device, delayopt, cbopt) → {Promise.<null>|null}

Source:

Disconnects from a device.

The method findCharacteristics creates the connection, and keeps it open to read/write/subscribe characteristics.

Parameters:
Name Type Attributes Description
device noble.peripheral

A device to disconnect.
delay number <optional>

An optional delay in msec before disconnecting.
cb cbType <optional>

An optional callback to wait for disconnection.
Returns:

A promise to wait for disconnection if there was no callback, or null otherwise.

Type
Promise.<null> | null

findCharacteristics(serviceId, device, charIdsopt, cbopt) → {Promise.<CharactInfo>|null}

Source:

Finds GATT characteristics of a service.

Implicitly stops scanning for services.

Parameters:
Name Type Attributes Description
serviceId string

A service identifier.
device noble.peripheral

A device returned by findServices.
charIds Array.<string> <optional>

Optional identifiers for the characteristics. If undefined, all the characteristics will be returned. Otherwise, the order in the array response will match the order of this array, and an error will be propagated if any is missing.
cb cbType <optional>

A standard callback returning an error, possibly due to a timeout, or an object of type CharactInfo:

{service: noble.service, device: noble.peripheral, characteristics: Array.<noble.characteristic>}

where service.uuid is the original identifier.
Returns:

A promise with the characteristics if no callback was provided, or null otherwise.

Type
Promise.<CharactInfo> | null

findServices(service, handlerMethodName, namePrefix)

Source:

Finds BLE devices that export a GATT service or a collection of GATT services.

The provided method will be called with each device exporting the service. To stop the scanning call stopFindServices or findCharacteristics.

Parameters:
Name Type Description
service string | Array.<string>

A service(s) id. They will get converted to lower case due to noble package requirements.
handlerMethodName string

The method called when a device is found. The type is signature is function(service, device, cb) where:

  • service type is string or array of strings
  • device type is noble.peripheral (see https://github.com/sandeepmistry/noble.git)
  • cb type is caf.cb

or async function(service, device) returning an array with an error/data pair.
namePrefix string | null

An optional name prefix to filter devices. This is needed if no GATT services are advertised. If the value is not null, this call will no longer filter based on service ids.

findServicesWeb(service, handlerMethodName, clickable, confirm, namePrefix) → {Promise.<null>}

Source:

Finds BLE devices using the Web Bluetooth API that export a GATT service or a collection of GATT services.

This method is needed in the browser since the Web Bluetooth API requires a user click before starting the search. It needs access to the DOM, so it only works in the browser.

A returned promise allows the client to wait for user selection.

The provided method will be called with the selected device exporting the service(s).

Parameters:
Name Type Description
service string | Array.<string>

A service(s) id.
handlerMethodName string

The method called when a device is found. The type is signature is function(service, device, cb) where:

  • service type is string or array of strings
  • device type is noble.peripheral (see https://github.com/sandeepmistry/noble.git)
  • cb type is caf.cb

or async function(service, device) returning an array with an error/data pair.
clickable string

The id of an HTML button to start the search.
confirm string

The id of an HTML confirmation message.
namePrefix string | null

An optional name prefix to filter devices. This is needed if no GATT services are advertised. If the value is not null, this call will no longer filter based on service ids.
Returns:

A promise to wait for selection.

Type
Promise.<null>

matchServiceId(services, serviceId) → {noble.service|null}

Source:

Utility function to select a service by comparing ids.

The type noble.service is an object that contains the field uuid.

Parameters:
Name Type Description
services Array.<noble.service>

An array of gatt services.
serviceId string | number

A service id to compare.
Returns:

A service in services with matching id or null if not found.

Type
noble.service | null

read(characteristic, handlerMethodName)

Source:

Reads the value of a GATT characteristic.

Parameters:
Name Type Description
characteristic noble.characteristic

A characteristic to read.
handlerMethodName string

The method called with the characteristic value.

The type is signature is function(charact, value, cb) where:

  • charact type is noble.characteristic
  • value type is Buffer
  • cb type is caf.cb

or async function(charact, value) returning an array with an error/data pair.

reset() → {Promise.<Array.<null>>}

Source:

Disconnects from all connections.

Returns:

A promise to wait for disconnection.

Type
Promise.<Array.<null>>

stopFindServices()

Source:

Stops scanning for services.

subscribe(characteristic, handlerMethodName) → {Promise.<null>}

Source:

Subscribes to a GATT characteristic.

This operation times out, rejecting the promise with an error, if it takes longer than RWCharactTimeout msec.

Parameters:
Name Type Description
characteristic noble.characteristic

A characteristic to read.
handlerMethodName string

The method called with the characteristic value.

The method type signature is function(charact, value, cb) where:

  • charact type is noble.characteristic
  • value type is Buffer
  • cb type is caf.cb

or async function(charact, value) returning an array with an error/data pair.
Returns:

A promise to wait for completion or notify a timeout error.

Type
Promise.<null>

unsubscribe(characteristic) → {Promise.<null>}

Source:

Unsubscribes to a GATT characteristic.

This operation times out, rejecting the promise with an error, if it takes longer than RWCharactTimeout msec.

Parameters:
Name Type Description
characteristic noble.characteristic

A characteristic to unsubscribe.
Returns:

A promise to wait for completion or notify a timeout error.

Type
Promise.<null>

write(characteristic, value, withoutResponseopt) → {Promise.<null>}

Source:

Writes the value of a GATT characteristic.

This write times out, rejecting the promise with an error, if it takes longer than RWCharactTimeout msec.

Parameters:
Name Type Attributes Description
characteristic noble.characteristic

A characteristic to write.
value Buffer

The new value.
withoutResponse boolean <optional>

Uses GATT "write without response" whenever possible. Web Bluetooth API currently ignores it.
Returns:

A promise to wait for completion or notify a timeout error.

Type
Promise.<null>