nh2/hemokit

Haskell library for the Emotiv EEG, inspired by the Emokit code

hemokit

Haskell library and tool suite for the Emotiv Epoc EEG, inspired by the Emokit code.

It currently only works on Linux and Windows - patches for other platforms are welcome, they should be trivial.

Download

You can download pre-built binaries here, or build it yourself via cabal install hemokit.

Library Features

• device discovery via hidapi
• decryption of the raw data (one-to-one port from from Emokit)
• convenient access to sensor values, gyro, qualities, battery, and raw data

Programs

Hemokit comes with example programs to

• hemokit-dump print out the current EEG data
• hemokit-mouse move the cursor using the gyro

Note that we have to use sudo in most of the cases because the HIDAP-hidraw implementation reads directly from a device file.

hemokit-dump - Examples

hemokit-dump can print EEG data, format it as JSON, serve it via TCP or Websockets, and read from real devices and dump files.

• Output EEG cumulative state for an automatically found device:

  sudo hemokit-dump

• Select one of many connected EEGs by serial number:

  sudo hemokit-dump --serial SN...GM

• Output only the data the device sends (no cumulative state), and format the output as JSON:

  sudo hemokit-dump --mode packets --format json

  The --format flag allows you to change the way the output is printed. The output of --mode state --format spaced is especially easy to work with.

• Instead of from a real device, read data recorded to a file, and serve it via JSON over a TCP server on port 1234:

  sudo cat /dev/hidraw1 > encrypted.dump  # Dump data to a file
  sudo hemokit-dump --from-file encrypted.dump --serial SN...GM --serve 0.0.0.0:1234 --format json

  Here you have to specify the serial since HIDAPI is not used to obtain it automatically.

  If you prefer a Websockets server over a raw TCP server, use ws://0.0.0.0:1234 instead.

• Output decrypted raw data to stdout:

  sudo hemokit-dump --mode raw

• Both print the data from the EEG and store the original data for later use:

  sudo cat /dev/hidraw1 | tee >(hemokit-dump --from-file - --serial SN...GM --format json) > encrypted.dump

  We use tee and shell process substitution to duplicate the data stream, and tell hemokit-dump to read from - (stdin).

Connecting with other Programs

• To use Hemokit as a data source from OpenVibe, check out the corresponding entry in the Wiki
• To read Hemokit data from Matlab, I recommend publishing the data on a local socket in text format using hemokit-dump --format spaced --serve 127.0.0.1:1234. Then you can read it with code like:

t = tcpip('127.0.0.1', 1234);
fopen(t)
data = fscanf(t, '%d');

hemokit's Issues

Installation Failure

I tried installing the hemokit-dump.exe but the execution file is not running.... Pls help me...

hemokit data has higher time stdev than emokit

I've taken some rough measurements of how long emokit_read_data_timeout and hemokit-dump's main loop take per iteration.

For this I modified:

int emokit_read_data_timeout(struct emokit_device* s, unsigned timeout)
{
    static uint64_t t_before = 0;
    struct timeval tv;
    gettimeofday(&tv, NULL);
    uint64_t t = ((uint64_t) tv.tv_sec)*1000000 + (uint64_t) tv.tv_usec;
    fprintf(stderr, "%lu\n", t - t_before);
    t_before = t;
    return hid_read_timeout(s->_dev, s->raw_frame, 32, timeout);
}

Results (times in microseconds):

	emokit (gettimeofday)	hemokit (getCurrentTime)
mean	7818.57	7662.45
std	410.32	725.25
std/mean	~5.2 %	9.5 %

So the distance between time measurements varies quite a bit more in Hemokit.

This wasn't measured properly though on the Hemokit side; for it to be a fair comparison, I should measure how long readEmotivRaw takes, not the time of a hemokit-dump loop.

trouble with dependencies

I'm trying to build this (hemokit-0.6.6.tar.gz from https://hackage.haskell.org/package/hemokit#readme ) project on Windows to get the raw data feed. I have no previous experience in neither haskell nor cabal.
installed pre-build .exe, plugged usb-receiver and connected epoc+, but no device found upon:

• hemokit-dump
• hemokit-dump --serial SN...GM (My serialN is EP20170108001BA0.. and usb receivers UDsomethingsomething)

as i understand from earlier posts the pre-build.exe built before vid&pid of 1234;ed02 beknown to writer, so I decided to compile and build the hemokit-dump myself as I believe there is no updated pre-build hemokit.exe.
installed haskell platform with ghci 8.2.1
installed cabal
updated cabal
tried to build homokit.cabal but received missing dependencies:

C:\Users\berkdi\Desktop\Neuroscience\BCI\hemokit-0.6.6>cabal build hemokit
Warning: The package list for 'hackage.haskell.org' does not exist. Run 'cabal
update' to download it.
Resolving dependencies...
Warning: solver failed to find a solution:
Could not resolve dependencies:
trying: hemokit-0.6.6 (user goal)
unknown package: split (dependency of hemokit-0.6.6)
fail (backjumping, conflict set: hemokit, split)
After searching the rest of the dependency tree exhaustively, these were the
goals I've had most trouble fulfilling: hemokit, splitTrying configure anyway.
Configuring hemokit-0.6.6...
cabal: Encountered missing dependencies:
aeson >=0.6.1.0,
cipher-aes >=0.2.0,
conduit >=1,
deepseq-generics >=0.1,
hidapi >=0.1.2,
mtl >=2.1.2,
network-simple >=0.4.0.2,
optparse-applicative >=0.11,
pretty-show >=1.0,
split >=0.2.2,
vector >=0.9,
websockets >=0.8.0.0

installed all of them with updated versions, tried to install it all, starting from the simpliest indicating to not cause any inter-dependent problem.

• text 0.11
• primitive

succeeded but starting with vector, it started needing more dependencies and base 4.10 fails to configure, instead it gives:

<interactive>:1:19: error:
    Not in scope: `System.IO.hSetBuffering'
    No module named `System.IO' is imported.

<interactive>:1:43: error:
    Not in scope: `System.IO.stdin'
etc..etc..

Moreover I believe some of these missing dependencies are already in C:\Program Files\Haskell\Platform\8.2.1\lib but still giving "couldnt find module" error upon compiling
with WinGHC the same error happens. Trying to install it with "cabal install base" also makes the base 4.10 get rejected, giving

only already installed instances can be used

, If someone could help me I would appreciate greatly. I don't know what to do next...or previously what should have been done.

Formatting for Openvibe

if I have the following data, how it will transfer?

EmotivState {counter = 34, battery = 70, gyroX = 115, gyroY = -39, sensors = fromList [8769,7945,8113,8658,8455,8767,8857,8351,7744,9585,8141,8019,8177,9101], qualities = fromList [24,24,0,0,8,24,16,0,0,8,16,8,16,24]}

You should use the --format spaced option, then the data will look like this:

$ ./hemokit-dump --format spaced
48 0 646 -1636 14260 5451 6184 15047 13613 6573 15294 9075 5637 9415 8906 4214 16064 4322 0 0 0 0 0 0 0 0 0 0 0 0 0 0
128 0 288 -1082 16339 731 9041 5104 3837 6126 1916 14906 9550 2759 10431 5920 6503 14713 0 0 0 0 0 0 0 0 0 0 0 0 0 0
42 0 -1340 -1270 3461 9534 11386 15808 9507 5725 3030 12763 6679 8898 3755 13544 2893 10611 0 0 0 0 0 0 0 0 0 0 0 0 0 0
...

I am working on a python script to convert the sensor values to a format openvibe can read.

i've looked over your code, and i see that these are 16-bit ints, big endian bytes. but i am
having trouble deciphering the values you have listed here.

i see here the format is:
'counter' 'battery' 'gyroX' 'gyroY' 'sensors'
'counter' 'battery' 'gyroX' 'gyroY' 'quality?'
'counter' 'battery' 'gyroX' 'gyroY' 'sensors'
etc.

Could you please step through how you would convert one of these values back to its original value?
for example:
'counter' 48 = 0000000110000000
? = 34

i've tried studying your code, but i am not very fluent with haskell.

thank you for your time.

No devices found

Hello,
I have installed hemokit latest version along with hidapi (@chpatrick) with no errorrs on a Linux Ubuntu 16.04 LTS system, but when I try to execute hemokit-dump (or any other programs), it results with the following error:

hemokit-dump: user error (No devices found.)

I have also installed separately on the same machine emokit (@qdot) and my Emotiv Epoc headset is being recognized both using the python scripts, and the executables files. The VID and PID of the headset are inserted in the rules file accordingly (in /etc/udev/rules.d), and the device is recognized under /dev/hidraw1 and 2 (lsusb command also shows the headset correctly).
Any hints? I have obviously not looked everywhere, so any help would be appreciated.
Thanks in advance

Sampling frequency

Hi
I run 'hemokit-dump --format spaced' on windows and put the data on a text file, but I don't know if the sampling frequency is 2048Hz or 128Hz. Which frequency is the right one?

Problem compiling / Not in scope: type constructor or class ‘NFData’

While trying to install hemokit on an up-to-date (ghc v8.0.1) Arch Linux system I got the following error message(s):

[...]
src/Hemokit.hs:530:10: error:
    Not in scope: type constructor or class ‘NFData’
    Perhaps you meant ‘Data’ (imported from Data.Data)
cabal: Leaving directory '.'
cabal: Error: some packages failed to install:
hemokit-0.6.6 failed during the building phase. The exception was:
ExitFailure 1

I could fix it by adding the following line again in ./src/Hemokit.hk:

import Control.DeepSeq

That line was previously changed to import Control.DeepSeq.Generics in 83c208d but it seems both lines are required now.

---

Other than that, I also had to remove the executable hemokit-mouse section in the hemokit.cabal file. Its dependency on robot, which in turn depends on xhb, could not satisfied: the installation of xhb fails on my system with the error message

Ambiguous occurrence ‘putInt8’

So far, I have no idea how to fix this but it's definitely an upstream bug in xhb.

error in building hemokit-mouse

I tried to load hemokit by the command cabal install hemokit, but the following error appear:
` [4 of 4] Compiling Hemokit.Start ( src/Hemokit/Start.hs, dist/build/Hemokit/Start.o )
In-place registering hemokit-0.6.4...
Preprocessing executable 'hemokit-mouse' for hemokit-0.6.4...
[1 of 1] Compiling Main ( apps/Mouse.hs, dist/build/hemokit-mouse/hemokit-mouse-tmp/Main.o )

apps/Mouse.hs:29:20:
Ambiguous occurrence connect' It could refer to eitherGraphics.XHB.Connection.connect',
imported from Graphics.XHB.Connection' at apps/Mouse.hs:6:43-49 orTest.Robot.connect',
imported from Test.Robot' at apps/Mouse.hs:9:1-27 (and originally defined inTest.Robot.Internal')

apps/Mouse.hs:38:7: Not in scope: runRobotWithConnection' Failed to install hemokit-0.6.4 cabal: Error: some packages failed to install: hemokit-0.6.4 failed during the building phase. The exception was: ExitFailure 1
Then I tried to build the source code, it's give me the above message, after run the command sudo runhaskell Setup.hs build , the following messaeg appear:

` Preprocessing executable 'hemokit-mouse' for hemokit-0.6.4...
[1 of 1] Compiling Main ( apps/Mouse.hs, dist/build/hemokit-mouse/hemokit-mouse-tmp/Main.o )

apps/Mouse.hs:29:20:
Ambiguous occurrence connect' It could refer to eitherGraphics.XHB.Connection.connect',
imported from Graphics.XHB.Connection' at apps/Mouse.hs:6:43-49 orTest.Robot.connect',
imported from Test.Robot' at apps/Mouse.hs:9:1-27 (and originally defined inTest.Robot.Internal')

apps/Mouse.hs:38:7: Not in scope: runRobotWithConnection'
note that both robotandxhb` are installed.

Reference Channels Excluded?

Hi, I'm working on a neurofeedback project with hemokit, and wondering why it only uses 14 channels rather than 16? The Emotiv Epoc, has 16 sensors. How can I add the reference channels? Or do I even need them? Are the reference channels being subtracted from the signals before the hemokit-dump is created? Is this processing taking place inside the headset?

Hemokit is sending data too slowly

From #4 (comment) with Openvibe:

Turning drift correction off in the Openvibe Acquisitor, I get after running it for 6000 seconds:

[  INF  ] Stopping the acquisition.
[WARNING] After 6013.4 seconds, theorical samples per second does not match real samples per second
[WARNING]   Received : 768928 samples
[WARNING]   Should have received : 769671 samples
[WARNING]   Drift was : -743 samples (-0.09%)
[WARNING]   The driver did not try to correct this difference

user error : no devices found

so this error states that no devices were found and quits (which would be nice to have a little delay before jumping out ;) )
should i uninstall the original drivers? or am i missing something bigger here?

hemokit-0.4.0 failed during the building phase

src/Hemokit.hs:525:46:
No instance for (NFData DeviceInfo)
arising from a use of genericRnf' Possible fix: add an instance declaration for (NFData DeviceInfo) In the expression: genericRnf In an equation forrnf': rnf = genericRnf
In the instance declaration for `NFData EmotivDeviceInfo'