The Application programming interface (API)

From Neuroelectric's Wiki
Jump to: navigation, search

The Enobio sensor can be interfaced by third-party applications using its well-documented API. This API's area available on demand, please contact your sales representative to get it.

Contents

API content

The Enobio API distribution package consists on the following:

- Enobio3GAPI folder which contains the header of the Enobio API classes and
   - documentation folder, in doxygen-style
   - libs folder with the dll binaries.
- EnobioAPIExample_Qt_mingw, which contains an example that is made with the Qt libraries and the mingw compiler.
- EnobioAPIExample_VC2010, which contains an example that is made with Visual Studio 2010.
- EnobioAPIExample_.NET, which contains a wrapper of the API classes to be used in .NET along with an example in C#.

API explanation

The Enobio API consists on a set of classes that permit the access to the Enobio device and the data that it provides.

The main class to access the device is Enobio3G. This class provides methods for opening the device, starting and stopping the data streaming and configuring the device.

The access to both the data streaming and the device status is made through a producer-consumer protocol. The Enobio raw data streaming is accessed through the producer Enobio3G::ENOBIO_DATA. The device status is accessed through the producer Enobio3G::STATUS. By registering an implementation of the IDataConsumer virtual class with the Enobio3G::registerConsumer method the link between the producer and the consumer is made. Thus the Enobio class will call the IDataConsumer::receiveData method of all registered IDataConsumer implementations every time a new sample is available or the device status changes.

The actual data or status is passed as a parameter to the IDataConsumer::receiveData implementation through the PData class. The pointer returned by the PData::getData method shall be casted to the ChannelData or StatusData class depending on whether the implementation of the IDataConsume is registered to the Enobio3G::ENOBIO_DATA producer or the Enobio3G::STATUS one.

The implementation of the IDataConsumer::receiveData method shall take into consideration that it will be executed from a different thread than the Enobio one. So the operations done within the implementation shall be thread-safe.

Another consideration that the IDataConsumer::receiveData implementation shall take into account is that the data accessed through the PData::getData method is not accessible out of the scope of that method. That data is deleted inside the Enobio class when all the IDataConsumer implementations are called.

The API can calculate the power of the signals provided by Enobio in eight different bands: Delta (from 0.1 to 3.5 Hz), Theta (from 4.0 to 7.5 Hz), Alpha (from 8.0 to 13.0), Beta (from 14.0 to 30.0 Hz), Gamma (from 30.0 to 100.0 Hz), SMR band (from 12.0 to 15.0 Hz) and two user defined bands. To access these values, eight different producers are provided: Enobio3G::POWER_DELTA, Enobio3G::POWER_ALPHA, Enobio3G::POWER_ALPHA, Enobio3G::POWER_BETA, Enobio3G::POWER_GAMMA, Enobio3G::POWER_SMR, Enobio3G::POWER_USERDEFINED_1 and Enobio3G::POWER_USERDEFINED_2. The rate these producers provide a new power calculation can be controlled with the method Enobio3G::setPowerCalculationRate. The number of samples that are taken into consideration for the power calculation is controlled with the method Enobio3G::setPowerComputingLength. The user defined bands are selected by calling the methods Enobio3G::setUserDefinedBand1 and Enobio3G::setUserDefinedBand2.

The accelerometer is activated/deactivated by calling the Enobio3G::activateAccelerometer method before starting the EEG streaming. The data is received through the Enobio3G::ACCELEROMETER producer when the EEG streaming is ON.

The API can also configure up to five different power combination features. The combination of the power in some specific frequency bands for a set of channels placed on specific locations might provide relevant features (i.e. information regarding affective state). The Enobio3G::configurePowerCombinationFeatures method allows selecting up to two sets of channels that will be used to extract the feature of interest as well as the frequency bands for the two sets of channels and the mathematical operation to combine the power from the set of channels.

As an example, to extract information regarding valence the following configuration might be used: Perform the subtraction operation over the channel placed on F3 on the Alpha band and the channel placed on F4 filtered on the Alpha band too.

The length of the raw EEG signal which is used to perform the computations is defined by the Enobio3G::setPowerComputingLength method.

The obtained results are delivered through the Enobio3G::POWER_COMBINATION_FEATURE_X producers (being X a number from 0 to 4). The IDataConsumer::receiveData implementation connected to the producers shall cast the pointer obtained through PData::getData method to the ProcessedData class. The result of the combination is a single value stored on channel 0 of the class.

The results are delivered at rate defined by the Enobio3G::setPowerCalculationRate method.

Using the API

The following code is extracted from the examples that are provided in the Enobio API package.

Including the main Enobio API header:

#include "enobio3g.h"

Instantiate of the Enobio class:

Enobio3G _enobio;

Defining the Enobio data and status consumers:

class EnobioDataConsumer :  public IDataConsumer
{
public:
    void receiveData (const PData& data)
    {
      ChannelData * pData = (ChannelData *)data.getData();
      // Do whatever with the Enobio data
    }
};

class EnobioStatusConsumer : public IDataConsumer
{
public:
    void receiveData (const PData& data)
    {
      StatusData * pStatus = (StatusData *)data.getData();
      // Do whatever with the StatusData
    }
};

Instantiate the Data and Status consumers:

EnobioDataConsumer _enobioDataConsumer;
EnobioStatusConsumer _enobioStatusConsumer;

Registering the consumers:

_enobio.registerConsumer(Enobio3G::ENOBIO_DATA, _enobioDataConsumer);
_enobio.registerConsumer(Enobio3G::STATUS, _enobioStatusConsumer);

Making the conection to the Enobio device:

// mac address -> 00:07:80:XX:YY:ZZ
unsigned char mac[6];
mac[5] = 0x00;
mac[4] = 0x07;
mac[3] = 0x80;
mac[2] = 0x63;
mac[1] = 0xf7;
mac[0] = 0x78;

if(!_enobio.openDevice(mac))
{
 // report Error. Enobio might be switched off or out of battery.
}

Starting the EEG streaming:

_enobio.startStreaming();

Stopping the EEG streaming:

_enobio.stopStreaming();

Closing the Enobio connection:

_enobio.closeDevice();
Personal tools
Namespaces

Variants
Actions
BASIC USE
EEG APPLICATIONS
STIMULATION (tCS)
DATA ANALYSIS
ADVANCED
Toolbox