This section introduces key concepts for using the Emotiv SDK to build software that is compatible with Emotiv headsets. It also walks you through some sample programs that demonstrate these concepts and serve as a tutorial to help you get started with the Emotiv API. The sample programs are written in C++ and are intended to be compiled with Microsoft Visual Studio 2005 (Visual Studio 2008 is also supported). They are installed with the Xavier SDK and are organized into a Microsoft Visual Studio 2005 solution, EmoTutorials.sln, which can be found in the \doc\Examples directory of your installation.
Introduction to the Xavier API and Emotiv EmoEngine
The Emotiv API is exposed as an ANSI C interface that is declared in 3 header files (edk.h, EmoStateDLL.h, edkErrorCode.h) and implemented in 2 Windows DLLs (edk.dll and edk_utils.dll). C or C++ applications that use the Emotiv API simply include edk.h and link with edk.dll.
The Emotiv EmoEngine refers to the logical abstraction of the functionality that Emotiv provides in edk.dll. The EmoEngine communicates with the Emotiv headset, receives preprocessed EEG and gyroscope data, manages user-specific or application-specific settings, performs post-processing, and translates the Emotiv detection results into an easy-to-use structure called an EmoState. Emotiv API functions that modify or retrieve EmoEngine settings are prefixed with “EE_.”
Integrating the EmoEngine and Emotiv EPOC with a videogame
An EmoState is an opaque data structure that contains the current state of the Emotiv detections, which, in turn, reflect the user’s facial, emotional and cognitive state. EmoState data is retrieved by Emotiv API functions that are prefixed with “ES_.” EmoStates and other Emotiv API data structures are typically referenced through opaque handles (e.g. EmoStateHandle and EmoEngineEventHandle). These data structures and their handles are allocated and freed using the appropriate Emotiv API functions (e.g. EE_EmoEngineEventCreate and EE_EmoEngineEventFree).
The above figure shows a high-level flow chart for applications that incorporate the EmoEngine. During initialization, and prior to calling Emotiv API functions, your application must establish a connection to the EmoEngine by calling EE_EngineConnect or EE_EngineRemoteConnect. Use EE_EngineConnect when you wish to communicate directly with an Emotiv headset. Use EE_EngineRemoteConnect if you are using SDKLite and/or wish to connect your application to XavierComposer or Emotiv Control Panel.
The EmoEngine communicates with your application by publishing events that can be retrieved by calling EE_EngineGetNextEvent(). For near real-time responsiveness, most applications should poll for new EmoStates at least 10-15 times per second. This is typically done in an application’s main event loop or, in the case of most videogames, when other input devices are periodically queried. Before your application terminates, the connection to EmoEngine should be explicitly closed by calling EE_EngineDisconnect().
There are three main categories of EmoEngine events that your application should handle:
- Hardware-related events: Events that communicate when users connect or disconnect Emotiv input devices to the computer (e.g. EE_UserAdded).
- New EmoState events: Events that communicate changes in the user’s facial, cognitive and emotional state. You can retrieve the updated EmoState by calling EE_EmoEngineEventGetEmoState(). (e.g. EE_EmoStateUpdated).
- Suite-specific events: Events related to training and configuring the Mental Commands and Performance Metrics detection suites (e.g. EE_CognitivEvent).
Most Xavier API functions are declared to return a value of type int. The return value should be checked to verify the correct operation of the API function call. Most Emotiv API functions return EDK_OK if they succeed. Error codes are defined in edkErrorCode.h and documented in Appendix 2.
Development Scenarios Supported by EE_EngineRemoteConnect
The EE_EngineRemoteConnect() API should be used in place of EE_EngineConnect() in the following circumstances:
- The application is being developed with Emotiv SDKLite. This version of the SDK does not include an Emotiv headset so all Emotiv API function calls communicate with XavierComposer, the EmoEngine emulator that is described in Section 4.2. XavierComposer listens on port 1726 so an application that wishes to connect to an instance of XavierComposer running on the same computer must call EE_EngineRemoteConnect(“127.0.0.1”, 1726).
- The developer wishes to test his application’s behavior in a deterministic fashion by manually selecting which Emotiv detection results to send to the application. In this case, the developer should connect to XavierComposer as described in the previous item.
- The developer wants to speed the development process by beginning his application integration with the EmoEngine and the Emotiv headset without having to construct all of the UI and application logic required to support detection tuning, training, profile management and headset contact quality feedback. To support this case, Emotiv Control Panel can act as a proxy for either the real, headset-integrated EmoEngine or XavierComposer. Control Panel listens on port 3008 so an application that wishes to connect to Control Panel must call EE_EngineRemoteConnect(“127.0.0.1”, 3008).
- Emotiv Xavier SDK uses function:
EE_HardwareGetVersion(unsigned int userId, unsigned long* pHwVersionOut);
This function will return the current hardware version of the headset and dongle for a particular user.
\param pHwVersionOut - hardware version for the user headset/dongle pair. hiword is the headset version, loword is the dongle version.
- EDK_ERROR_CODE = EDK_OK if successful
\sa EmoStateDll.h, edkErrorCode.h
We use 0x0565 for EPOC EEG, 0x1000 or 0x1E00 for EPOC non-EEG, 0x17B0 for Insight EEG, 0x0170 for Insight non-EEG.