User-specific detection settings, including trained Mental Commands and Performance Metrics signature data, currently enabled Mental Commands actions, Mental Commands and Performance Metrics sensitivity settings, and Facial Expressions calibration data, are saved in a user profile that can be retrieved from the EmoEngine and restored at a later time.
This example demonstrates the API functions that can be used to manage a user’s profile within Emotiv EmoEngine™. Please note that this example requires the Boost C++ Library in order to build correctly. Boost is a modern, open source, peer-reviewed, C++ library with many powerful and useful components for general-purpose, cross-platform development. For more information and detailed instructions on installing the Boost library please visit http://www.boost.org.
EE_EngineConnect() or EE_EngineRemoteConnect() must be called before manipulating EmoEngine profiles. Profiles are attached to a special kind of event handle that is constructed by calling EE_ProfileEventCreate(). After successfully connecting to EmoEngine, a base profile, which contains initial settings for all detections, may be obtained via the API call EE_GetBaseProfile().
This function is not required in order to interact with the EmoEngine profile mechanism – a new user profile with all appropriate default settings is automatically created when a user connects to EmoEngine and the EE_UserAdded event is generated - it is, however, useful for certain types of applications that wish to maintain valid profile data for each saved user.
It is much more useful to be able to retrieve the custom settings of an active user. Listing 8 demonstrates how to retrieve this data from EmoEngine.
EE_GetUserProfile() is used to get the profile in use for a particular user. This function requires a valid user ID and an EmoEngineEventHandle previously obtained via a call to EE_ProfileEventCreate(). Once again, the return value should always be checked. If successful, an internal representation of the user’s profile will be attached to the EmoEngineEventHandle and a serialized, binary representation can be retrieved by using the EE_GetUserProfileSize()and EE_EngineGetUserProfileBytes() functions, as illustrated above.
The application is then free to manage this binary profile data in the manner that best fits its purpose and operating environment. For example, the application programmer may choose to save it to disk, persist it in a database or attach it to another app-specific data structure that holds its own per-user data.
EE_SetUserProfile() is used to dynamically set the profile for a particular user. In Listing 9, the profileBuf is a pointer to the buffer of the binary profile and profileSize is an integer storing the number of bytes of the buffer. The binary data can be obtained from the base profile if there is no previously saved profile, or if the application wants to return to the default settings. The return value should always be checked to ensure the request has been made successfully.
Examples one and two focused chiefly on the proper handling of the EE_EmoStateUpdated event to accomplish their tasks. Two new event types are required to properly manage EmoEngine profiles in Example 3:
- EE_UserAdded: Whenever a new Emotiv USB receiver is plugged into the computer, EmoEngine will generate an EE_UserAdded event. In this case, the application should create a mapping between the Emotiv user ID for the new device and any application-specific user identifier. The Emotiv USB receiver provides 4 LEDs that can be used to display a player number that is assigned by the application. After receiving the EE_UserAdded event, the EE_SetHardwarePlayerDisplay() function can be called to provide a visual indication of which receiver is being used by each player in a game.
- EE_UserRemoved: When an existing Emotiv USB receiver is removed from the host computer, EmoEngine™ will send an EE_UserRemoved event to the application and release internal resources associated with that Emotiv device. The user profile that is coupled with the removed Emotiv EPOC™ will be embedded in the event as well. The developer can retrieve the binary profile using the EE_GetUserProfileSize() and EE_GetUserProfileBytes() functions as described above. The binary profile can be saved onto disc to decrease memory usage, or kept in the memory to minimize the I/O overhead, and can be reused at a later time if the same user reconnects.