# Brain turns a Neurosky toy headset into data an Arduino sketch can use

> Brain is a small C++ library for Arduino that parses the serial protocol of Neurosky based EEG headsets, so that a sketch can read signal quality, the attention and meditation indices and eight bands of EEG power directly instead of parsing a string. The compatibility table is the first thing to read, because two of the better known headsets in this family are explicitly not supported.

**kitschpatrol/brain** — Arduino library for reading NeuroSky EEG brainwave data.

- Repository: https://github.com/kitschpatrol/brain
- Website: https://frontiernerds.com/brain-hack
- Stars: 985 · Forks: 169
- Language: C++
- License: LGPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/kitschpatrol-brain

## One vendor's protocol, parsed for you

The library exists to do one job, and doing it well means the sketch does not have to. A Neurosky headset talks to the Arduino over a serial link with a particular packet format, and the library's `Brain` class reads that format and hands back clean values. The headline feature is that it can send out an ASCII string of comma separated values over serial, which is what makes it useful with any serial terminal or with the Processing based Brain Grapher that the documentation recommends pairing it with, and it also exposes the parsed values directly so a sketch can use them internally. The class is constructed with a reference to a hardware serial port, and the sketch calls `update()` in its main loop, which returns true when a fresh packet has arrived. Everything else is read from the object: `readSignalQuality()`, `readAttention()`, `readMeditation()` and one function per EEG band.

## The numbers are indices, and one of them counts backwards

The documentation is careful about what the values mean, and a reader should be equally careful. The CSV that `readCSV()` produces has these fields in this order:

```
signal strength, attention, meditation, delta, theta, low alpha, high alpha, low beta, high beta, low gamma, high gamma
```

Signal strength runs from 0 to 200, and the direction is the opposite of what the name suggests: 0 means the unit has connected successfully and 200 means there is no signal, so a well connected headset reports a small number. Attention and meditation both run from 0 to 100 with the intuitive direction, higher meaning more of each. The EEG power values are the ones to be careful with. They are described as a heavily filtered representation of the relative activity in different brain wavelengths, and the documentation says they cannot be mapped directly to physical values such as volts, but are still of use when considered over time or relative to each other. That is a smaller claim than the band names suggest, and it is the claim the library actually makes.

## The compatibility table rules out two well known headsets

The library expects a specific serial protocol, and hardware that uses a different one will not work, showing serial or parsing errors instead. The tested devices are the Star Wars Force Trainer and the Mattel MindFlex, and the table marks the Star Wars Force Trainer II and the Neurosky MindWave Mobile 2 as not compatible. That distinction matters, because the failure mode described is an error rather than a wrong number, so a mismatch is at least loud. The author also says that support for other devices is feasible and that pull requests are welcome, while being straight about not having the time or the hardware access to implement it. The MindFlex is the richer of the two supported units, because it exposes eight bands of EEG power data in addition to the signal strength, attention and meditation values.

## Two ways to install, both through the releases page

Installation goes through a downloaded release rather than the Arduino library manager. The first route is the IDE route, where you download the latest release from the repository, then in the Arduino IDE go to Sketch and then Import Library, and point the file dialogue at the Brain.zip file you downloaded. The second is manual, where you download the same release, decompress it, rename the folder to Brain, and drag that folder into the libraries folder inside your sketch folder. On a Mac that folder is Documents/Arduino/libraries by default, and the documentation notes you may need to create it if it does not exist, and you restart the Arduino environment afterwards. The name matters, because the project was renamed from Arduino-Brain-Library to simply Brain in 2014 so that it would show up properly in the IDE's new Sketch and Import Library menu, and a folder with the old name will confuse that listing.

## The API is small, and the error string is worth printing

The function list is short enough to hold in your head. `update()` goes in the loop and tells you whether a new packet arrived. `readCSV()` gives the comma delimited line, `readErrors()` gives a character string with the most recent errors, which the documentation recommends printing over serial when something is not working. The individual readers return the values in their natural types, a `byte` for signal quality, attention and meditation, and an `unsigned long` for the EEG band values, with `readPowerArray()` returning all eight at once in the same order as the CSV. The per band readers are named after the band and carry the frequency range in the documentation, delta at 1 to 3 Hz, theta at 4 to 7, low alpha at 8 to 9, high alpha at 10 to 12, low beta at 13 to 17, high beta at 18 to 30, low gamma at 31 to 40 and high gamma at 41 to 50, each with the state it is usually associated with. Using the typed readers rather than parsing the CSV is what saves the memory and the effort of string handling on a microcontroller.

## Half duplex, slow packets and a branch you should ignore

The minutiae section covers the hardware realities that decide whether your sketch works. The connection to the headset is half duplex, so it uses the RX pin of the Arduino, and you can still send data back to a PC over USB, but you cannot send data to the Arduino from the PC while the headset is connected. If you need the hardware serial for full duplex, the documentation points to a software serial connection and mentions a separate branch of the library designed for NewSoftSerial, while warning in bold that you should not use the old softserial branch. There is also a note that brain data comes quite slowly, with a fresh packet expected roughly every second, which matters because a sketch that polls in a tight loop will simply read the same value many times, and one that assumes a steady stream will look broken. Three examples ship with the library, BrainBlinker.ino blinks an LED faster as the attention value rises, BrainSerialTest.ino prints the CSV over serial, and BrainSoftSerialTest.ino reads over SoftwareSerial and prints over the hardware port.

## What the repository looks like now

The tree is what you would expect from a small, well behaved Arduino library. There is `Brain.cpp` and `Brain.h` at the root, an `examples/` directory with the three sketches, a `library.properties` file and a `keywords.txt` file that the Arduino IDE uses for syntax highlighting of the library's names, and a `codemeta.json` file carrying the metadata that research tooling expects. The licensing is split in the usual way, with `COPYING` and `COPYING.LESSER` for LGPL-3.0, and the LGPL was chosen so that the library can be used in closed projects as long as the library itself stays available. On the state of the project, the facts are these: the release list shows a single tagged version, v1.0 from 2014-01-19, and the last push to the repository was on 2026-10-18. The code is small and self contained, the hardware it supports is old, and the one thing that would change the library most, adding support for the newer Neurosky headsets, is exactly what the author says they have no hardware access to test.

## Conclusion

Brain suits a maker with a Star Wars Force Trainer or a Mattel MindFlex who wants to build something that reacts to attention or meditation values, and it suits a teaching project where a headset that used to be a toy becomes a live sensor. It is a poor fit if you own a Force Trainer II or a MindWave Mobile 2, because the documentation states plainly that those will not work, and it is a poor fit if you intend to do anything quantitative with the EEG bands, since the values are a heavily filtered representation that cannot be mapped to physical units. Before you buy hardware, check three things: which headset model you have, that the library sits on the hardware serial port with the half duplex limitation in mind, and that you read the data slowly, since a fresh packet arrives roughly once a second.

## FAQ

### Which headsets work with the Brain Arduino library?

The tested devices are the Star Wars Force Trainer and the Mattel MindFlex. The Star Wars Force Trainer II and the Neurosky MindWave Mobile 2 are listed as not compatible, and the library expects a specific serial protocol, so other hardware produces serial or parsing errors.

### How do I install the Brain library in the Arduino IDE?

Download the latest release from the repository, then in the Arduino IDE choose Sketch and Import Library and point the file dialogue at the downloaded Brain.zip file. The manual route is to decompress the release, rename the folder to Brain and drag it into the libraries folder inside your sketch folder, then restart the Arduino environment.

### What does the signal strength value mean in the Brain library?

It runs from 0 to 200 and counts backwards from the name. 0 means the unit has connected successfully and 200 means there is no signal, so a small number is a good connection. The attention and meditation values run from 0 to 100 with higher meaning more.

### Can I use the Brain library with a software serial connection?

Yes, and the documentation says it may be worth it, since the headset connection is half duplex and occupies the RX pin. It points to a separate branch designed for NewSoftSerial while warning against the old softserial branch, and one of the bundled examples, BrainSoftSerialTest.ino, reads over software serial and prints over the hardware port.

### How often does brain data arrive from a Neurosky headset?

The documentation says brain data comes quite slowly and that you should expect a fresh packet about every second. The update() function returns true when a fresh packet has arrived, so a sketch can use that flag rather than assuming new values on every pass of its loop.

## Sources

- [kitschpatrol/brain on GitHub](https://github.com/kitschpatrol/brain)
- [License: LGPL-3.0](https://github.com/kitschpatrol/brain/blob/main/LICENSE)
- [Project website](https://frontiernerds.com/brain-hack)
- [README](https://github.com/kitschpatrol/brain/blob/main/README.md)
- [Releases](https://github.com/kitschpatrol/brain/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kitschpatrol-brain