obniz-noble
v2.2.0
Published
A Node.js BLE (Bluetooth Low Energy) central library for obniz.
Downloads
6
Readme
obniz-noble
A Node.js BLE (Bluetooth Low Energy) central module for obniz.
Want to implement a peripheral? Checkout obniz-bleno
How to convert from noble
- Install obniz-noble and uninstall noble.
npm install obniz-noble
npm uninstall noble
- Change require method for noble
//before
const noble = require("noble");
//after
const obnizNoble = require("obniz-noble");
const noble = obnizNoble("OBNIZ_ID_HERE");
- Setup obniz device and run your script!
Install & Usage
For node.js
npm install obniz-noble
var obnizNoble = require('obniz-noble')
var noble = obnizNoble("OBNIZ_ID_HERE") // or var noble = obnizNoble("OBNIZ_ID_HERE", {obnizOptions})
For browser
<script src="https://unpkg.com/obniz-noble/obniz-noble.js" crossorigin="anonymous"></script>
<script>
var noble = obnizNoble("OBNIZ_ID_HERE") // or var noble = obnizNoble("OBNIZ_ID_HERE", {obnizOptions})
...
</script>
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[, callback(error)]); // particular UUID's
NOTE: noble.state
must be poweredOn
before scanning is started. noble.on('stateChange', callback(state));
can be used register for state change events.
Stop scanning
noble.stopScanning();
Peripheral
Connect
peripheral.connect([callback(error)]);
Disconnect or cancel pending connection
peripheral.disconnect([callback(error)]);
Update RSSI
peripheral.updateRssi([callback(error, rssi)]);
Discover services
peripheral.discoverServices(); // any service UUID
var serviceUUIDs = ["<service UUID 1>", ...];
peripheral.discoverServices(serviceUUIDs[, callback(error, services)]); // particular UUID's
Discover all services and characteristics
peripheral.discoverAllServicesAndCharacteristics([callback(error, services, characteristics)]);
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
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)]);
Write
characteristic.write(data, withoutResponse[, callback(error)]); // data is a buffer, withoutResponse is true|false
withoutResponse
:false
: send a write request, used with "write" characteristic propertytrue
: send a write command, used with "write without response" characteristic property
Broadcast
characteristic.broadcast(broadcast[, callback(error)]); // broadcast is true|false
Subscribe
characteristic.subscribe([callback(error)]);
- subscribe to a characteristic, triggers
'data'
events when peripheral sends an notification or indication - use for characteristics with notify or indicate properties
Unsubscribe
characteristic.unsubscribe([callback(error)]);
- unsubscribe to a characteristic
- use for characteristics with notify or indicate properties
Discover descriptors
characteristic.discoverDescriptors([callback(error, descriptors)]);
Read value
descriptor.readValue([callback(error, data)]);
Write value
descriptor.writeValue(data[, callback(error)]); // data is a buffer
Handle
Read
peripheral.readHandle(handle, callback(error, data));
Write
peripheral.writeHandle(handle, data, withoutResponse, callback(error));
Events
See Node.js EventEmitter docs for more info. on API's.
Adapter state change
state = <"unknown" | "resetting" | "unsupported" | "unauthorized" | "poweredOff" | "poweredOn">
noble.on('stateChange', callback(state));
Scan started:
noble.on('scanStart', callback);
The event is emitted when scanning is started or if another application enables scanning or changes scanning settings.
Scan stopped
noble.on('scanStop', callback);
The event is emitted when scanning is stopped or if another application stops scanning.
Peripheral discovered
peripheral = {
id: "<id>",
address: "<BT address">, // Bluetooth Address of device, or 'unknown' if not known
addressType: "<BT address type>", // Bluetooth Address type (public, random), or 'unknown' if not known
connectable: <connectable>, // true or false, or undefined if not known
advertisement: {
localName: "<name>",
txPowerLevel: <int>,
serviceUuids: ["<service UUID>", ...],
serviceSolicitationUuid: ["<service solicitation UUID>", ...],
manufacturerData: <Buffer>,
serviceData: [
{
uuid: "<service UUID>"
data: <Buffer>
},
...
]
},
rssi: <rssi>
};
noble.on('discover', callback(peripheral));
Note: on OS X the address will be set to 'unknown' if the device has not been connected previously.
Warnings
noble.on('warning', callback(message));
Peripheral
Connected
peripheral.once('connect', callback);
Disconnected:
peripheral.once('disconnect', callback);
RSSI update
peripheral.once('rssiUpdate', callback(rssi));
Services discovered
peripheral.once('servicesDiscover', callback(services));
Service
Included services discovered
service.once('includedServicesDiscover', callback(includedServiceUuids));
Characteristics discovered
characteristic = {
uuid: "<uuid>",
// properties: 'broadcast', 'read', 'writeWithoutResponse', 'write', 'notify', 'indicate', 'authenticatedSignedWrites', 'extendedProperties'
properties: [...]
};
service.once('characteristicsDiscover', callback(characteristics));
Characteristic
Data
Emitted when characteristic read has completed, result of characteristic.read(...)
or characteristic value has been updated by peripheral via notification or indication - after having been enabled with notify(true[, callback(error)])
.
characteristic.on('data', callback(data, isNotification));
characteristic.once('read', callback(data, isNotification)); // legacy
Note: isNotification
event parameter value MAY be undefined
depending on platform support. The parameter is deprecated after version 1.8.1, and not supported when on macOS High Sierra and later.
Write
Emitted when characteristic write has completed, result of characteristic.write(...)
.
characteristic.once('write', withoutResponse, callback());
Broadcast
Emitted when characteristic broadcast state changes, result of characteristic.broadcast(...)
.
characteristic.once('broadcast', callback(state));
Notify
Emitted when characteristic notification state changes, result of characteristic.notify(...)
.
characteristic.once('notify', callback(state));
Descriptors discovered
descriptor = {
uuid: '<uuid>'
};
characteristic.once('descriptorsDiscover', callback(descriptors));
Descriptor
Value read
descriptor.once('valueRead', data);
Value write
descriptor.once('valueWrite');