README.md

ARDUINO BRAIN LIBRARY

OVERVIEW

Brain is an Arduino Library for parsing data from Neurosky-based EEG headsets. Tested units include the Star Wars Force Trainer and Mattel MindFlex.

It's designed to make it simple to send out an ASCII string of comma-separated values over serial, or to access processed brain wave information directly in your Arduino sketch. See the examples for code demonstrating each use case.

Signal strength ranges from 0 - 200. Counterintuitively, 0 means the unit has connected successfully, and 200 means there is no signal.

The attention and meditation values both run from 0 - 100. Intuitively, higher numbers represent more attention or meditation.

The EEG power values — delta, theta, etc... - are a heavily filtered representation of the relative activity in different brain wavelengths. These values can not be mapped directly to physical values (e.g. volts), but are still of use when considered over time or relative to each other.

Repository Rename

This project was formerly "Arduino-Brain-Library" on GitHub, but was renamed to just "Brain" in 2014 to play nicely with the Arduino IDE's new ""Sketch --> Import Library..." menu item.

SOFTWARE SERIAL

Past versions of this library relied on a separate branch implementing support for NewSoftSerial. Improvements to both the bundled SoftwareSerial library and the underlying class hierarchy in Arduino 1.0 has allowed a single version of the Brain library to cover both use cases. Please do not use the old softserial branch of this library! Please see

EXAMPLES

Three examples are provided with the library:

BrainBlinker.ino blinks an LED faster as your "attention" value increases.

BrainSerialTest.ino prints out a CSV of brain data over serial.

BrainSoftSerialTest.ino reads brain data over SoftwareSerial and prints a CSV over hardware serial.

INSTALLATION

There are two ways to install the library:

Installation through the Arduino IDE

Download the latest release, and then in the Arduino IDE go to ""Sketch --> Import Library..." and point the file dialogue to the Brain.zip file you just downloaded.

Manual Installation

Download the latest release, decompress, rename it to Brain, and drag "Brain" folder to Arduino's "libraries" folder inside your sketch folder. (On the Mac, this is ~/Documents/Arduino/libraries by default. You may need to create this folder if it does not exist.) Restart the Arduino environment.

FUNCTION OVERVIEW

boolean update();
Call this in your main loop to read data from the headset. Returns true if there is a fresh packet.

char* readErrors();
Character string containing the most recent errors. Worth printing this out over serial if you're having trouble.

char* readCSV();
Character string with all of the latest brain values in a comma-delimited format. Intended to be printed over serial. The data is returned in this order: signal strength, attention, meditation, delta, theta, low alpha, high alpha, low beta, high beta, low gamma, high gamma

byte readSignalQuality();
Returns the latest signal quality reading. 200 is high, 0 is no signal. This (and the remainder of the functions) are mainly intended for use when you want the Arduino to use the brain data internally. (Saves you the hassle / memory expenditure of parsing the CSV.)

unsigned long readMidGamma();
Returns the high gamma (41-50Hz) power value.

MINUTIAE

Note that the connection to the Neurosky headset is half-duplex — it will use up the RX pin on your Arduino, but you will still be able to send data back to a PC via USB. (Although in this case you won't be able to send data to the Arduino from the PC.)

CONTACT

COLOPHON

Created by Eric Mika at NYU ITP in the spring of 2010.
Updated for Arduino 1.0 in 2013.
Revised, retested, and cleaned up in early 2014.

My thanks to Tom Igoe for his assistance during development. Thanks to my collaborators Sofy Yuditskaya and Arturo Vidich. (E>)

Thanks also to Eero af Heurlin for making some considered changes in his fork.

LICENSE

Copyright Eric Mika, 2010-2015
Licensed under the GNU Lesser General Public License.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.