User Reference:Logging Input
BCI2000 allows you to record input from various input devices at sample resolution. Support for the mouse, keyboard and joystick is provided in the BCI2000 SignalSource framework by default, and is available in the downloadable binaries. Various other (more manufacturer-specific) loggers are also available, as listed on the Extensions page: integration of these optional loggers into your framework requires the use of CMake and a supported C++ compiler to rebuild your source module.
Device information is recorded into state variables, and recording is enabled by specifying appropriate command line options when starting a source module.
Input from keyboard, mouse, or joystick will occur asynchronously with respect to BCI2000's data processing. To account for this, input events are associated with time stamps, stored in a BCI2000 event queue, and assigned sample positions once data samples have been acquired.
When BCI2000 is distributed across multiple machines in a network, input devices must be attached to the machine that runs the data acquisition module. This is because time stamps of data acquisition and input events must refer to a common physical time base to allow associating input events with sample positions.
In Microsoft Windows, keyboard, mouse and joystick devices attached via USB are limited to a polling rate of 125Hz, corresponding to a temporal resolution of 8ms. When better timing resolution is required, you might consider recording into an additional analog channel, or using the amplifier's trigger input when available.
Logging input works in both Microsoft Windows, and macOS. On macOS, macOS specific key codes are translated into Windows virtual key codes.
On Linux, no system-wide API is available for receiving key press and mouse movement information. Instead, raw input events need to be read from /dev/input/eventX, and translated into virtual key codes by applying a keyboard layout. Also, the user must be member of a the group that owns the raw keyboard devices, typically input or plugdev.
For relative pointing devices, such as a typical mouse, only relative movement information is received from /dev/input/eventX. At the same time, modern desktop compositors such as Wayland, the successor of X11, no longer allow retrieving global mouse coordinates for security reasons. Thus, the Linux input logger cannot provide accurate mouse position, and integrates up relative mouse movement information instead.
Parameters
Logging parameters need to be specified from the command line that starts up the signal source module. For more information about command line options, see the Module Command Line Options page.
LogKeyboard
--LogKeyboard=1
When set to 1 from the command line, this parameter enables recording of keyboard events into the KeyDown and KeyUp state variables.
LogMouse
--LogMouse=1
When set to 1 from the command line, this parameter enables recording of mouse events.
LogJoystick
--LogJoystick=1
When set to 1 from the command line, this parameter enables recording of joystick state. To select which joystick is used, go to "Control Panel->Game Controllers," and click the "Advanced..." button. The device in the "Preferred device:" drop-down menu will be used in BCI2000.
On Linux, no joystick logger is available.
States
KeyDown, KeyUp
Key events. When a key is pressed, "KeyDown" will be set to the key's virtual key code at the corresponding sample position. When a key is released, the key code will be written into the "KeyUp" state variable.
MouseKeys
Mouse key state, with the left mouse button corresponding to bit 0, and the right mouse button corresponding to bit 1.
MousePosX, MousePosY
Mouse position in screen pixel coordinates with an additional offset of 32768, i.e. the main monitor's top left corner will be recorded as (32768,32768).
JoystickXpos, JoystickYpos, JoystickZpos
Position is recorded from Joystick #1. Each position state is ranging from 0 to 32767 with a resting position at 16384.
JoystickButtons1, JoystickButtons2, JoystickButtons3, JoystickButtons4
Joystick button information. Each button state is either 1 when pressed or 0 when not pressed.
See also
User Reference:KeystrokeFilter, Programming Tutorial:Implementing an Input Logger, User Reference:Module Command Line Options