A node.js BLE (Bluetooth low energy) central module.
Want to implement a peripheral? Checkout bleno
Note: Mac OS X and Linux are currently the only supported OSes, and are still under development. Other platforms will be developed later on (see Roadmap below).
OS X
- install Xcode
Linux (Ubuntu)
- Kernel version 3.6 or above
sudo apt-get install bluetooth bluez-utils libbluetooth-dev- Run as
sudoorroot
npm install noble
var noble = require('noble');
Actions
Start scanning:
noble.startScanning(); // any service UUID, no duplicates
noble.startScanning([], true); // any service UUID, allow duplicates
var serviceUUIDs = ["<service UUID 1>", ...]; // default: [] => all
var allowDuplicates = <false|true>; // default: false
noble.startScanning(serviceUUIDs, allowDuplicates); // particular UUID's
Stop scanning:
noble.stopScanning();
Peripheral connect:
peripheral.connect([callback(error)]);
Peripheral disconnect or cancel pending connection:
peripheral.disconnect([callback(error)]);
Peripheral update RSSI
peripheral.updateRssi([callback(error, rssi)]);
Peripheral discover services
peripheral.discoverServices(); // any service UUID
var serviceUUIDs = ["<service UUID 1>", ...];
peripheral.discoverServices(serviceUUIDs[, callback(error, services)]); // particular UUID's
Peripheral discover all services and characteristics
peripheral.discoverAllServicesAndCharacteristics([callback(error, services, characteristics));
Peripheral discover some services and characteristics
var serviceUUIDs = ["<service UUID 1>", ...];
var characteristicUUIDs = ["<characteristic UUID 1>", ...];
peripheral.discoverSomeServicesAndCharacteristics(serviceUUIDs, characteristicUUIDs, [callback(error, services, characteristics));
Service discover included services
service.discoverIncludedServices(); // any service UUID
var serviceUUIDs = ["<service UUID 1>", ...];
service.discoverIncludedServices(serviceUUIDs[, callback(error, includedServiceUuids)]); // particular UUID's
Service discover characteristics
service.discoverCharacteristics() // any characteristic UUID
var characteristicUUIDs = ["<characteristic UUID 1>", ...];
service.discoverCharacteristics(characteristicUUIDs[, callback(error, characteristics)]); // particular UUID's
Characteristic read
characteristic.read([callback(error, data)]);
Characteristic write
characteristic.write(data, notify[, callback(error)]); // data is a buffer, notify is true|false
Characteristic broadcast
characteristic.broadcast(broadcast[, callback(error)]); // broadcast is true|false
Characteristic notify
characteristic.notify(notify[, callback(error)]); // notify is true|false
- use for characteristics with notifiy or indicate properties
Characteristic discover descriptors
characteristic.discoverDescriptors([callback(error, descriptors)]);
Descriptor read value
descriptor.readValue([callback(error, data)]);
Descriptor write value
descriptor.writeValue(data[, callback(error)]); // data is a buffer
Events
Adapter state change:
state = <"unknown" | "resetting" | "unsupported" | "unauthorized" | "poweredOff" | "poweredOn">
noble.on('stateChange', callback(state));
Scan started:
noble.on('scanStart', callback);
Scan stopped:
noble.on('scanStop', callback);
Peripheral discovered:
peripheral = {
uuid: "<uuid>",
advertisement: {
localName: "<name>",
txPowerLevel: <int>,
serviceUuids: ["<service UUID>", ...],
manufacturerData: <Buffer>,
serviceData: [
{
uuid: "<service UUID>"
data: <Buffer>
},
...
]
},
rssi: <rssi>
};
noble.on('discover', callback(peripheral));
Peripheral connected:
peripheral.on('connect', callback);
Peripheral disconnected:
peripheral.on('disconnect', callback);
Peripheral RSSI update
peripheral.on('rssiUpdate', callback(rssi));
Peripheral services discovered
peripheral.on('servicesDiscover', callback(services));
Service included services discovered
service.on('includedServicesDiscover', callback(includedServiceUuids));
Service characteristics discovered
characteristic = {
uuid: "<uuid>",
// properties: 'broadcast', 'read', 'writeWithoutResponse', 'write', 'notify', 'indicate', 'authenticatedSignedWrites', 'extendedProperties'
properties: [...]
};
service.on('characteristicsDiscover', callback(characteristics));
Characteristic read
characteristic.on('read', callback(data, isNotification));
Characteristic write
characteristic.on('write', withoutResponse, callback());
Characteristic broadcast
characteristic.on('broadcast', callback(state));
Characteristic notify
characteristic.on('notify', callback(state));
Characteristic descriptors discovered
descriptor = {
uuid: '<uuid>'
};
characteristic.on('descriptorsDiscover', callback(descriptors));
Descriptor value read
descriptor.on('valueRead', data);
Descriptor value write
descriptor.on('valueWrite');
Read handle
peripheral.readHandle(handle, callback(error, data));
Write handle
peripheral.writeHandle(handle, data, withoutResponse, callback(error));
Must be run with sudo or as root user.
hci0 is used by default to override set the NOBLE_HCI_DEVICE_ID environment variable to the interface number.
Example, specify hci1:
sudo NOBLE_HCI_DEVICE_ID=1 node <your file>.js
-
Mac OS X:
Adapter state (unknown | reseting | unsupported | unauthorized | off | on)ScanstartScanningservice UUID'sallow duplicates
stopScanning
Peripheraldiscoveredconnectdisconnect/cancel connectupdate RSSIservicesdiscoverdisover includeddiscover characteristics for services
characteristicsreadwriteset broadcast valueset notify/indicate valuedescriptorsdiscoverreadwrite
handlereadwritewith response- without response
- error handling
-
Linux
Adapter state (unsupported | unauthorized | off | on)ScanstartScanningservice UUID'sallow duplicates
stopScanning
Peripheraldiscoveredconnectpublic addressrandom address
disconnect/cancel connectupdate RSSIservicesdiscoverfilter by uuid
discover includeddiscover characteristics for servicesfilter by uuid
characteristicsreadwriteset broadcast valueset notify/indicate valuedescriptorsdiscoverreadwrite
handlereadwritewith responsewithout response
- error handling
-
Windows
- TDB (most likely Windows 8 only)