mainpage.md
Go to the documentation of this file.
3 This API document will help you to use the Emotiv SDK to build software that is compatible with Emotiv headsets.
5 For examples and latest releases please check out the [Github repository](https://github.com/Emotiv). There are some sample programs that demonstrate these concepts and serve as a tutorial to help you get started with the Emotiv API.
9 The Emotiv SDK is exposed as an ANSI C interface that is declared in 5 header files (Iedk.h, IEmoStateDLL.h, IedkErrorCode.h, FacialExpressionDetection.h, MentalCommandDetection.h). Applications that use the Emotiv API simply include Iedk.h and link with platform dependent library files.
11 The Emotiv EmoEngine refers to the logical abstraction of the functionality that Emotiv provides in the run-time library. 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 **IEE_**.
15 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 **IS_**. 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 (i.e. IEE_EmoEngineEventCreate() and IEE_EmoEngineEventFree()).
17 During initialization, and prior to calling Emotiv API functions, your application must establish a connection to the EmoEngine by calling IEE_EngineConnect() or IEE_EngineRemoteConnect(). Use IEE_EngineConnect() when you wish to communicate directly with an Emotiv headset. Use IEE_EngineRemoteConnect() if you wish to connect your application to EmoComposer or Emotiv Control Panel.
19 The EmoEngine communicates with your application by publishing events that can be retrieved by calling IEE_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 IEE_EngineDisconnect().
24 Events that communicate when users connect or disconnect Emotiv input devices to the computer (e.g. IEE_UserAdded, IEE_UserRemoved).
27 Events that communicate changes in the user’s FacialExpression and MentalCommands state. You can retrieve the updated EmoState by calling IEE_EmoEngineEventGetEmoState(). (e.g. IEE_EmoStateUpdated).
30 Events related to training and configuring the FacialExpression and MentalCommands detection suites (e.g. IEE_MentalCommandEvent_t).
32 Most 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 IedkErrorCode.h.
36 The IEE_EngineRemoteConnect() API should be used in place of IEE_EngineConnect() in the following circumstances:
38 * The application is being developed with Emotiv SDK Lite. This version of the SDK does not communicate with an Emotiv headset, so all Emotiv API function calls communicate with EmoComposer - the EmoEngine emulator that is described [here](https://emotiv.zendesk.com/hc/en-us/articles/201458205-Emotiv-Xavier-Tools-XavierComposer-usage). EmoComposer listens on port 1726 so an application that wishes to connect to an instance of emulator running on the same computer must call IEE_EngineRemoteConnect(“127.0.0.1”, 1726).
40 * 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 EmoComposer as described previously.
42 * The developer wants to speed up 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. In this case, Emotiv Control Panel can act as a proxy for either the real, headset-integrated EmoEngine or EmoComposer. Control Panel listens on port 3008 so an application that wishes to connect to Control Panel must call IEE_EngineRemoteConnect(“127.0.0.1”, 3008).
