openbci-sdk
Advanced tools
A Node.js module for OpenBCI ~ written with love by Push The World!
We are proud to support all functionality of the OpenBCI 8 Channel board (16 channel coming soon) and are actively developing and maintaining this module.
The purpose of this module is to get connected and start streaming as fast as possible.
npm install openbci-sdk
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
ourBoard.connect(portName)
.then(function() {
ourBoard.on('ready',function() {
ourBoard.streamStart();
ourBoard.on('sample',function(sample) {
/** Work with sample */
for (var i = 0; i < ourBoard.numberOfChannels(); i++) {
console.log("Channel " + (i + 1) + ": " + sample.channelData[i].toFixed(8) + " Volts.");
// prints to the console
// "Channel 1: 0.00001987 Volts."
// "Channel 2: 0.00002255 Volts."
// ...
// "Channel 8: -0.00001875 Volts."
}
});
});
})
Want to know if the module really works? Check out some projects and organizations using it:
Still not satisfied it works?? Check out this detailed report that scientifically validates the output voltages of this module.
How are you still doubting and not using this already? Fine, go look at some of the 400 automatic tests written for it!
Initializing the board:
var OpenBCIBoard = require('openbci-sdk');
var ourBoard = new OpenBCIBoard.OpenBCIBoard();
For initializing with options, such as verbose print outs:
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard({
verbose: true
});
Or if you don't have a board and want to use synthetic data:
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard({
simulate: true
});
Another useful way to start the simulator:
var openBCIBoard = require('openbci-sdk');
var k = openBCIBoard.OpenBCIConstants;
var ourBoard = openBCIBoard.OpenBCIBoard();
ourBoard.connect(k.OBCISimulatorPortName) // This will set `simulate` to true
.then(function(boardSerial) {
ourBoard.on('ready',function() {
/** Start streaming, reading registers, what ever your heart desires */
});
}).catch(function(err) {
/** Handle connection errors */
});
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.
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
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 */
});
startByte (Number should be 0xA0)sampleNumber (a Number between 0-255)channelData (channel data indexed at 0 filled with floating point Numbers in Volts)auxData (aux data indexed starting at 0 [0,1,2] filled with floating point Numbers)stopByte (Number should be 0xC0)The power of this module is in using the sample emitter, to be provided with samples to do with as you wish.
You can also start the simulator by sending .connect(portName) with portName equal to 'OpenBCISimulator'.
.connect(serialPortName)streamStart()var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
ourBoard.connect(portName).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()
var ourBoard = new require('openbci-sdk').OpenBCIBoard();
ourBoard.streamStop().then(ourBoard.disconnect());
You must have the OpenBCI board connected to the PC before trying to automatically find it.
If a port is not automatically found, then call .listPorts() to get a list of all serial ports this would be a good place to present a drop down picker list to the user, so they may manually select the serial port name.
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
ourBoard.autoFindOpenBCIBoard().then(portName => {
if(portName) {
/**
* Connect to the board with portName
* i.e. ourBoard.connect(portName).....
*/
} else {
/**Unable to auto find OpenBCI board*/
}
});
Note: .autoFindOpenBCIBoard() will return the name of the Simulator if you instantiate with option simulate: true.
Measuring impedance is a vital tool in ensuring great data is collected.
IMPORTANT! Measuring impedance takes time, so only test what you must
Your OpenBCI board will have electrodes hooked up to either a P input, N input or in some cases both inputs.
To test specific inputs of channels:
.impedanceTestChannels() with your configuration arrayA configuration array looks like, for an 8 channel board, ['-','N','n','p','P','-','b','b']
Where there are the same number of elements as channels and each element can be either:
p or P (only test P input)n or N (only test N input)b or B (test both inputs) (takes 66% longer to run then previous two p or n)- (ignore channel)Without further ado, here is an example:
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
ourBoard.connect(portName).then(function(boardSerial) {
ourBoard.on('ready',function() {
ourBoard.streamStart();
ourBoard.once('impedanceArray', impedanceArray => {
/** Work with impedance Array */
});
ourBoard.impedanceTestChannels(['n','N','n','p','P','p','b','B']).catch(err => console.log(err));
});
}).catch(function(err) {
/** Handle connection errors */
});
But wait! What is this impedanceArray? An Array of Objects, for each object:
[{
channel: 1,
P: {
raw: -1,
text: 'init'
},
N: {
raw: -1,
text: 'init'
}
},
{
// Continues for each channel up to the amount of channels on board (8 or 16)
},...];
Where:
impedanceArray[0] is channel 1, impedanceArray[6] is channel 7)average
To run an impedance test on all inputs, one channel at a time:
.impedanceTestAllChannels()Note: Takes up to 5 seconds to start measuring impedances. There is an unknown number of samples taken. Not always 60!
For example:
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
ourBoard.connect(portName).then(function(boardSerial) {
ourBoard.streamStart();
ourBoard.on('impedanceArray', impedanceArray => {
/** Work with impedance */
});
ourBoard.impedanceTestAllChannels();
}
See Reference Guide for a complete list of impedance tests.
Create new instance of an OpenBCI board.
options (optional)
Board optional configurations.
boardType Specifies type of OpenBCI board (3 possible boards)
default - 8 Channel OpenBCI board (Default)daisy - 8 Channel board with Daisy Module
(NOTE: THIS IS IN-OP AT THIS TIME DUE TO NO ACCESS TO ACCESSORY BOARD)ganglion - 4 Channel board
(NOTE: THIS IS IN-OP TIL RELEASE OF GANGLION BOARD 07/2016)baudRate Baud Rate, defaults to 115200. Manipulating this is allowed if firmware on board has been previously configured.verbose To output more messages to the command line.simulate Full functionality, just synthetic data.simulatorSampleRate - The sample rate to use for the simulator (Default is 250)simulatorAlpha - {Boolean} - Inject and 10Hz alpha wave in Channels 1 and 2 (Default true)simulatorLineNoise - Injects line noise on channels.
60Hz - 60Hz line noise (Default) (ex. United States)50Hz - 50Hz line noise (ex. Europe)None - Do not inject line noise.sntp - Syncs the module up with an SNTP time server. Syncs the board on startup with the SNTP time. Adds a time stamp to the AUX channels. NOTE: (NOT FULLY IMPLEMENTED) [DO NOT USE]Note, we have added support for either all lowercase OR camelcase of the options, use whichever style you prefer.
Automatically find an OpenBCI board.
Note: This will always return an Array of COM ports on Windows
Returns a promise, fulfilled with a portName such as /dev/tty.* on Mac/Linux or OpenBCISimulator if this.options.simulate === true.
Turn off a specified channel
channelNumber
A number (1-16) specifying which channel you want to turn off.
Returns a promise, fulfilled if the command was sent to the write queue.
Turn on a specified channel
channelNumber
A number (1-16) specifying which channel you want to turn on.
Returns a promise, fulfilled if the command was sent to the write queue.
Send a channel setting command to the board.
channelNumber
Determines which channel to set. It's a 'Number' (1-16)
powerDown
Powers the channel up or down. It's a 'Bool' where true turns the channel off and false turns the channel on (default)
gain
Sets the gain for the channel. It's a 'Number' that is either (1,2,4,6,8,12,24(default))
inputType
Selects the ADC channel input source. It's a 'String' that MUST be one of the following: "normal", "shorted", "biasMethod" , "mvdd" , "temp" , "testsig", "biasDrp", "biasDrn".
bias
Selects if the channel shall include the channel input in bias generation. It's a 'Bool' where true includes the channel in bias (default) or false it removes it from bias.
srb2
Select to connect (true) this channel's P input to the SRB2 pin. This closes a switch between P input and SRB2 for the given channel, and allows the P input to also remain connected to the ADC. It's a 'Bool' where true connects this input to SRB2 (default) or false which disconnect this input from SRB2.
srb1
Select to connect (true) all channels' N inputs to SRB1. This effects all pins, and disconnects all N inputs from the ADC. It's a 'Bool' where true connects all N inputs to SRB1 and false disconnects all N inputs from SRB1 (default).
Returns a promise fulfilled if proper commands sent to the write queue, rejects on bad input or no board.
Example
ourBoard.channelSet(2,false,24,'normal',true,true,false);
// sends ['x','2','0','6','0','1','1','0','X'] to the command queue
The essential precursor method to be called initially to establish a serial connection to the OpenBCI board.
portName
The system path of the OpenBCI board serial port to open. For example, /dev/tty on Mac/Linux or COM1 on Windows.
Returns a promise, fulfilled by a successful serial connection to the board, the promise will be rejected at any time if the serial port has an 'error' or 'close' event emitted.
Calls all .printPacketsBad(), .printPacketsRead(), .printBytesIn()
Closes the serial port opened by .connect()
Returns a promise, fulfilled by a successful close of the serial port object, rejected otherwise.
Gets the specified channelSettings register data from printRegisterSettings call.
channelNumber
A number specifying which channel you want to get data on. Only 1-8 at this time.
Note, at this time this does not work for the daisy board
Returns a promise, fulfilled if the command was sent to the board and the .processBytes() function is ready to reach for the specified channel.
To apply test signals to the channels on the OpenBCI board used to test for impedance. This can take a little while to actually run (<8 seconds)!
Don't forget to install the impedanceArray emitter to receive the impendances!
Note, you must be connected in order to set the test commands. Also this method can take up to 5 seconds to send all commands!
Returns a promise upon completion of test.
arrayOfCommands
The array of configurations where there are the same number of elements as channels and each element can be either:
p or P (only test P input)n or N (only test N input)b or B (test both inputs) (takes 66% longer to run then previous two p or n)- (ignore channel)Don't forget to install the impedanceArray emitter to receive the impendances!
Note, you must be connected in order to set the test commands. Also this method can take up to 5 seconds to send all commands!
Returns a promise upon completion of test.
Run a complete impedance test on a single channel, applying the test signal individually to P & N inputs.
channelNumber
A Number, specifies which channel you want to test.
Returns a promise that resolves a single channel impedance object.
Example:
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
ourBoard.connect(portName).then(function(boardSerial) {
ourBoard.on('ready',function() {
ourBoard.streamStart();
ourBoard.impedanceTestChannel(1)
.then(impedanceObject => {
/** Do something with impedanceObject! */
})
.catch(err => console.log(err));
});
}).catch(function(err) {
/** Handle connection errors */
});
Where an impedance for this method call would look like:
{
channel: 1,
P: {
raw: 2394.45,
text: 'good'
},
N: {
raw: 7694.45,
text: 'ok'
}
}
Run impedance test on a single channel, applying the test signal only to P input.
channelNumber
A Number, specifies which channel you want to test.
Returns a promise that resolves a single channel impedance object.
Example:
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
ourBoard.connect(portName).then(function(boardSerial) {
ourBoard.on('ready',function() {
ourBoard.streamStart();
ourBoard.impedanceTestChannelInputP(1)
.then(impedanceObject => {
/** Do something with impedanceObject! */
})
.catch(err => console.log(err));
});
}).catch(function(err) {
/** Handle connection errors */
});
Where an impedance for this method call would look like:
{
channel: 1,
P: {
raw: 2394.45,
text: 'good'
},
N: {
raw: -1,
text: 'init'
}
}
Run impedance test on a single channel, applying the test signal only to N input.
channelNumber
A Number, specifies which channel you want to test.
Returns a promise that resolves a single channel impedance object.
Example:
var OpenBCIBoard = require('openbci-sdk').OpenBCIBoard;
var ourBoard = new OpenBCIBoard();
ourBoard.connect(portName).then(function(boardSerial) {
ourBoard.on('ready',function() {
ourBoard.streamStart();
ourBoard.impedanceTestChannelInputN(1)
.then(impedanceObject => {
/** Do something with impedanceObject! */
})
.catch(err => console.log(err));
});
}).catch(function(err) {
/** Handle connection errors */
});
Where an impedance for this method call would look like:
{
channel: 1,
P: {
raw: -1,
text: 'init'
},
N: {
raw: 7694.45,
text: 'ok'
}
}
Sends command to turn on impedances for all channels and continuously calculate their impedances.
Returns a promise, that fulfills when all the commands are sent to the internal write buffer
Sends command to turn off impedances for all channels and stop continuously calculate their impedances.
Returns a promise, that fulfills when all the commands are sent to the internal write buffer
List available ports so the user can choose a device when not automatically found.
Returns a promise, fulfilled with a list of available serial ports.
Get the current number of channels available to use. (i.e. 8 or 16).
Note: This is dependent on if you configured the board correctly on setup options. Specifically as a daisy.
Returns a number, the total number of available channels.
Prints the total number of bytes that were read in this session to the console.
Prints the total number of packets that were not able to be read in this session to the console.
Prints the total number of packets that were read in this session to the console.
Prints all register settings for the ADS1299 and the LIS3DH on the OpenBCI board.
Returns a promise, fulfilled if the command was sent to the write queue.
Get the current sample rate.
Note: This is dependent on if you configured the board correctly on setup options. Specifically as a daisy.
Returns a number, the current sample rate.
Start logging to the SD card. If you are not streaming when you send this command, then you should expect to get a success or failure message followed by and end of transmission $$$.
recordingDuration
The duration you want to log SD information for. Opens a new SD file to write into. Limited to:
14sec - 14 seconds5min - 5 minutes15min - 15 minutes30min - 30 minutes1hour - 1 hour2hour - 2 hour4hour - 4 hour12hour - 12 hour24hour - 24 hourNote: You must have the proper type of SD card inserted into the board for logging to work.
Returns resolves if the command was added to the write queue.
Stop logging to the SD card and close any open file. If you are not streaming when you send this command, then you should expect to get a success or failure message followed by and end of transmission $$$. The success message contains a lot of useful information about what happened when writing to the SD card.
Returns resolves if the command was added to the write queue.
To enter simulate mode. Must call .connect() after.
Note, must be called after the constructor.
Returns a promise, fulfilled if able to enter simulate mode, reject if not.
To leave simulate mode.
Note, must be called after the constructor.
Returns a promise, fulfilled if able to stop simulate mode, reject if not.
Extends the popular STNP package on npmjs
Stateful method for querying the current offset only when the last one is too old. (defaults to daily)
Returns a promise with the time offset
Get time from the SNTP server. Must have internet connection!
Returns a promise fulfilled with time object
This function gets SNTP time since Jan 1, 1970, if we call this after a successful .sntpStart() this time will be sycned, or else we will just get the current computer time, the case if there is no internet.
Returns time since UNIX epoch in ms.
This starts the SNTP server and gets it to remain in sync with the SNTP server;
Returns a promise if the module was able to sync with ntp server.
Stops the SNTP from updating
Sends a soft reset command to the board.
Note, this method must be sent to the board before you can start streaming. This triggers the initial 'ready' event emitter.
Returns a promise, fulfilled if the command was sent to the write queue.
Sends a start streaming command to the board.
Note, You must have called and fulfilled .connect() AND observed a 'ready' emitter before calling this method.
Returns a promise, fulfilled if the command was sent to the write queue, rejected if unable.
Sends a stop streaming command to the board.
Note, You must have called and fulfilled .connect() AND observed a 'ready' emitter before calling this method.
Returns a promise, fulfilled if the command was sent to the write queue, rejected if unable.
Apply the internal test signal to all channels.
signal
A String indicating which test signal to apply
dc - Connect to DC signalground - Connect to internal GND (VDD - VSS)pulse1xFast - Connect to test signal 1x Amplitude, fast pulsepulse1xSlow - Connect to test signal 1x Amplitude, slow pulsepulse2xFast - Connect to test signal 2x Amplitude, fast pulsepulse2xFast - Connect to test signal 2x Amplitude, slow pulsenone - Reset to defaultReturns a promise, if the commands were sent to write buffer.
Send commands to the board. Due to the OpenBCI board firmware, a 10ms spacing must be observed between every command sent to the board. This method handles the timing and spacing between characters by adding characters to a global write queue and pulling from it every 10ms.
dataToWrite
Either a single character or an Array of characters
Returns a promise, fulfilled if the board has been connected and dataToWrite has been added to the write queue, rejected if there were any problems.
Example
Sends a single character command to the board.
// ourBoard has fulfilled the promise on .connected() and 'ready' has been observed previously
ourBoard.write('a');
Sends an array of bytes
// ourBoard has fulfilled the promise on .connected() and 'ready' has been observed previously
ourBoard.write(['x','0','1','0','0','0','0','0','0','X']);
Taking full advantage of the write queue. The following would be sent at t = 0, 10ms, 20ms, 30ms
ourBoard.write('t');
ourBoard.write('a');
ourBoard.write('c');
ourBoard.write('o');
Emitted when the serial connection to the board is closed.
Emitted when there is an on the serial port.
Emitted when there is a new impedanceArray available.
Emitted resulting in a call to .getChannelSettings() with the channelSettingsObject
Emitted when there is a new raw data packet available.
Emitted when the board is in a ready to start streaming state.
Emitted when there is a new sample available.
A bool, true if connected to an OpenBCI board, false if not.
A bool, true if streaming data from an OpenBCI board, false if not.
To use the constants file simply:
var openBCIBoard = require('openbci-sdk');
var k = openBCIBoard.OpenBCIConstants;
console.log(k.OBCISimulatorPortName); // prints OpenBCISimulator to the console.
The name of the simulator port.
npm install -Dnpm start into the terminal in the project directorynpm test
git checkout -b my-new-featurenpm test)git commit -m 'Add some feature'git push origin my-new-featureMIT
FAQs
The official Node.js SDK for the OpenBCI Biosensor Board.
We found that openbci-sdk demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Critics call the Node.js EOL CVE a misuse of the system, sparking debate over CVE standards and the growing noise in vulnerability databases.
Security News
cURL and Go security teams are publicly rejecting CVSS as flawed for assessing vulnerabilities and are calling for more accurate, context-aware approaches.
Security News
Bun 1.2 enhances its JavaScript runtime with 90% Node.js compatibility, built-in S3 and Postgres support, HTML Imports, and faster, cloud-first performance.