Complete BLE(Central) Module

[nova0821]

Complete BLE(Central) Module

Reference to node.js ble module - noble under MIT License.
(https://github.com/sandeepmistry/noble)

• JS API (ble)
  • ble.startScanning()
  • ble.stopScanning()
• JS Event (ble)
  • ble.on('stateChange')
  • ble.on('scanStart')
  • ble.on('scanStop')
  • ble.on('discover'): return peripheral JS object with callback function.

peripheral = {
  id: "<id>",
  address: "<BT address">,
  addressType: "<BT address type>", // Bluetooth Address type (public, random, or unknown) 
  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>
};

ble.on('discover', callback(peripheral));

• JS API (peripheral)
  • peripheral.connect()
  • peripheral.disconnect()
  • peripheral.updateRssi()
  • peripheral.discoverServices(): return services JS object with callback function.
  • peripheral.discoverAllServicesAndCharacteristics() : return services and characteristic.
  • peripheral.readHandle()
  • peripheral.writeHandle()
• JS Event (peripheral)
  • peripheral.once('connect')
  • peripheral.once('disconnect')
  • peripheral.once('rssiUpdate')
  • peripheral.once('servicesDiscover')
• JS API (service)
  • service.discoverIncludedServices()
  • service.discoverCharacteristics()
• JS Event (service)
  • service.once('includedServicesDiscover')
  • service.once('characteristicsDiscover')

characteristic = {
  uuid: "<uuid>",
   // properties: 'broadcast', 'read', 'writeWithoutResponse', 'write', 'notify', 'indicate', 'authenticatedSignedWrites', 'extendedProperties'
  properties: [...]
};

service.once('characteristicsDiscover', callback(characteristics));

• JS API (characteristic)
  • characteristic.read()
  • characteristic.write()
  • characteristic.broadcast()
  • characteristic.subscribe()
  • characteristic.unsubscribe()
  • characteristic.discoverDescriptors()
• JS Event (characteristic)
  • characteristic.on('data')
  • characteristic.once('read')
  • characteristic.once('write')
  • characteristic.once('broadcast')
  • characteristic.once('notify')
  • characteristic.once('descriptorsDiscover'

descriptor = {
  uuid: '<uuid>'
};

characteristic.once('descriptorsDiscover', callback(descriptors));

• JS API (descriptor)
  • descriptor.readValue()
  • descriptor.writeValue()
• JS Event (descriptor)
  • descriptor.once('valueRead')
  • descriptor.once('valueWrite')
• x86 linux
• arm-linux on Raspberry Pi
• arm-nuttx on STM32F4-discovery
• Create document

[gudbooy]

@nova0821
I have thoroughly read the reference node.js module (called noble), however the internal JavaScript APIs (noble-Linux Version) have Glib-DBus (IPC) and Bluez (Bluetooth Native Daemon) dependencies.
I think that the BLE module on IoT.js should minimize such dependencies.
Thus, I think the best candidate is to implement socket interface with Bluez instead of DBus.
Could you let me know what is the best way to implement ?

[nova0821]

@gudbooy This document describes about Javascript API Interface. We didn't decide yet which libraries are used for BLE implementation. However, IoT.js has the feature which use the different native part for each platforms, so I think it is ok to use any libraries on each platforms if there is no issue(like license issue). As you know, in Node.js, it also implements the native part for each platforms. Of course, we will try to reduce the size of the code and optimize the performance.

If you have any detail idea to implement the native part of BLE on specific platform, please let me know.

[esevan]

@nova0821 Do you have any progress on BLE Central? As I checked on your private fokred repository, only ble peripheral is being implemented. If it is, could you assign this project to me for a week? I want to try to implement this based on bluez for raspberry-pi2 version.

[nova0821]

@esevan Yes, I am working on BLE peripheral now.(ble branch on my repo) - no progress on BLE central module.

If you want to try to implement BLE central module, you can try it! Welcome!!

Ubuntu and Raspbian should support BLE module(both central and peripheral). On Ubuntu, it will run with USB Bluetooth 4.0 dongle. Both platform have bluez library, so I guess, it will work with same codes.

We need js and c native codes for BLE central, and also need the API document.

I already use module name ble for BLE peripheral. Do you have any idea about module name for BLE central and peripheral? I think bleno and noble are not good, because user can't know it means central and peripheral.

[esevan]

@nova0821 I've also tried to come up with an idea about the module name of peripheral and central. According to blueZ HCI library (See example here), scanning and advertising APIs have same prefix hci_le_ or le_ which does not represent if it is used as central or peripheral.
I agree with that the users may be confused with same module name "ble", but why don't we go with same module and different APIs at this time? Since ble is a concept which includes central and peripheral, the users can select the APIs by their application settings (as same way in blueZ). We can also go with same way as Net module. Both central and peripheral are under the module.

var ble = require('ble');
var central = ble.Central();
...
central.startScanning();

var ble = require('ble');
var peripheral = ble.Peripheral();
...
peripheral.startAdvertising('service1', [service1.uuid])

[nova0821]

@esevan I also thought to using one module name ble for central and peripheral. However, it is not a good idea because IoT.js is focused to small device - we need to reduce code size.

Since we already have excluding modules which are not needed in compile time, I think we need to separate BLE central and peripheral. Also, there is no use-case to use both module in same time.

How do you think of temporarily naming module BLE central as ble-central?

[esevan]

@nova0821 I agree. I'm going with ble-central

[esevan]

We're going to implement the ble-central module as described below.

The ble-central is based on noble npm packages on Node.js.
Entire parts of noble are actually implemented in JS language with several dependent modules, e.g. bluetooth-hci-socket, websocket, and xpc.

In case of our implementation, however, we're planning to cut those dependencies in JS code by implementing major parts of noble as C code. It means that we're developing blueZ communication code, which is platform-dependent, as C code instead of JS code. If anyone wants to add other platform-dependent codes, then you can add the code under the C binder of ble-central.

Any advice for the ble-central architecture will be very welcome.

p.s. Since ble-central is originated from noble in major, please let us know how to handle the license (MIT) specifying problem. I couldn't get clear solution from #326.

APIs from left to right
//ble-central
startScanning()
stopScanning()
//peripheral
connect()
disconnect()
updateRssi()
discoverServices()
readHandle()
writeHandle()
//service
discoverIncludedServices()
discoverCharacteristics()
//characteristic
read()
write()
broadcast()
notify()
discoverDescriptors()
//descriptor
readValue()
writeValue()

Events from right to left
//ble-central
stateChange
addressChange
scanStart
scanStop
discover
//peripheral
connect
disconnect
rssiUpdate
servicesDiscover
handleRead
handleWrite
handleNotify
//service
includedServicesDiscover
characteristicsDiscover
//characteristic
data
read
write
broadcast
notify
descriptorsDiscover
//descriptor
valueRead
valueWrite