search

openbci-archive / OpenBCI_NodeJS_Wifi

NodeJS driver for the Wifi Shield
MIT License
16 stars 13 forks source link

readme

THIS REPOSITORY HAS BEEN DEPRECATED AND IS NO LONGER IN ACTIVE DEVELOPMENT.

OpenBCI WiFi Shield NodeJS SDK

banner

Make programming with OpenBCI reliable, easy, research grade and fun!

codecov Dependency Status npm js-semistandard-style

Welcome!

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

Thank you for visiting the OpenBCI WiFi Shield 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?

The problem

So, if even the very best developers integrate the current easy to use Cyton and Ganglion NodeJS drivers, they are still burdened by the limitations of the physical hardware on the OpenBCI system.

The solution

The OpenBCI WiFi Shield NodeJS SDK will:

Using WiFi physically solves limitations with the current state-of-the-art open source bio sensor. The goal for the WiFi Shield firmware was to create a one up data pipeline, where scientific data in JSON is sent instead of raw/compressed ADC counts (yuk!) to make programming with OpenBCI reliable, easy, research grade and fun!

Who are we?

The founder of the OpenBCI WiFi Shield NodeJS SDK is AJ Keller.

<img src="http://mozillascience.github.io/working-open-workshop/assets/images/science-fox.svg" align="right" width=140

AJ is an invited member of the 4th cohort Open Leaders Cohort of the Mozilla Science Lab who brought together open science advocates from around the world to participate in the first Working Open Workshop in Berlin in February 2016. The training exercises (which are free and easy to reuse) focused on how to build and effectively engage communities so they can work together to develop tools and resources for the greater good.

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 make programming with OpenBCI reliable, easy, research grade and fun, 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:

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.

Documentation

Table of Contents:

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

Installation:

We assume you have NodeJS installed already, if you don't please download the latest stable version from NodeJS.

Then simply using the node package manager command line tool, enter:

npm install @openbci/wifi

TL;DR:

Get connected and start streaming right now with the example code.

const Wifi = require('@openbci/wifi');
let wifi = new Wifi({
  debug: false,
  verbose: true,
  latency: 10000
});

wifi.on(k.OBCIEmitterSample, (sample) => {
  for (let i = 0; i < wifi.getNumberOfChannels(); 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."
  }
});

wifi.searchToStream({
    sampleRate: 1000 // Custom sample rate
    shieldName: 'OpenBCI-2C34', // Enter the unique name for your wifi shield
    streamStart: true // Call to start streaming in this function
  }).catch(console.log);

Developing:

Running:

npm install

Testing:

npm test

Contribute:

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

License:

MIT

General Overview

Initialization

Initializing the board:

const Wifi = require('../../openBCIWifi');
const ourBoard = new Wifi();

Go checkout out the get streaming example!

For initializing with options, such as verbose print outs:

const Wifi = require('../../openBCIWifi');
const wifi = new Wifi({
  verbose: true
});

or if you are using ES6:

import Wifi from '../../openBCIWifi';
import { constants } from '@openbci/utilities';
const wifi = new Wifi();
wifi.connect("OpenBCI-2114");

To debug, it's amazing, do:

const Wifi = require('../../openBCIWifi');
const wifi = new Wifi({
    debug: true
});

Sample properties:

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:

  1. Install the 'sample' event emitter
  2. Call .searchToStream(_options_) 
    
const Wifi = require('../../openBCIWifi');
let wifi = new Wifi({
debug: false,
verbose: true,
latency: 10000
});

wifi.on(k.OBCIEmitterSample, (sample) => { for (let i = 0; i < wifi.getNumberOfChannels(); 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." } });

wifi.searchToStream({ sampleRate: 1000 // Custom sample rate shieldName: 'OpenBCI-2C34', // Enter the unique name for your wifi shield streamStart: true // Call to start streaming in this function }).catch(console.log);

Close the connection with [`.streamStop()`](#Wifi+streamStop) and disconnect with [`.disconnect()`](#Wifi+disconnect)
```js
const Wifi = require('../../openBCIWifi');
const wifi = new Wifi();
wifi.streamStop().then(wifi.disconnect());

Classes

Wifi

Typedefs

InitializationObject : Object

Wifi

Kind: global class Author: AJ Keller (@aj-ptw)

new Wifi(options)

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

Param Type Description
options InitializationObject (optional) - Board optional configurations.

wifi.options : InitializationObject

Kind: instance property of Wifi

wifi._accelArray

Private Properties (keep alphabetical)

Kind: instance property of Wifi

wifi.curOutputMode

Public Properties (keep alphabetical)

Kind: instance property of Wifi

wifi.bufferRawDataPackets(rawDataPackets) ⇒ Array

This function is for redundancy after a long packet send, the wifi firmware can resend the same packet again, using this till add redundancy on poor networks.

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

Param Description
rawDataPackets -

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

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

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

Param
channelNumber

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

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

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

Param
channelNumber

wifi.channelSet(channelNumber, powerDown, gain, inputType, bias, srb2, srb1) ⇒ Promise

To send a channel setting command to the board

Kind: instance method of Wifi Returns: Promise - resolves if sent, rejects on bad input or no board Author: AJ Keller (@aj-ptw)

Param Description
channelNumber Number (1-16)
powerDown Bool (true -> OFF, false -> ON (default)) turns the channel on or off
gain Number (1,2,4,6,8,12,24(default)) sets the gain for the channel
inputType String (normal,shorted,biasMethod,mvdd,temp,testsig,biasDrp,biasDrn) selects the ADC channel input source
bias Bool (true -> Include in bias (default), false -> remove from bias) selects to include the channel input in bias generation
srb2 Bool (true -> Connect this input to SRB2 (default), false -> Disconnect this input from 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.
srb1 Bool (true -> connect all N inputs to SRB1, false -> Disconnect all N inputs from SRB1 (default)) Select to connect (true) all channels' N inputs to SRB1. This effects all pins, and disconnects all N inputs from the ADC.

wifi.impedanceSet(channelNumber, pInputApplied, nInputApplied) ⇒ Promise

To send an impedance setting command to the board

Kind: instance method of Wifi Returns: Promise - resolves if sent, rejects on bad input or no board Author: AJ Keller (@aj-ptw)

Param Type Description
channelNumber Number (1-16)
pInputApplied Boolean (true -> ON, false -> OFF (default))
nInputApplied Boolean (true -> ON, false -> OFF (default))

wifi.connect(o) ⇒ Promise

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

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

Param Type Description
o Object
o.burst Boolean Set this option true to have UDP do burst mode 3x
o.examineMode Boolean Set this option true to connect to the WiFi Shield even if there is no board attached.
o.ipAddress String The ip address of the shield if you know it
o.latency Number If you want to set the latency of the system you can here too.
o.protocol String Either send the data over TCP or UDP. UDP seems better for either a bad router or slow router. Default is TCP
o.sampleRate The sample rate to set the board connected to the wifi shield
o.shieldName String If supplied, will search for a shield by this name, if not supplied, will connect to the first shield found.
o.streamStart Boolean Set true if you want the board to start streaming.

wifi.disconnect() ⇒ Promise

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

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

wifi.isConnected() ⇒ boolean

Checks if the driver is connected to a board.

Kind: instance method of Wifi Returns: boolean - - True if connected. Author: AJ Keller (@aj-ptw)

wifi.isSearching() ⇒ boolean

Checks if noble is currently scanning.

Kind: instance method of Wifi Returns: boolean - - True if streaming. Author: AJ Keller (@aj-ptw)

wifi.isStreaming() ⇒ boolean

Checks if the board is currently sending samples.

Kind: instance method of Wifi Returns: boolean - - True if streaming. Author: AJ Keller (@aj-ptw)

wifi.getBoardType() ⇒ *

Get the current board type

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.getFirmwareVersion() ⇒ String

Get the firmware version of connected and synced wifi shield.

Kind: instance method of Wifi Returns: String - The version number Note: This is dependent on if you called connect Author: AJ Keller (@aj-ptw)

wifi.getIpAddress() ⇒ null | String

Return the ip address of the attached WiFi Shield device.

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.getLatency() ⇒ Number

Return the latency to be set on the WiFi Shield.

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.getMacAddress() ⇒ null | String

Return the MAC address of the attached WiFi Shield device.

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.getNumberOfChannels() ⇒ Number

This function is used as a convenience method to determine how many channels the current board is using. Note: This is dependent on if your wifi shield is attached to another board and how many channels are there.

Kind: instance method of Wifi Returns: Number - A number Author: AJ Keller (@aj-ptw)

wifi.getSampleRate() ⇒ Number

Get the the current sample rate is. Note: This is dependent on if you configured the board correctly on setup options

Kind: instance method of Wifi Returns: Number - The sample rate Author: AJ Keller (@aj-ptw)

wifi.getShieldName() ⇒ null | String

Return the shield name of the attached WiFi Shield device.

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.impedanceStart() ⇒ global.Promise | Promise

Call to start testing impedance.

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.impedanceStop() ⇒ global.Promise | Promise

Call to stop testing impedance.

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.searchToStream(o) ⇒ Promise

Used to search for an OpenBCI WiFi Shield. Will connect to the first one if no shieldName is supplied.

Kind: instance method of Wifi Returns: Promise - - Resolves after successful connection, rejects otherwise with Error. Author: AJ Keller (@aj-ptw)

Param Type Description
o Object (optional)
o.sampleRate The sample rate to set the board connected to the wifi shield
o.shieldName String If supplied, will search for a shield by this name, if not supplied, will connect to the first shield found.
o.streamStart Boolean Set true if you want the board to start streaming.
o.timeout Number The time in milli seconds to wait for the system to try and auto find and connect to the shield.

wifi.setSampleRate(sampleRate) ⇒ Promise

Set the sample rate of the remote OpenBCI shield

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

Param Type Description
sampleRate Number the sample rate you want to set to.

wifi.syncSampleRate() ⇒ Promise

Returns the sample rate from the board

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.searchStart() ⇒ Promise

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

Kind: instance method of Wifi Returns: Promise - - If scan was started Author: AJ Keller (@aj-ptw)

wifi.searchStop() ⇒ global.Promise | Promise

Called to end a search.

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

wifi.sdStop() ⇒ Promise

Sends the stop SD logging command to the board. If not streaming then eot event will be emitted with request response from the board.

Kind: instance method of Wifi Returns: Promise - - Resolves when written Author: AJ Keller (@aj-ptw)

wifi.syncRegisterSettings() ⇒ Promise.<T> | *

Syncs the internal channel settings object with a cyton, this will take about over a second because there are delays between the register reads in the firmware.

Kind: instance method of Wifi Returns: Promise.<T> | * - Resolved once synced, rejects on error or 2 second timeout Author: AJ Keller (@aj-ptw)

wifi.softReset() ⇒ Promise

Sends a soft reset command to the board

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

wifi.eraseWifiCredentials() ⇒ Promise

Tells the WiFi Shield to forget it's network credentials. This will cause the board to drop all connections.

Kind: instance method of Wifi Returns: Promise - Resolves when WiFi Shield has been reset and the module disconnects. Author: AJ Keller (@aj-ptw)

wifi.streamStart() ⇒ Promise

Sends a start streaming command to the board.

Kind: instance method of Wifi 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 (@aj-ptw)

wifi.streamStop() ⇒ Promise

Sends a stop streaming command to the board.

Kind: instance method of Wifi 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 (@aj-ptw)

wifi.syncInfo(o) ⇒ Promise.<TResult>

Sync the info of this wifi module

Kind: instance method of Wifi Author: AJ Keller (@aj-ptw)

Param Type Description
o Object
o.examineMode Boolean Set this option true to connect to the WiFi Shield even if there is no board attached.

wifi.write(data) ⇒ Promise

Used to send data to the board.

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

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

wifi.destroy()

Call this to shut down the servers.

Kind: instance method of Wifi

wifi.wifiGetLocalPort() ⇒ number

Get the local port number of either the TCP or UDP server. Based on options.protocol being set to either udp or tcp.

Kind: instance method of Wifi Returns: number - The port number that was dynamically assigned to this module on startup.

wifi.wifiGetLocalPortUDP() ⇒ number

Get the local port number of the UDP server.

Kind: instance method of Wifi Returns: number - The port number that was dynamically assigned to this module on startup.

wifi.wifiGetLocalPortTCP() ⇒ number

Get the local port number of the UDP server.

Kind: instance method of Wifi Returns: number - The port number that was dynamically assigned to this module on startup.

wifi.wifiInitServer()

Initialization function that will start the TCP server and bind the UDP port.

Kind: instance method of Wifi

wifi.delete(path) ⇒ Promise

Send a delete message to the connected wifi shield.

Kind: instance method of Wifi Returns: Promise - - Resolves if gets a response from the client/server, rejects with error

Param Type Description
path String the path/route to send the delete message to

wifi.get(path) ⇒ Promise

Send a GET message to the connected wifi shield.

Kind: instance method of Wifi Returns: Promise - - Resolves if gets/with a response from the client/server, rejects with error

Param Type Description
path String the path/route to send the GET message to

wifi.post(path, payload) ⇒ Promise

Send a POST message to the connected wifi shield.

Kind: instance method of Wifi Returns: Promise - - Resolves if gets a response from the client/server, rejects with error

Param Type Description
path String the path/route to send the POST message to
payload * can really be anything but should be a JSON object.

Wifi~o

Configuring Options

Kind: inner property of Wifi

InitializationObject : Object

Kind: global typedef Properties

Name Type Description
attempts Number The number of times to try and perform an SSDP search before quitting. (Default 10)
burst Boolean Only applies for UDP, but the wifi shield will send 3 of the same packets on UDP to increase the chance packets arrive to this module (Default false)
debug Boolean Print out a raw dump of bytes sent and received. (Default false)
latency Number The latency, or amount of time between packet sends, of the WiFi shield. The time is in micro seconds!
protocol String Either send the data over TCP or UDP. UDP seems better for either a bad router or slow router. Default is TCP
sampleRate Number The sample rate to set the board to. (Default is zero)
sendCounts Boolean Send integer raw counts instead of scaled floats. (Default false)
verbose Boolean Print out useful debugging events. (Default false)