261 lines (209 with data), 6.9 kB

= Emotiv EEG Protocol Documentation

By Daeken, Eguru, qDot
Version 1.0, 2012-05-26

== Introduction

This document gives an overview of the communications and obfuscation
mechanisms for the Emotiv EEG Headset. It covers the raw data
transmission protocols, as well as the techniques used to lock down
the system. 

This document does not cover the inner working of any of the Emotiv
SDK or Suites used on top of the raw data. It exists mainly for those
interested in doing research with raw wave processing software such as
OpenVibe and BrainBay.

== Communications Mechanisms

The Emotiv EEG communicates via a proprietary wireless protocol to a
USB dongle hooked to the host computer. The USB dongle identifies as a
USB HID device, emitting 32-byte reports at a rate of 128hz when the
headset is on and in range. No data is ever written to the dongle or
head, only read from them.

Each report contains the following information:

* Packet Counter
* Battery Level
* Contact Quality
* Contact Sensor Readings
* Gyro Sensor Readings

== Cryptography

=== Information and History

To ensure that raw data is only read by those that have paid for the
raw data license, each USB dongle encrypts incoming wireless data via
AES against a key composed of the Serial Number (relayed in the USB
feature report descriptor for the HID endpoint) of the dongle before
emitting it as an HID report. It is assumed that data coming to the
dongle from the wireless protocol is unencrypted, and all encryption
happens on the dongle.

While one would figure that dongles would have unique serials, this
was not necessarily the case for the first year or so of emotiv
development, and cracked decryption keys could be passed around as
long as serials for USB dongles matched. However, later headsets now
have unique serials per USB dongle.

Initial key extraction techniques can be found at "Announcement.md"
documentation in the emokit repository.

=== Key Strategy

To create a 128-bit key to decrypt incoming data from the usb dongle,
we first need to request a feature report from the device that
contains whether the device is a consumer or research headset. This
fact changes the makeup of the key.

Serial numbers are fetched via the feature report for the HID
endpoint. Serial numbers are 16 byte strings of the format:

-------
SNXXXXXXXXXXYYYY
-------

Where Xs and Ys are usually numbers. The last 4 characters of the
serial number are what are used to create the key. It's interesting to
note that sometimes serials have dates embedded in them, i.e.

-------
SN20120526998912
-------

The date is probably the day the usb dongle was flashed. 

For the research headset, the key is composed of the following values:

-------
[15] 0x00 [14] 0x54 [13] 0x10 [12] 0x42 [15] 0x00 [14] 0x48 [13] 0x00 [12] 0x50
-------

For the consumer headset, the key is composed of the following values:

-------
[15] 0x00 [14] 0x48 [13] 0x00 [12] 0x54 [15] 0x10 [14] 0x42 [13] 0x00 [12] 0x50
-------

Where the numbers in brackets are indexes of the serial string
retrieved from the USB feature report descriptor. So for instance, if
a serial number for a consumer headset is

-------
SN20120526998912
-------

The characters we're interested in are the last 4:

-------
8 [0x38] 9 [0x39] 1 [0x31] 2 [0x32]
-------

Then the resulting crypto key will be 

-------
0x32 0x00 0x31 0x48 0x39 0x00 0x38 0x54 0x32 0x10 0x31 0x42 0x39 0x00 0x38 0x50
-------

== Packet Analysis

32-byte packets are received from the USB device at 128hz. Update
rates within that packet are:

* Sensor Data - 128hz
* Gyro Data - 128hz
* Battery - 1hz
* Sensor Quality - 1hz-16hz (Depending on sensor)

=== Packet Layout

An Overview of the 256-bit Packet Layout:

|=============================
| Bit Indexes | Used for
| 0:7   | Counter/Battery
| 8:21  | F3 Data
| 22:35 | FC5 Data
| 36:49 | AF3 Data
| 50:63 | F7 Data
| 64:77 | T7 Data
| 78:91 | P7 Data
| 92:105 | O1 Data
| 107:120 | Connection Quality (Rotating)
| 121:133 | ?
| 134:147 | O2 Data
| 148:161 | P8 Data
| 162:175 | T8 Data
| 176:189 | F8 Data
| 190:203 | AF4 Data
| 204:217 | FC6 Data
| 218:231 | F4 Data
| 233:239 | Gyro X
| 240:247 | Gyro Y
| 248:255 | ?
|=============================

=== Counter and Battery

The first byte of each packet can denote one of two things: the packet
count, or the battery power level.

Packet count makes up the lower 7 bits of the first byte. If the
highest bit is a 1, then the battery level is being relayed. This
happens once per second.

Packet count goes from 0-127, then transmits a battery power packet,
then wraps back to 0. This can be used to detect dropped packets. The
battery power packet will always have the highest bit set to 1.

Battery count is read via this table:

|============================
| Value		| Battery Level (%)
| >= 248  | ~100
|    247  | 99.93
|    246  | 97.02
|    245  | 93.40
|    244  | 89.45
|    243  | 85.23
|    242  | 81.89
|    241  | 76.77
|    240  | 71.54
|    239  | 66.59
|    238  | 61.92
|    237  | 55.37
|    236  | 45.93
|    235  | 32.34
|    234  | 20.43
|    233  | 12.37
|    232  |  5.08
|    231  |  3.63
|    230  |  2.80
|    229  |  2.05
|    228  |  1.42
|    227  |  0.88
|    226  |  0.42
|    225  |  0
|  < 225  |  ~0
|============================

=== Contact Readings

Readings from the contacts are available as 14 bit values, with each
sensor sending at 128hz. The values are interspered throughout the
packet. See the Packet Layout section for which sensors are covered by
each bit range.

=== Contact Quality

Contact quality consists of 14 bits, and refers to the contact quality
of the sensor as an amplitude of its calibration signal. The sensor
context of the field changes based on the value of the packet counter
in the first byte. For instance, a counter value of 1 means the packet
is showing the quality for sensor FC5, while a counter value of 2
means that the packet is showing the quality for sensor AF3, and
so on.

The following list shows the order that the sensors are listed in, in
relation to the counter, starting with counter = 0.

|============================
| Counter Index | Contact	
| 0 | F3
| 1 | FC5
| 2 | AF3
| 3 | F7
| 4 | T7
| 5 | P7
| 6 | O1
| 7 | O2
| 8 | P8
| 9 | T8
| 10 | F8
| 11 | AF4
| 12 | FC6
| 13 | F4
| 14 | F8
| 15 | AF4
| 16-63 | Unknown?
| 64 | F3
| 65 | FC5
| 66 | AF3
| 67 | F7
| 68 | T7
| 69 | P7
| 70 | O1
| 71 | O2
| 72 | P8
| 73 | T8
| 74 | F8
| 75 | AF4
| 76 | FC6
| 77 | F4
| 78 | F8
| 79 | AF4
| 80 | FC6
| .. | 77-80 Pattern repeats until counter hits 127
|============================

To get a useful reading, divide each readout by ~540. A value of
0.8-1.0 means a "good" contact.

=== Gyros

Gyro readings are available for 2 axes (head turned left/right and
foreward/back). These are 8-bit values that update at a rate of 128hz,
with 7-bits of resolution on either side of the median point for the
turn.