Blino Logo

Quick Start

pip install pinaps
pip install SC16IS750

sudo raspi-config
  • Select interfacing options from menu.
  • Select serial from menu.
  • Select no to shell use over serial.
  • Select yes to enabling serial port hardware.
sudo raspi-config
  • Select interfacing options from menu.

  • Select I2C from menu.

  • Select yes to enable ARM I2C interface.

Clone our examples repository somewhere appropriate:

git clone https://Blino_Tech@bitbucket.org/blino-dev/pinaps.git

Run an example script - don't forget to plug your electrodes in!

cd pi-naps_examples/

python meditate.py

Installation

The installation of the Pi-Naps library should be as simple as using pip to install the online distribution. From then onwards you can import it into your scripts and use the library classes (See Usage)

pip install pinaps

Alternatively, the original repository can be cloned into a directory and used locally from there:

git clone https://Blino_Tech@bitbucket.org/blino-dev/pinaps.git

This is the best way of running the examples straight away and testing the library out.

Installing I2C Driver

The Pi-Naps uses an I2C chip as an interface to communicate with the EEG sensor and for configuring some pinouts on the board. This requires a standalone driver which may need installing separately.

If you need to install the I2C driver separately required to use the Pi-Naps:

pip install SC16IS750

Alternatively, the original repository can be cloned into the Pi-Naps repository:

git clone https://github.com/Harri-Renney/SC16IS750-Python-Driver.git

(See https://github.com/Harri-Renney/SC16IS750-Python-Driver)

Serial Port Configuration

In order for you to use the serial interface on your Raspberry Pi Zero, you may need to configure the OS to enable its use.

1.Run raspi-config from command line.

sudo raspi-config

2.Select interfacing options from menu.

Serial Step 1

3.Select serial from menu.

Serial Step 2

4.Select no to shell use over serial.

Serial Step 3

5.Select yes to enabling serial port hardware.

Serial Step 4

I2C Configuration

In order for you to use the I2C interface on your Raspberry Pi Zero, you may need to configure the OS to enable its use.

1.Run raspi-config from command line.

sudo raspi-config

2.Select interfacing options from menu.

3.Select I2C from menu.

4.Select yes to enable ARM I2C interface.

Raspberry Pi Compatibility

Pi Zero

This shield is designed to fit the form factor of the Raspberry Pi Zero, facilitating the creation of portable and highly configurable Brain Computer Interfaces. It should be noted however, that due to the performance limitations of the Raspberry Pi Zero, not all features work correctly when using a Pi Zero and so it is important to see the documentation concerning Raspberry Pi integrations.

Current limitations are:

Note: We are working to provide solutions to these limitations and will be developing updates for Pi zero compatability through 2019.

Pi 3b

Using the Pi 3b currently facilitates access to the full potential of the Pi-Naps_v0.2 providing the option to record RAW EEG and FFT simultaneously.

Library

Usage

There are two main classes that cover all required functionality. The Pi-NapsController is for controlling the Pi-Naps hardware. The BlinoParser is used for parsing the data retrieved from the EEG sensor into the values that Pi-Naps can produce.

PiNapsController

The Pi-NapsController allows for control over the Pi-Naps shield, allowing access to LED and Button (Button: supported coming soon) as well as device configuration. The EEG Sensor is read from the Controller and data should be passed into the BlinoParser to parse into useful information.

The controller can also configure what pins EEG data is transferred over, allowing for configuration of your project in software.

It's important to import the PiNapsController with the form from pinaps.piNapsController import PiNapsController to ensure correct operation.

Below is a script demonstrating typical a typical setup and use of PiNapsController

from pinaps.piNapsController import PiNapsController
# First the controller is initalized and setup with desired control

# Create a PiNapsController object:
controller = PiNapsController()

# Select how Pi-Naps is controlled : options are using I2C or UART. 
# If you are unsure we recommend I2C for maximising compatability and functionality.
controller.setControlInterfaceI2C()

# Setup the use of I2C interface in communication with EEG sensor chip:
controller.setEEGSensorInterfaceI2C()

# Set the desired mode for the EEG chip to operate in.

#For Raspberry Pi Zero: 
# ONlY BASIC MODE IS CURRENTLY SUPPORTED
controller.setModeBasic()

#Raspberry Pi 3 etc have full access....
# controller.setModeEEGRaw()
# controller.setModeFFT()


# From this point, any available EEG data from the board when ready can be detected using:
while(1):
    if(controller.dataWaiting() > 0):
        data = controller.readEEGSensor()
        #We then parse data to the parser to make more sense of it!
        parser.parseByte(data)

We may consider these modes in more detail:

Control Interface

The control interface is the setting describing how the Raspberry Pi and Pi-Naps shield should comunicate. You may control the shield using the I2C bus (which is recomended for full featured operation), or using the GPIO pins.

In general, we recommend using the I2C setting and would only change this, if we had a specific reason to completely reserve the I2C bus.

# Functions for configuration of Controlling Pi-Naps 

from pinaps.piNapsController import PiNapsController

controller = PinapsController()

# We have two main ways to set the control method

# Using a parameter
controller.setControlInterface(controller.Control.I2C)
controller.setControlInterface(controller.Control.GPIO)
# Etc ...

# Or with a direct function call for more convenience

controller.setControlInterfaceI2C()
controller.setControlInterfaceGPIO()
# Etc ...

EEG Sensor Interface

The EEG sensor interface allows you to set the pins over which the EEG data itself is transfered. Again we recomend I2C for this, however this can also be set to use UART. Again, this is done to allow for avoiding collisions with other projects or devices.

# Functions for configuration of setting Pi-Naps EEG sensor communication channel

from pinaps.piNapsController import PiNapsController

controller = PinapsController()

# We have two main ways to set the control method

# Using a parameter
controller.setEEGSensorInterface(controller.Interface.I2C)
controller.setEEGSensorInterface(controller.Interface.UART)

# Etc ...

# Or with a direct function call for more convenience
controller.setEEGSensorInterfaceI2C()
controller.setEEGSensorInterfaceUART()
# Etc ...

Pi-Naps Mode (Data Output Mode)

The 'Mode' configures what data the EEG sensor produces.

Notably: The Rasberry Pi Zero can currently only operate in Basic Mode.

The Modes are as follows:

setBasicMode()

Basic mode provides the following data points: - Signal Quality - Meditation Value - Attention Value - EEG powers ( FFT )

setRawEEGMode()

Raw EEG mode provides the following data points:

  • Signal Quality
  • Meditation Value
  • Attention Value
  • Raw EEG Signal

setFFTMode()

FFT mode provides the following data points:

  • Signal Quality
  • Meditation Value
  • Attention Value
  • Raw EEG Signal
  • EEG powers ( FFT ) ​

BlinoParser

The Blino parser, transaltes the stream of bytes from the Pi-Naps into meaningful more information. It's important to import the BlinoParser correctly. Just use the following code at the beginning of your script if you are unsure.

from pinaps.blinoParser import BlinoParser

There are two methods for working with the parsed information:

1. Callbacks

The prefered method for handling data is to use callbacks. We simply create a function to work with the relevant data and then register that function for use with

Here a function is defined, simply to print the attention value:

def onAttentionRecieved(attention):
    print("Attention value: %d" % attention)
...

Now when a parser is created, and processes a new attention value a callback is triggered. If we register the previously defined callback, it will execute on every new value recieved.

We may register the function as follows:

#Create parser.
parser = BlinoParser()  
#Register the attentionCallback function with the parser.
parser.attentionCallback = onAttentionRecieved 

2. Returning Packets

The parseByte function returns the latest packet. It is advisable to check with a conditional that the packet has been updated before using it. This is advised as not every iteration a byte is parsed is new information updated in the packet. Check the object's "updated" member variable.

returnedPacket = parser.parseByte(data)

if(returnedPacket.updated):
    print("Delta Value = %d" % returnedPacket.EEGPower.delta)

Alternatively, the latest packet can be retrieved from the parsedPacket:

currentPacket = parser.parsedPacket
print("meditation value = %d" % currentPacket.meditation)

Troubleshooting

Pip Install

If you're having trouble using pip install. Try using:

python -m pip install --index-url https://pypi.org/simple/ example_pkg

Where the url is the project url and the example_pkg is the package you wish to install.

Python Library Path

You might be having a lot of trouble finding where to install the libraries manually for global use. On raspbian it should look something like this: "usr/local/lib/python2.7/dist-packages"

A lot of unnecessary trouble can come of this, especially if you are not confident in using linux and more specifically Raspbian. In which case, we advise to just clone the repository into a local directory and create your script in there, with the library files in the same directory.

___Additional Dependencies Error__

During pip install of Pi-Naps. If an error occours specifically around installing any addtional dependencies. Use --no-dependencies flag.