OpenBCI Node.js Ganglion SDK

A Node.js module for OpenBCI.

We are proud to support all functionality of the Ganglion (4 channel).

The purpose of this module is to get connected and start streaming as fast as possible.

TL;DR:

Get connected and start streaming right now

const Ganglion = require("@openbci/ganglion");
const ganglion = new Ganglion();
ganglion.once("ganglionFound", peripheral => {
  // Stop searching for BLE devices once a ganglion is found.
  ganglion.searchStop();
  ganglion.on("sample", sample => {
    /** Work with sample */
    console.log(sample.sampleNumber);
    for (let i = 0; i < ganglion.numberOfChannels(); i++) {
      console.log(
        "Channel " +
          (i + 1) +
          ": " +
          sample.channelData[i].toFixed(8) +
          " Volts."
      );
    }
  });
  ganglion.once("ready", () => {
    ganglion.streamStart();
  });
  ganglion.connect(peripheral);
});
// Start scanning for BLE devices
ganglion.searchStart();

Prerequisites:

Please ensure Python 2.7 is installed for all OS.

macOS

install Xcode

Linux

Kernel version 3.6 or above
libbluetooth-dev
libudev-dev

Running without sudo

In order to stream data on Linux without root/sudo access, you may need to give the node binary privileges to start and stop BLE advertising.

sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)

Note: this command requires setcap to be installed. Install it with the libcap2-bin package.

sudo apt-get install libcap2-bin

Windows 8+

node-gyp requirements for Windows
- Python 2.7
- Visual Studio (Express)
node-bluetooth-hci-socket prerequisites
- Compatible Bluetooth 4.0 USB adapter
- WinUSB driver setup for Bluetooth 4.0 USB adapter, using Zadig tool

See @don's set up guide on Bluetooth LE with Node.js and Noble on Windows.

Installation:

Install from npm:

npm install @openbci/ganglion

About:

The Ganglion driver used by OpenBCI's Processing GUI and Electron Hub.

Check out the automatic tests written for it!

General Overview:

Initialization

Initializing the board:

const Ganglion = require("@openbci/ganglion");
const ganglion = new Ganglion();

For initializing with options, such as verbose print outs:

const Ganglion = require("@openbci/ganglion");
const ourBoard = new Ganglion({
  verbose: true
});

For initializing with callback, such as to catch errors on noble startup:

const Ganglion = require("@openbci/ganglion");
const ourBoard = new Ganglion(error => {
  if (error) {
    console.log("error", error);
  } else {
    console.log("no error");
  }
});

For initializing with options and callback, such as verbose and to catch errors on noble startup:

const Ganglion = require("@openbci/ganglion");
const ourBoard = new Ganglion(
  {
    verbose: true
  },
  error => {
    if (error) {
      console.log("error", error);
    } else {
      console.log("no error");
    }
  }
);

'ready' event

You MUST wait for the 'ready' event to be emitted before streaming/talking with the board. The ready happens asynchronously so installing the 'sample' listener and writing before the ready event might result in... nothing at all.

const Ganglion = require("@openbci/ganglion");
const ourBoard = new Ganglion();
ourBoard
  .connect(portName)
  .then(function(boardSerial) {
    ourBoard.on("ready", function() {
      /** Start streaming, reading registers, what ever your heart desires  */
    });
  })
  .catch(function(err) {
    /** Handle connection errors */
  });

Sample properties:

sampleNumber (a Number between 0-255)
channelData (channel data indexed at 0 filled with floating point Numbers in Volts)
accelData (Array with X, Y, Z accelerometer values when new data available)
timeStamp (Number the boardTime plus the NTP calculated offset)

The power of this module is in using the sample emitter, to be provided with samples to do with as you wish.

To get a 'sample' event, you need to:

Call .connect(localName | peripheral)
Install the 'ready' event emitter on resolved promise
In callback for 'ready' emitter, call streamStart()
Install the 'sample' event emitter

const Ganglion = require("@openbci/ganglion");
const ourBoard = new Ganglion();
ourBoard
  .connect(localName)
  .then(function() {
    ourBoard.on("ready", function() {
      ourBoard.streamStart();
      ourBoard.on("sample", function(sample) {
        /** Work with sample */
      });
    });
  })
  .catch(function(err) {
    /** Handle connection errors */
  });

Close the connection with .streamStop() and disconnect with .disconnect()

const Ganglion = require("@openbci/ganglion");
const ourBoard = new Ganglion();
ourBoard.streamStop().then(ourBoard.disconnect());

See Reference Guide for a complete list of impedance tests.

SDK Reference Guide:

Classes

Ganglion

Typedefs

InitializationObject : Object: Board optional configurations.
BLED112AttributeValue : Object
BLED112AttributeWrite : Object
BLEDConnection : Object
BLED112FindInformationFound : Object
BLED112GapConnectDirect : Object
BLED112GroupService : Object
BLED112ParseRawAttributeValue : Object
BLED112ParseRawHeadTail : Object
BLED112ParseRawWord : Object
BLED112Peripheral : Object
BLED112RspGroupType : Object

Ganglion

Kind: global class
Author: AJ Keller (@pushtheworldllc)

Ganglion
- new Ganglion(options, callback)
- instance
  - .options : InitializationObject
  - ._accelArray
  - ._bled112WriteCharacteristic : BLED112FindInformationFound
  - .buffer
  - .accelStart() ⇒ Promise
  - .accelStop() ⇒ Promise
  - .autoReconnect()
  - .channelOff(channelNumber) ⇒ Promise.<T>
  - .channelOn(channelNumber) ⇒ Promise.<T> | *
  - .cleanupEmitters()
  - .connect(id) ⇒ Promise
  - .destroyNoble()
  - .destroyBLED112()
  - .destroyMultiPacketBuffer()
  - .disconnect(stopStreaming) ⇒ Promise
  - .getLocalName() ⇒ null | String
  - .getMutliPacketBuffer() ⇒ null | Buffer
  - .impedanceStart() ⇒ global.Promise | Promise
  - .impedanceStop() ⇒ global.Promise | Promise
  - .initDriver() ⇒ Promise.<any>
  - .isConnected() ⇒ boolean
  - .isNobleReady() ⇒ boolean
  - .isSearching() ⇒ boolean
  - .isStreaming() ⇒ boolean
  - .numberOfChannels() ⇒ Number
  - .printRegisterSettings() ⇒ Promise.<T> | *
  - .sampleRate() ⇒ Number
  - .searchStart(`maxSearchTime`) ⇒ Promise
  - .searchStop() ⇒ global.Promise | Promise
  - .softReset() ⇒ Promise
  - .streamStart() ⇒ Promise
  - .streamStop() ⇒ Promise
  - .syntheticEnable() ⇒ Promise
  - .syntheticDisable() ⇒ Promise
  - .write(data) ⇒ Promise
  - ._bled112WriteAndDrain(data) ⇒ Promise
- inner
  - ~o

new Ganglion(options, callback)

The initialization method to call first, before any other method.

Param	Type	Description
options	`InitializationObject`	(optional) - Board optional configurations.
callback	`function`	(optional) - A callback function used to determine if the noble module was able to be started. This can be very useful on Windows when there is no compatible BLE device found.

ganglion.options : `InitializationObject`

Kind: instance property of Ganglion

ganglion._accelArray

Private Properties (keep alphabetical)

Kind: instance property of Ganglion

ganglion._bled112WriteCharacteristic : `BLED112FindInformationFound`

Kind: instance property of Ganglion

ganglion.buffer

Public Properties (keep alphabetical)

Kind: instance property of Ganglion

ganglion.accelStart() ⇒ `Promise`

Used to enable the accelerometer. Will result in accelerometer packets arriving 10 times a second. Note that the accelerometer is enabled by default.

Kind: instance method of Ganglion

ganglion.accelStop() ⇒ `Promise`

Used to disable the accelerometer. Prevents accelerometer data packets from arriving.

Kind: instance method of Ganglion

ganglion.autoReconnect()

Used to start a scan if power is on. Useful if a connection is dropped.

Kind: instance method of Ganglion

ganglion.channelOff(channelNumber) ⇒ `Promise.<T>`

Send a command to the board to turn a specified channel off

Kind: instance method of Ganglion
Author: AJ Keller (@pushtheworldllc)

Param
channelNumber

ganglion.channelOn(channelNumber) ⇒ `Promise.<T>` | `*`

Send a command to the board to turn a specified channel on

Kind: instance method of Ganglion
Author: AJ Keller (@pushtheworldllc)

Param
channelNumber

ganglion.cleanupEmitters()

Used to clean up emitters

Kind: instance method of Ganglion

ganglion.connect(id) ⇒ `Promise`

The essential precursor method to be called initially to establish a ble connection to the OpenBCI ganglion board.

Kind: instance method of Ganglion
Returns: Promise - If the board was able to connect.
Author: AJ Keller (@pushtheworldllc)

Param	Type	Description
id	`String` \| `Object`	a string local name or peripheral object

ganglion.destroyNoble()

Destroys the noble!

Kind: instance method of Ganglion

ganglion.destroyBLED112()

Destroys the noble!

Kind: instance method of Ganglion

ganglion.destroyMultiPacketBuffer()

Destroys the multi packet buffer.

Kind: instance method of Ganglion

ganglion.disconnect(stopStreaming) ⇒ `Promise`

Closes the connection to the board. Waits for stop streaming command to be sent if currently streaming.

Kind: instance method of Ganglion
Returns: Promise - - fulfilled by a successful close, rejected otherwise.
Author: AJ Keller (@pushtheworldllc)

Param	Type	Description
stopStreaming	`Boolean`	(optional) - True if you want to stop streaming before disconnecting.

ganglion.getLocalName() ⇒ `null` | `String`

Return the local name of the attached Ganglion device.

Kind: instance method of Ganglion

ganglion.getMutliPacketBuffer() ⇒ `null` | `Buffer`

Get's the multi packet buffer.

Kind: instance method of Ganglion
Returns: null | Buffer - - Can be null if no multi packets received.

ganglion.impedanceStart() ⇒ `global.Promise` | `Promise`

Call to start testing impedance.

Kind: instance method of Ganglion

ganglion.impedanceStop() ⇒ `global.Promise` | `Promise`

Call to stop testing impedance.

Kind: instance method of Ganglion

ganglion.initDriver() ⇒ `Promise.<any>`

Initialize the drivers

Kind: instance method of Ganglion

ganglion.isConnected() ⇒ `boolean`

Checks if the driver is connected to a board.

Kind: instance method of Ganglion
Returns: boolean - - True if connected.

ganglion.isNobleReady() ⇒ `boolean`

Checks if bluetooth is powered on.

Kind: instance method of Ganglion
Returns: boolean - - True if bluetooth is powered on.

ganglion.isSearching() ⇒ `boolean`

Checks if noble is currently scanning.

Kind: instance method of Ganglion
Returns: boolean - - True if streaming.

ganglion.isStreaming() ⇒ `boolean`

Checks if the board is currently sending samples.

Kind: instance method of Ganglion
Returns: boolean - - True if streaming.

ganglion.numberOfChannels() ⇒ `Number`

This function is used as a convenience method to determine how many channels the current board is using.

Kind: instance method of Ganglion
Returns: Number - A number Note: This is dependent on if you configured the board correctly on setup options
Author: AJ Keller (@pushtheworldllc)

ganglion.printRegisterSettings() ⇒ `Promise.<T>` | `*`

To print out the register settings to the console

Kind: instance method of Ganglion
Author: AJ Keller (@pushtheworldllc)

ganglion.sampleRate() ⇒ `Number`

Get the the current sample rate is.

Kind: instance method of Ganglion
Returns: Number - The sample rate Note: This is dependent on if you configured the board correctly on setup options

ganglion.searchStart(`maxSearchTime`) ⇒ `Promise`

List available peripherals so the user can choose a device when not automatically found.

Kind: instance method of Ganglion
Returns: Promise - - If scan was started

Param	Type	Description
`maxSearchTime`	`Number`	The amount of time to spend searching. (Default is 20 seconds)

ganglion.searchStop() ⇒ `global.Promise` | `Promise`

Called to end a search.

Kind: instance method of Ganglion

ganglion.softReset() ⇒ `Promise`

Sends a soft reset command to the board

Kind: instance method of Ganglion
Returns: Promise - - Fulfilled if the command was sent to board.
Author: AJ Keller (@pushtheworldllc)

ganglion.streamStart() ⇒ `Promise`

Sends a start streaming command to the board.

Kind: instance method of Ganglion
Returns: Promise - indicating if the signal was able to be sent. Note: You must have successfully connected to an OpenBCI board using the connect method. Just because the signal was able to be sent to the board, does not mean the board will start streaming.
Author: AJ Keller (@pushtheworldllc)

ganglion.streamStop() ⇒ `Promise`

Sends a stop streaming command to the board.

Kind: instance method of Ganglion
Returns: Promise - indicating if the signal was able to be sent. Note: You must have successfully connected to an OpenBCI board using the connect method. Just because the signal was able to be sent to the board, does not mean the board stopped streaming.
Author: AJ Keller (@pushtheworldllc)

ganglion.syntheticEnable() ⇒ `Promise`

Puts the board in synthetic data generation mode. Must call streamStart still.

Kind: instance method of Ganglion
Returns: Promise - indicating if the signal was able to be sent.
Author: AJ Keller (@pushtheworldllc)

ganglion.syntheticDisable() ⇒ `Promise`

Takes the board out of synthetic data generation mode. Must call streamStart still.

Kind: instance method of Ganglion
Returns: Promise - - fulfilled if the command was sent.
Author: AJ Keller (@pushtheworldllc)

ganglion.write(data) ⇒ `Promise`

Used to send data to the board.

Kind: instance method of Ganglion
Returns: Promise - - fulfilled if command was able to be sent
Author: AJ Keller (@pushtheworldllc)

Param	Type	Description
data	`Array` \| `Buffer` \| `Number` \| `String`	The data to write out

Example

Sends a single character command to the board.

// ourBoard has fulfilled the promise on .connect() and 'ready' has been observed previously
ourBoard.write("a");

Sends an array of bytes

// ourBoard has fulfilled the promise on .connect() and 'ready' has been observed previously
ourBoard.write(["x", "0", "1", "0", "0", "0", "0", "0", "0", "X"]);

Call crazy? Go for it...

ourBoard.write("t");
ourBoard.write("a");
ourBoard.write("c");
ourBoard.write("o");

ganglion._bled112WriteAndDrain(data) ⇒ `Promise`

Should be used to send data to the board

Kind: instance method of Ganglion
Returns: Promise - if signal was able to be sent
Author: AJ Keller (@pushtheworldllc)

Param	Type	Description
data	`Buffer` \| `Buffer2`	The data to write out

Ganglion~o

Configuring Options

Kind: inner property of Ganglion

kOBCIBLED112ParsingConnectDirect

Used in parsing incoming serial data

Kind: global constant