OpenBCI Cyton BLE NodeJS SDK
Prove the Cyton over BLE instead of Gazell stack
Welcome!
First and foremost, Welcome! 🎉 Willkommen! 🎊 Bienvenue! 🎈🎈🎈
Thank you for visiting the OpenBCI Cyton BLE NodeJS SDK repository.
This document (the README file) is a hub to give you some information about the project. Jump straight to one of the sections below, or just scroll down to find out more.
- What are we doing? (And why?)
- Who are we?
- What do we need?
- How can you get involved?
- Get in touch
- Find out more
- Uploading the firmware
What are we doing?
The problem
- People have to use a dongle to get data from the Cyton
- People can't send data from the Cyton to the web browser :sad_face:
- There is a BLE switch on the Cyton that is doing nothing!
So, these problems add up to limit the amount of devices the cyton can stream it's high quality data to, and that's sad.
The solution
The OpenBCI Cyton BLE NodeJS SDK will:
- Find, connect, sync, and configure the Cyton over BLE
- Send two channels of EEG data uncompressed to the client
Using BLE allows for every modern day computer to get data from the Cyton.
Who are we?
The author of the OpenBCI Cyton BLE NodeJS SDK is AJ Keller and he was sponsored by NEBA Health, LLC. We are in search of a reliable BLE driver to really get this project going! We used this repo to test the firmware we were writing.
What do we need?
You! In whatever way you can help.
We need expertise in programming, user experience, software sustainability, documentation and technical writing and project management.
We'd love your feedback along the way.
Our primary goal is to prove the Cyton works over BLE instead of the Gazell stack and we're excited to support the professional development of any and all of our contributors. If you're looking to learn to code, try out working collaboratively, or translate you skills to the digital domain, we're here to help.
Get involved
If you think you can help in any of the areas listed above (and we bet you can) or in any of the many areas that we haven't yet thought of (and here we're sure you can) then please check out our contributors' guidelines and our roadmap.
Please note that it's very important to us that we maintain a positive and supportive environment for everyone who wants to participate. When you join us we ask that you follow our code of conduct in all interactions both on and offline.
Contact us
If you want to report a problem or suggest an enhancement we'd love for you to open an issue at this github repository because then we can get right on it. But you can also contact AJ by email (pushtheworldllc AT gmail DOT com) or on twitter.
You can also hang out, ask questions and share stories in the OpenBCI NodeJS room on Gitter.
Find out more
You might be interested in:
- Check out NEBA Health, LLC
- Purchase an OpenBCI [WiFi Shield][link_shop_wifi]
- A NodeJS example: cytonBLEServer.js
And of course, you'll want to know our:
Thank you
Thank you so much (Danke schön! Merci beaucoup!) for visiting the project and we do hope that you'll join us on this amazing journey to make programming with OpenBCI fun and easy.
Firmware
To set up Cyton to do BLE, keeping in mind the switch on the Cyton between PC and BLE does nothing, you must change the firmware.
- Upload BoardWithBLE.ino to the Cyton's Pic32 over the air following this tutorial
- Upload DefaultRadio.ino to the Cyton's RFDuino through hardwire following this tutorial where you use the DefaultRadio.ino from OpenBCI_RFDuino_BLE. If you don't have an FTDI programmer and need to use the Dongle that shipped with your Cyton, then be sure to follow the part in the tutorial about uploading the pass through code to the Dongle.
To undo an go back to the default firmware that ships with the Cyton
- Upload RadioDevice32bit.ino to the Cyton's RFDuino through hardwire following this tutorial
- If you were using your Dongle to help program the Cyton's RFDuino, then now is the time to upload RadioHost32bit.ino to the Dongle.
- Upload DefaultBoard.ino to the Cyton's Pic32 over the air following this tutorial
Please edit this document if you can improve it!
Documentation
Table of Contents:
Installation:
npm install openbci-cyton-ble
Classes
Typedefs
- InitializationObject :
Object
Board optional configurations.
CytonBLE
Kind: global class Author: AJ Keller (@pushtheworldllc)
- CytonBLE
- new CytonBLE(options, callback)
- instance
- .options :
InitializationObject
- ._accelArray
- .impedanceTest
- .autoReconnect()
- .channelOff(channelNumber) ⇒
Promise.<T>
- .channelOn(channelNumber) ⇒
Promise.<T>
|*
- .connect(id) ⇒
Promise
- .destroyNoble()
- .destroyMultiPacketBuffer()
- .disconnect(stopStreaming) ⇒
Promise
- .getLocalName() ⇒
null
|String
- .getMutliPacketBuffer() ⇒
null
|Buffer
- .impedanceTestChannel(channelNumber) ⇒
Promise
- .impedanceTestChannelInputP(channelNumber) ⇒
Promise
- .impedanceTestChannelInputN(channelNumber) ⇒
Promise
- .impedanceTestChannels(arrayOfChannels) ⇒
Promise
- .isConnected() ⇒
boolean
- .isNobleReady() ⇒
boolean
- .isSearching() ⇒
boolean
- .isStreaming() ⇒
boolean
- .numberOfChannels() ⇒
Number
- .sampleRate() ⇒
Number
- .searchStart(`maxSearchTime`) ⇒
Promise
- .searchStop() ⇒
global.Promise
|Promise
- .softReset() ⇒
Promise
- .streamStart() ⇒
Promise
- .streamStop() ⇒
Promise
- .write(data) ⇒
Promise
- .options :
- inner
new CytonBLE(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. |
InitializationObject
cytonBLE.options : Kind: instance property of CytonBLE
cytonBLE._accelArray
Private Properties (keep alphabetical)
Kind: instance property of CytonBLE
cytonBLE.impedanceTest
Public Properties (keep alphabetical)
Kind: instance property of CytonBLE
cytonBLE.autoReconnect()
Used to start a scan if power is on. Useful if a connection is dropped.
Kind: instance method of CytonBLE
Promise.<T>
cytonBLE.channelOff(channelNumber) ⇒ Send a command to the board to turn a specified channel off
Kind: instance method of CytonBLE
Author: AJ Keller (@pushtheworldllc)
Param |
---|
channelNumber |
Promise.<T>
| *
cytonBLE.channelOn(channelNumber) ⇒ Send a command to the board to turn a specified channel on
Kind: instance method of CytonBLE
Author: AJ Keller (@pushtheworldllc)
Param |
---|
channelNumber |
Promise
cytonBLE.connect(id) ⇒ The essential precursor method to be called initially to establish a ble connection to the OpenBCI ganglion board.
Kind: instance method of CytonBLE
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 |
cytonBLE.destroyNoble()
Destroys the noble!
Kind: instance method of CytonBLE
cytonBLE.destroyMultiPacketBuffer()
Destroys the multi packet buffer.
Kind: instance method of CytonBLE
Promise
cytonBLE.disconnect(stopStreaming) ⇒ Closes the connection to the board. Waits for stop streaming command to be sent if currently streaming.
Kind: instance method of CytonBLE
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. |
null
| String
cytonBLE.getLocalName() ⇒ Return the local name of the attached CytonBLE device.
Kind: instance method of CytonBLE
null
| Buffer
cytonBLE.getMutliPacketBuffer() ⇒ Get's the multi packet buffer.
Kind: instance method of CytonBLE
Returns: null
| Buffer
- - Can be null if no multi packets received.
Promise
cytonBLE.impedanceTestChannel(channelNumber) ⇒ Run a complete impedance test on a single channel, applying the test signal individually to P & N inputs.
Kind: instance method of CytonBLE
Returns: Promise
- - Fulfilled with a single channel impedance object.
Author: AJ Keller (@pushtheworldllc)
Param | Description |
---|---|
channelNumber | A Number, specifies which channel you want to test. |
Promise
cytonBLE.impedanceTestChannelInputP(channelNumber) ⇒ Run impedance test on a single channel, applying the test signal only to P input.
Kind: instance method of CytonBLE
Returns: Promise
- - Fulfilled with a single channel impedance object.
Author: AJ Keller (@pushtheworldllc)
Param | Description |
---|---|
channelNumber | A Number, specifies which channel you want to test. |
Promise
cytonBLE.impedanceTestChannelInputN(channelNumber) ⇒ Run impedance test on a single channel, applying the test signal to N input.
Kind: instance method of CytonBLE
Returns: Promise
- - Fulfilled with a single channel impedance object.
Author: AJ Keller (@pushtheworldllc)
Param | Description |
---|---|
channelNumber | A Number, specifies which channel you want to test. |
Promise
cytonBLE.impedanceTestChannels(arrayOfChannels) ⇒ To test specific input configurations of channels!
Kind: instance method of CytonBLE
Returns: Promise
- - Fulfilled with a loaded impedance object.
Author: AJ Keller (@pushtheworldllc)
Param | Description |
---|---|
arrayOfChannels | The array of configurations where: 'p' or 'P' is only test P input 'n' or 'N' is only test N input 'b' or 'B' is test both inputs (takes 66% longer to run) '-' to ignore channel EXAMPLE: For 8 channel board: ['-','N','n','p','P','-','b','b'] (Note: it doesn't matter if capitalized or not) |
boolean
cytonBLE.isConnected() ⇒ Checks if the driver is connected to a board.
Kind: instance method of CytonBLE
Returns: boolean
- - True if connected.
boolean
cytonBLE.isNobleReady() ⇒ Checks if bluetooth is powered on.
Kind: instance method of CytonBLE
Returns: boolean
- - True if bluetooth is powered on.
boolean
cytonBLE.isSearching() ⇒ Checks if noble is currently scanning.
Kind: instance method of CytonBLE
Returns: boolean
- - True if streaming.
boolean
cytonBLE.isStreaming() ⇒ Checks if the board is currently sending samples.
Kind: instance method of CytonBLE
Returns: boolean
- - True if streaming.
Number
cytonBLE.numberOfChannels() ⇒ This function is used as a convenience method to determine how many channels the current board is using.
Kind: instance method of CytonBLE
Returns: Number
- A number
Note: This is dependent on if you configured the board correctly on setup options
Author: AJ Keller (@pushtheworldllc)
Number
cytonBLE.sampleRate() ⇒ Get the the current sample rate is.
Kind: instance method of CytonBLE
Returns: Number
- The sample rate
Note: This is dependent on if you configured the board correctly on setup options
Promise
cytonBLE.searchStart(`maxSearchTime`) ⇒ List available peripherals so the user can choose a device when not automatically found.
Kind: instance method of CytonBLE
Returns: Promise
- - If scan was started
Param | Type | Description |
---|---|---|
maxSearchTime |
Number |
The amount of time to spend searching. (Default is 20 seconds) |
global.Promise
| Promise
cytonBLE.searchStop() ⇒ Called to end a search.
Kind: instance method of CytonBLE
Promise
cytonBLE.softReset() ⇒ Sends a soft reset command to the board
Kind: instance method of CytonBLE
Returns: Promise
- - Fulfilled if the command was sent to board.
Author: AJ Keller (@pushtheworldllc)
Promise
cytonBLE.streamStart() ⇒ Sends a start streaming command to the board.
Kind: instance method of CytonBLE
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)
Promise
cytonBLE.streamStop() ⇒ Sends a stop streaming command to the board.
Kind: instance method of CytonBLE
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)
Promise
cytonBLE.write(data) ⇒ Used to send data to the board.
Kind: instance method of CytonBLE
Returns: Promise
- - fulfilled if command was able to be sent
Author: AJ Keller (@pushtheworldllc)
Param | Type | Description |
---|---|---|
data | Array | Buffer | Buffer2 | Number | String |
The data to write out |
CytonBLE~o
Configuring Options
Kind: inner property of CytonBLE
Object
InitializationObject : Board optional configurations.
Kind: global typedef Properties
Name | Type | Description |
---|---|---|
debug | Boolean |
Print out a raw dump of bytes sent and received. (Default false ) |
nobleAutoStart | Boolean |
Automatically initialize noble . Subscribes to blue tooth state changes and such. (Default true ) |
nobleScanOnPowerOn | Boolean |
Start scanning for CytonBLE BLE devices as soon as power turns on. (Default true ) |
sendCounts | Boolean |
Send integer raw counts instead of scaled floats. (Default false ) |
Boolean |
Print out useful debugging events. (Default false ) |
Developing:
Running:
npm install
Testing:
npm test
Contribute:
- Fork it!
- Branch off of
development
:git checkout development
- Create your feature branch:
git checkout -b my-new-feature
- Make changes
- If adding a feature, please add test coverage.
- Ensure tests all pass. (
npm test
) - Commit your changes:
git commit -m 'Add some feature'
- Push to the branch:
git push origin my-new-feature
- Submit a pull request. Make sure it is based off of the
development
branch when submitting! :D
License:
MIT