Bluetooth-Bindings

Overview

W3C Web of Things (WoT) compatible Protocol Bindings for Bluetooth LE to use with node-wot.

This package provides a Bluetooth LE client factory that plugs into a WoT Servient enabling consumption of Things over GATT.

Installation

npm install wot-ble-client-factory @node-wot/core

Minimal Setup

GATT

const { Servient } = require("@node-wot/core");
const { BluetoothGATTClientFactory } = require("wot-ble-client-factory");

const servient = new Servient();
servient.addClientFactory(new BluetoothGATTClientFactory());

GAP

const { Servient } = require("@node-wot/core");
const { BluetoothGapClientFactory } = require("wot-ble-client-factory");

const servient = new Servient();
servient.addClientFactory(new BluetoothGapClientFactory());

Check the examples folder for more complete Thing Descriptions.

To enable debug logs run with this command:

DEBUG=binding-Bluetooth node example.js

Protocol Specifier

The protocol prefix handled by this binding is gatt:// and gap://.

Getting Started

If you want to build this package locally:

git clone [email protected]:wintechis/Bluetooth-Bindings.git
cd Bluetooth-Bindings
npm install
npm run build

For local development you can use yalc:

./publish_yalc.sh

If the library code has been updated run:

./update_yalc.sh

For installation in your project use:

npm install
yalc add wot-ble-client-factory

Documentation

Default Mappings

In order to align a new protocol into the WoT context, the required abstract WoT operations must first be mapped to the concrete operations of the new protocol. A distinction must be made between the two GATT methods write and write-without-response. Both are capable of writing WoT resources, but the two methods differ in that write expects a confirmation message from the server after a write operation, while write-without-response requires no such confirmation. Thus the GATT method chosen depends on the implementation of the attribute in the GATT server.

| WoT Operation | BLE GATT Method | | -------------- | -------------------------- | | readproperty | read | | writeproperty | write / write-w/o-response | | invokeaction | write / write-w/o-response | | subscribeevent | notify |

URL Format

The introduced URI scheme is suitable for uniquely identifying resources on GATT servers, and allows users to interact with the desired GATT characteristic. It has the following structure:

gatt://<MAC>/<service>/<characteristic>

or

gap://<MAC>

with the following meaning:

• gatt or gap Identification of the transfer protocol
• <MAC> MAC address of the Bluetooth device
• <service> GATT service containing the characteristic
• <characteristic> GATT characteristic to interact with

Media Type

The encoding/decoding of transfered data is done using a suitable codec. Currently, there is no fitting combination of content type and codec that meets all requirements for the binary data transmitted by Bluetooth LE. The closest is application/octet-stream, but unfortunately, this codec only fulfills parts of our requirements and can not encode or decode all binary data transmitted via Bluetooth LE. For the Bluetooth LE bindings, we chose the new, non-standard subtype x.binary-data-stream and defined an associated codec that interprets the binary data using a newly created vocabulary.

Binary Data Ontology

The Binary Data Ontology (bdo) is intended to provide maximum flexibility and describe all kinds of binary data. We want to use the bdo ontology to describe the data transmitted by Bluetooth LE devices, even those that do not comply with the Bluetooth standard. The terms of the vocabulary are in our use case only useful within the properties, actions, or events parts of a Thing Description because they contain information about the data that is needed in the codec associated with application/x.binary-data-stream.

| Vocabulary term | Description | Assignment | Type | Default Value | | --------------- | ------------------------------------------------ | ------------------------------- | ------- | ---------------- | | bdo:bytelength | Number of octets in the data | required | integer | None | | bdo:signed | Indicates if the data is signed | required | boolean | false | | bdo:byteOrder | Byte order of the binary data | required | string | bdo:littleEndian | | bdo:scale | Scale of received integer value (multiplicaiton) | optional | float | 1.0 | | bdo:valueAdd | Scale of received integer value (addition) | optional | float | 0 | | bdo:offset | Offset in number of octets | optional | integer | 0 | | bdo:pattern | The byte pattern of the binary data | optional | string | None | | bdo:variables | Description of the variables in bdo:pattern | required if bdo:pattern is used | --- | None |

Simple Bluetooth Ontology

The communication and metadata of a Bluetooth Low Energy device is described using the Simple Bluetooth Ontology with preferred prefix sbo. This information is optional and not required.

Citation

If you use this project in your research or applications, please cite it as:

@article{freund2022wotble,
  title   = {Applying the Web of Things abstraction to Bluetooth Low Energy communication},
  author  = {Freund, Michael and Dorsch, Rene and Harth, Andreas},
  journal = {arXiv preprint arXiv:2211.12934},
  year    = {2022}
}