@genee/bluez

Bluez D-Bus
===========

Easy to use Node.js Bluez5 D-Bus library.

Install

Required Packages for dbus:
- libglib2.0-dev
- libdbus-1-dev

``
npm install bluez
`

Usage

`js
const Bluez = require('bluez');
const bluetooth = new Bluez();

// Register callback for new devices
bluetooth.on('device', async (address, props) => {
console.log("[NEW] Device:", address, props.Name);
const dev = await bluetooth.getDevice(address);
dev.on("PropertiesChanged", (props) => {
console.log("[CHG] Device:", address, props);
});
});

bluetooth.init().then(async () => {
// listen on first bluetooth adapter
const adapter = await bluetooth.getAdapter();
await adapter.StartDiscovery();
console.log("Discovering");
}).catch(console.error);
`

Custom Agents and Profiles can be implemented by extending Agent / Profile base classes.
Then use bluez.registerAgent(agent, capability) and bluez.registerProfile(profile, options) to activate them.

#### Permissions

Make sure the user that is running the node process has the necessary permissions for Bluetooth and System-DBus.
- on some Systems there is a bluetooth group.
- also check AppArmor and Polkit permissions.

#### Examples

Have a look at the examples for more detailed usage information.

#### Tested with

- Bluez 5.50 Ubuntu 18.04
- Bluez 5.53 Ubuntu 20.04
- Bluez 5.48 Debian Stretch
- Bluez 5.50 Debian Buster
- Bluez 5.54 Debian Sid

Older Bluez version should work, but might miss some functions.
However I can not recommend using GATT with Bluez < 5.48.

Migration

#### 0.3.x -> 0.4

- Characteristic Values are now always Buffers
- Characteristic, Descriptor and Service properties where changed to functions
- RawFdSocket was removed and replaced by bluetooth-socket module
- Bluez.registerDummyAgent was renamed to Bluez.registerStaticKeyAgent which takes a pin code as argument
- Bluez.getAllDevicesAddresses was renamed to Bluez.getAllDevicesProps which returns all properties not only the address.

API

This package mostly reflects the Bluez-DBus API. You can find its documentation here.

#### Bluez

Contains most management functions.

##### constructor(options?: BluezOptions): Bluez

options:
- bus: DBus | undefined: an existing DBus connection. Default: create new connection
- service: DBus.Service | string | null | undefined: service where to register default Profiles / Agents. Default: null (connection local service)
- objectPath: string | undefined: object path where to register default Profiles / Agents. Default: "/org/node/bluez"


##### init(): Promise

Initializes DBus and interfaces. MUST be called bevor any bluetooth interaction is done.
Attach device event listeners first, because calling init() will emit device events for paired devices.

##### registerProfile(profile: Profile, options: ProfileOptions): Promise

Registers a Profile Bluetooth Service.

For available options see Bluez Docs.

##### registerAgent(agent: Agent, capabilities: string): Promise

Registers a Agent required for pairing.

For available options see Bluez Docs.

##### getDevice(address: string): Promise

Returns a Device for a given address.

address can be a adress in format XX:XX:XX:XX:XX:XX or XX_XX_XX_XX_XX_XX or /org/bluez/hciX/dev_XX_XX_XX_XX_XX_XX


##### findDevice(filterCb: (props: DeviceProps) => boolean): Promise

Search for a Device given a custom filter function

##### getAdapter(name?: string): Promise

Returns a Adapter either by name or of not supplied the first one available.

##### findAdapter(filterCb: (props: AdapterProps) => boolean): Promise

Search for a Adapter given a custom filter function


##### Events

###### on("device", address: string, props: DeviceProperties)

Emitted if a device was discovered.

Note that for paired devices this will be emitted no matter if the devices are in range or not.

#### Adapter

An Adapter represents a local Bluetooth adapter.

##### constructor(interface: DBus.Interface): Adapter

interface is the DBus Interface corresponding the the Adapter.

Should not be called directly. Use Bluez.getAdapter().


For available methods and properties see Bluez Docs.

#### Agent

An Agent is required for pairing with devices.

This default implementation accepts every pair request and has the passkey 1234

##### constructor(bluez: Bluez, DBusObject: DBus.ServiceObject): Agent

DBusObject is the DBus Object under witch the interface should be registerd.


For available methods and properties see Bluez Docs.

#### Device

A Device represents a remote Bluetooth device.

For available methods and properties see Bluez Docs.

##### constructor(interface: DBus.Interface): Device

interface is the DBus Interface corresponding the the Device.

Should not be called directly. Use Bluez.getDevice().

##### getService(uuid: string): Promise

Get a GATT Service of the Device.

#### Service

For available methods and properties see Bluez Docs.

##### getCharacteristic(uuid: string): Promise

Get a GATT Characteristic of the Service.

#### Characteristic

For available methods and properties see Bluez Docs.

##### getDescriptor(uuid: string): Promise

Get a GATT Descriptor of the Characteristic.

#### Descriptor

For available methods and properties see Bluez Docs.

#### Profile

A Profile is a service provided by this Bluetooth device.

##### constructor(bluez: Bluez, DBusObject: DBus.ServiceObject): Profile

DBusObject is the DBus Object under witch the interface should be registerd.

For available methods and properties see Bluez Docs.

#### SerialProfile

A Profile implementation for Serial communication.

##### constructor(bluez: Bluez, DBusObject: DBus.ServiceObject, listener: (device: Device, socket: RawFdSocket)=>void): SerialProfile`

listener is a callback that is called for each new connection to the Profile. Its socket parameter is the established channel between the two devices.

TODO

- Complete the API docs
- More examples
- Tests
- GATT Peripheral Services