@genee/bluez
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.4-10 • Public • Published

    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

    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<void>

    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<void>

    Registers a Profile Bluetooth Service.

    For available options see Bluez Docs.

    registerAgent(agent: Agent, capabilities: string): Promise<void>

    Registers a Agent required for pairing.

    For available options see Bluez Docs.

    getDevice(address: string): Promise<Device|null>

    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<Device|null>

    Search for a Device given a custom filter function

    getAdapter(name?: string): Promise<Device>

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

    findAdapter(filterCb: (props: AdapterProps) => boolean): Promise<Adapter|null>

    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<Service | null>

    Get a GATT Service of the Device.

    Service

    For available methods and properties see Bluez Docs.

    getCharacteristic(uuid: string): Promise<Characteristic | null>

    Get a GATT Characteristic of the Service.

    Characteristic

    For available methods and properties see Bluez Docs.

    getDescriptor(uuid: string): Promise<Descriptor | null>

    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

    Install

    npm i @genee/bluez

    DownloadsWeekly Downloads

    32

    Version

    0.4.4-10

    License

    MIT

    Unpacked Size

    83.6 kB

    Total Files

    17

    Last publish

    Collaborators

    • iamfat
    • genee_wanglei
    • jinxhao18