Thursday, 30 May 2013

NeuroPy : Python library for interfacing with Neurosky's Mindwave eeg headset

Neurosky Mindwave is a miniature eeg machine which i used in a project to control a harware based on our thoughts. It involved taking eeg data from the headset and then performing certain actions based on it.
Neurosky provides a lot of developmental resources and sdks and libraries for various platforms.
The support for Python However was missing.

To obtain data from the headset using python i had to write my own library, NeuroPy  based on the excellent description of the protocol provided by the company (google for mindset_communications_protocol).
The headset establishes a spp (serial port profile) connection over Bluetooth thus receiving and transmitting data is as easy as communicating with any other serial port.

The packet structure is fairly easy to understand from the document thus any description of it is not given here. However using the library is explained.

imp. :this library need pyserial for it's operation, thus make sure that dependencies are satisfied. (it also requires thread module but that is available in a standard python installation, pyserial can be downloaded from PyPi)


  1. Download the source distribution (zip file) from dist directory
  2. unzip and navigate to the folder containing and other files
  3. run the following command: python install
There are three main steps involved in connecting the headset to the mindwave headset then a subsequent 4th step which is explained below can be used to fetch data from the device.

  1. Pairing the device

    In windows the bluetooth device can be paired by clicking 'add new device' in the 'devices and printers' settings dialogue. Mindwave will reserve a virtual COM port for it, such as COM1 or COM2. To know which port is reserved check properties of mindwave, which will be visible in 'devices and printers' section

    In linux tools such as rfcomm can be used to pair. After pairing take a note of the device in the /dev/ directory allocated to the headset. I paired the headset using information given on the following links:
  2. Once the device is paired the library can be initialised in the following manner:
    object1=NeuroPy("COM6",57600) #windows
  3. The library provides data in two ways, either via callback mechanism or via accessing the required properties (variables for eg. object1.attention to get value for attention). This is explained in step 4.
    If required the callbacks are set and the start method is called.
  4. The data from the device can be obtained using either of the following methods or both of them together:

    a) Obtaining value: variable1=object1.attention #to get value of attention

    #other variables: attention,meditation,rawValue,delta,theta,lowAlpha,highAlpha,lowBeta,highBeta,lowGamma,midGamma, poorSignal and blinkStrength

    b) Setting callback:a call back can be associated with all the above variables so that a function is called when the variable is updated.
    Syntax: setCallBack("variable",callback_function)
    for eg. to set a callback for attention data the syntax will be setCallBack("attention",callback_function)

Sample Program

from NeuroPy import NeuroPy
object1=NeuroPy("COM6") #If port not given 57600 is automatically assumed
                        #object1=NeuroPy("/dev/rfcomm0") for linux
def attention_callback(attention_value):
    "this function will be called everytime NeuroPy has a new value for attention"
    print "Value of attention is",attention_value
    #do other stuff (fire a rocket), based on the obtained value of attention_value
    #do some more stuff
    return None

#set call back:

#call start method

while True:
    if(object1.meditation>70): #another way of accessing data provided by headset (1st being call backs)
        object1.stop()         #if meditation level reaches above 70, stop fetching data from the headset