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



  1. hi I got this error when initializing: Exception AttributeError: "'NoneType' object has no attribute 'close'" in > ignored
    can you help me with that?

    1. Hi, did you managed to solve this problem?

    2. Which particular line throws that error?

    3. On the face of it, it looks as if there is some problem with initializing the serial port.

  2. Could you elucidate how the bluetooth pairing in ubuntu is done? When I scan using
    hcitool, my device is not detecting mindwave.

    1. It has been almost 2 years since I worked on mindwave, and I see that your comment is quite old. I am sorry for not replying earlier.
      If your mindwave is not getting detected you can try doing two things
      1. turn off and then turn it on while your computer is scanning for devices.
      2. The button on midwave has three positions; on, off, and then there is one more beyond on which can be used to enter pairing mode. Press and hold the button in the last mode and the blue LED on mindwave will start blinking, indicating that it has entered pairing mode. You might have to try this several times to succeed, sometimes it starts blinking a red LED, which is not what we want.
      Although this might not help you now, it might help someone else stuck in the same problem.

  3. hi dudu, are you working with mindset or mindwave? thank you

    1. Not now, but previously I had made a project on it.

  4. This comment has been removed by the author.

  5. I can get the device to connect, but when I try to print any variable, it only outputs 0. I am using object1=NeuroPy("/dev/tty.MindWave",57600) on a macbook, and simply issuing the commands variable1=object1.rawValue and print variable1. Do you have any suggestions?

  6. I can get the device to connect, but when I try to print any variable, it only outputs 0. I am using object1=NeuroPy("/dev/tty.MindWave",57600) on a macbook, and simply issuing the commands variable1=object1.rawValue and print variable1. Do you have any suggestions?

  7. Are the callbacks working?
    Why don't you open an issue on Github itself. It will be easy to track problems there.