OpenBCI Cyton BLE NodeJS SDK

Welcome!

First and foremost, Welcome! :tada: Willkommen! :confetti_ball: Bienvenue! :balloon::balloon::balloon:

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:

• Contributors' guidelines
• Roadmap

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.

1. Upload BoardWithBLE.ino to the Cyton's Pic32 over the air following this tutorial
2. 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

1. Upload RadioDevice32bit.ino to the Cyton's RFDuino through hardwire following this tutorial
2. 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.
3. 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:

1. Installation
2. TL;DR
3. WiFi
4. General Overview
5. Classes
6. Developing
7. Testing
8. Contribute
9. License

Installation:

npm install openbci-cyton-ble

Classes

Typedefs

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
  • inner
    • ~o

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. |

cytonBLE.options : InitializationObject

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

cytonBLE.channelOff(channelNumber) ⇒ Promise.<T>

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

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

| Param | | --- | | channelNumber |

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

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

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

| Param | | --- | | channelNumber |

cytonBLE.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 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

cytonBLE.disconnect(stopStreaming) ⇒ Promise

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. |

cytonBLE.getLocalName() ⇒ null | String

Return the local name of the attached CytonBLE device.

Kind: instance method of CytonBLE

cytonBLE.getMutliPacketBuffer() ⇒ null | Buffer

Get's the multi packet buffer.

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

cytonBLE.impedanceTestChannel(channelNumber) ⇒ Promise

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. |

cytonBLE.impedanceTestChannelInputP(channelNumber) ⇒ Promise

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. |

cytonBLE.impedanceTestChannelInputN(channelNumber) ⇒ Promise

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. |

cytonBLE.impedanceTestChannels(arrayOfChannels) ⇒ Promise

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) |

cytonBLE.isConnected() ⇒ boolean

Checks if the driver is connected to a board.

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

cytonBLE.isNobleReady() ⇒ boolean

Checks if bluetooth is powered on.

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

cytonBLE.isSearching() ⇒ boolean

Checks if noble is currently scanning.

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

cytonBLE.isStreaming() ⇒ boolean

Checks if the board is currently sending samples.

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

cytonBLE.numberOfChannels() ⇒ Number

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)

cytonBLE.sampleRate() ⇒ Number

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

cytonBLE.searchStart(`maxSearchTime`) ⇒ Promise

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) |

cytonBLE.searchStop() ⇒ global.Promise | Promise

Called to end a search.

Kind: instance method of CytonBLE

cytonBLE.softReset() ⇒ Promise

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)

cytonBLE.streamStart() ⇒ Promise

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)

cytonBLE.streamStop() ⇒ Promise

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)

cytonBLE.write(data) ⇒ Promise

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

InitializationObject : Object

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:

1. Fork it!
2. Branch off of development: git checkout development
3. Create your feature branch: git checkout -b my-new-feature
4. Make changes
5. If adding a feature, please add test coverage.
6. Ensure tests all pass. (npm test)
7. Commit your changes: git commit -m 'Add some feature'
8. Push to the branch: git push origin my-new-feature
9. Submit a pull request. Make sure it is based off of the development branch when submitting! :D

License:

MIT