The ioHub Keyboard Device

Platforms: Windows, OS X, Linux

class psychopy.iohub.devices.keyboard.Keyboard(*args, **kwargs)

Bases: psychopy.iohub.devices.keyboard.ioHubKeyboardDevice

enableEventReporting(enabled=True)

Specifies if the device should be reporting events to the ioHub Process (enabled=True) or whether the device should stop reporting events to the ioHub Process (enabled=False).

Args:
enabled (bool): True (default) == Start to report device events to the ioHub Process. False == Stop Reporting Events to the ioHub Process. Most Device types automatically start sending events to the ioHUb Process, however some devices like the EyeTracker and AnlogInput device’s do not. The setting to control this behavour is ‘auto_report_events’
Returns:
bool: The current reporting state.
getConfiguration()

Retrieve the configuration settings information used to create the device instance. This will be a combination of the default settings for the device (found in iohub.devices.<device_name>.default_,defice_name>.yaml, plus any device settings specified by the experiment author within an iohub_config.yaml file if the ioHubExperimentRuntime is being used to define the experiment logic, or if using the iohub.launchHubProcess() function in the experriment script, as device settings in dictionary form.

Changing any values in the returned dictionary has no effect on the device state.

Args:
None
Returns:
(dict): The dictionary of the device configuration settings used to create the device.
getEvents(*args, **kwargs)

Retrieve any DeviceEvents that have occurred since the last call to the device’s getEvents() or clearEvents() methods.

Note that calling getEvents() at a device level does not change the Global Event Buffer’s contents.

Args:

event_type_id (int): If specified, provides the ioHub DeviceEvent ID for which events should be returned for. Events that have occurred but do not match the event ID specified are ignored. Event type ID’s can be accessed via the EventConstants class; all available event types are class atttributes of EventConstants.

clearEvents (int): Can be used to indicate if the events being returned should also be removed from the device event buffer. True (the defualt) indicates to remove events being returned. False results in events being left in the device event buffer.

asType (str): Optional kwarg giving the object type to return events as. Valid values are ‘namedtuple’ (the default), ‘dict’, ‘list’, or ‘object’.

Returns:
(list): New events that the ioHub has received since the last getEvents() or clearEvents() call to the device. Events are ordered by the ioHub time of each event, older event at index 0. The event object type is determined by the asType parameter passed to the method. By default a namedtuple object is returned for each event.
isReportingEvents()

Returns whether a Device is currently reporting events to the ioHub Process.

Args: None

Returns:
(bool): Current reporting state.

Keyboard Device Configuration Settings

# This file includes all valid Keyboard Device
# settings that can be specified in an iohub_config.yaml
# or in Python dictionary form and passed to the launchHubServer
# method. Any device parameters not specified when the device class is
# created by the ioHub Process will be assigned the default value
# indicated here.
#
Keyboard:
    # name: The name you want to assign the keyboard device for the experiment
    #   This name is what will be used to access the device within the experiment
    #   script via the devices.[device_name] property of the ioHubConnection or
    #   ioHubExperimentRuntime classes.
    #
    name: keyboard

    # enable: Specifies if the device should be enabled by ioHub and monitored
    #   for events.
    #   True = Enable the device on the ioHub Server Process
    #   False = Disable the device on the ioHub Server Process. No keyboard events will
    #   be reported by the ioHub Server.
    #
    enable: True
 

    # monitor_event_types: Specified which device event types that should be monitored
    #   and therefore saved to the DataStore or sent to the Experiment Process.
    #
    monitor_event_types: [KeyboardPressEvent, KeyboardReleaseEvent, KeyboardCharEvent]

    # report_auto_repeat_press_events: Should the keyboard report key press events
    #   that are generated by the OS when a key is held down for an extended 
    #   period of time.
    #
    report_auto_repeat_press_events: False

    # saveEvents: *If* the ioHubDataStore is enabled for the experiment, then
    #   indicate if events for this device should be saved to the
    #   data_collection/keyboard event group in the hdf5 event file.
    #   True = Save events for this device to the ioDataStore.
    #   False = Do not save events for this device in the ioDataStore.
    #
    save_events: True

    # streamEvents: Indicate if events from this device should be made available
    #   during experiment runtime to the Experiment / PsychoPy Process.
    #   True = Send events for this device to  the Experiment Process in real-time.
    #   False = Do *not* send events for this device to the Experiment Process in real-time.
    #
    stream_events: True

    # auto_report_events: Indicate if events from this device should start being
    #   processed by the ioHub as soon as the device is loaded at the start of an experiment,
    #   or if events should only start to be monitored on the device when a call to the
    #   device's enableEventReporting method is made with a parameter value of True.
    #   True = Automatically start reporting events for this device when the experiment starts.
    #   False = Do not start reporting events for this device until enableEventReporting(True)
    #       is set for the device during experiment runtime.
    #
    auto_report_events: True

    # event_buffer_length: Specify the maximum number of events (for each
    #   event type the device produces) that can be stored by the ioHub Server
    #   before each new event results in the oldest event of the same type being
    #   discarded from the ioHub device event buffer.
    #
    event_buffer_length: 256

    # The device manufacturer's name.
    #   It is not used by the ioHub, so is FYI only.
    #
    manufacturer_name: N/A
    
    # The device number to assign to the device. 
    #   Device_number is not used by this device type.
    #
    device_number: 0

    # The serial number for the specific isnstance of device used
    #   can be specified here. It is not used by the ioHub, so is FYI only.
    #
    serial_number: N/A

    # manufacture_date: The date of manufactiurer of the device 
    # can be specified here. It is not used by the ioHub,
    # so is FYI only.
    #   
    manufacture_date: DD-MM-YYYY

    # The device model name can be specified here.
    #   It is not used by the ioHub, so is FYI only.
    #
    model_name: N/A

    # The device model number can be specified here.
    #   It is not used by the ioHub, so is FYI only.
    #
    model_number: N/A
    
    # The device driver and / or SDK software version number.
    #   This field is not used by ioHub, so is FYI only. 
    #
    software_version: N/A

    # The device's hardware version can be specified here.
    #   It is not used by the ioHub, so is FYI only.
    #
    hardware_version: N/A
    
    # If the device has firmware, its revision number
    #   can be indicated here. It is not used by the ioHub, so is FYI only.
    #
    firmware_version: N/A

Keyboard Event Types

class psychopy.iohub.devices.keyboard.KeyboardInputEvent(*args, **kwargs)[source]

Bases: psychopy.iohub.devices.DeviceEvent

The KeyboardInputEvent class is an abstract class that is the parent of all Keyboard related event types.

scan_code

The scan code for the keyboard event. This represents the physical key id on the keyboard layout. The Linux and Windows ioHub interface provide’s scan codes; the OS X implementation does not. int value

key_id

The keyboard independent, but OS dependent, representation of the key pressed. int value.

ucode

The utf-8 coe point for the key present, if it has one and can be determined. 0 otherwise. This value is, in most cases, calulated by taking the event.key value, determining if it is a unicode utf-8 encoded char, and if so, calling the Python built in function unichr(event.key). int value between 0 and 2**16.

key

A string representation of what key was pressed. For standard character ascii keys (a-z,A-Z,0-9, some punctuation values), and unicode utf-8 encoded characters that have been successfully detected, key will be the the actual key value pressed as a unicode character. For other keys, like the up arrow key or key modifiers like the left or right shift key, then a string representation of the key press is given, for example ‘UP’, ‘SHIFT_LEFT’, and ‘SHIFT_RIGHT’. In the case of the lattr, ucode will generally be 0.

modifiers

List of the modifiers that were active when the key was pressed, provide in online events as a list of the modifier constant labels specified in iohub.ModifierConstants list: Empty if no modifiers are pressed, otherwise each elemnt is the string name of a modifier constant.

window_id

The id or handle of the window that had focus when the key was pressed. long value.

class psychopy.iohub.devices.keyboard.KeyboardPressEvent(*args, **kwargs)[source]

Bases: psychopy.iohub.devices.keyboard.KeyboardKeyEvent

A KeyboardPressEvent is generated when a key is pressed down. The event is created prior to the keyboard key being released. If a key is held down for an extended period of time, multiple KeyboardPressEvent events may be generated depending on your OS and the OS’s settings for key repeat event creation.

If auto repeat key events are not desired at all, then the keyboard configuration setting ‘report_auto_repeat_press_events’ can be used to disable these events by having the ioHub Server filter the unwanted events out. By default this keyboard configuartion parameter is set to True.

Event Type ID: EventConstants.KEYBOARD_PRESS

Event Type String: ‘KEYBOARD_PRESS’

class psychopy.iohub.devices.keyboard.KeyboardReleaseEvent(*args, **kwargs)[source]

Bases: psychopy.iohub.devices.keyboard.KeyboardKeyEvent

A KeyboardReleaseEvent is generated when a key the keyboard is released.

Event Type ID: EventConstants.KEYBOARD_RELEASE

Event Type String: ‘KEYBOARD_RELEASE’

class psychopy.iohub.devices.keyboard.KeyboardCharEvent(*args, **kwargs)[source]

Bases: psychopy.iohub.devices.keyboard.KeyboardReleaseEvent

A KeyboardCharEvent is generated when a key on the keyboard is pressed and then released. The KeyboardKeyEvent includes information about the key that was released, as well as a refernce to the KeyboardPressEvent that is associated with the KeyboardReleaseEvent. Any auto-repeat functionality that may be created by the OS keyboard driver is ignored regardless of the keyboard device ‘report_auto_repeat_press_events’ configuration setting.

..note: A KeyboardCharEvent and the associated KeyboardReleaseEvent for it have
the same event.time value, as should be expected. The cuurent event sorting process result in the KeyboardCharEvent occuring right before the KeyboardReleaseEvent in an event list that has both together. While this is ‘technically’ valid since both events have the same event.time, it would be more intuitive and logical if the KeyboardReleaseEvent occurred just before the KeyboardCharEvent in an event list. This will be addressed at a later date.

Event Type ID: EventConstants.KEYBOARD_CHAR

Event Type String: ‘KEYBOARD_CHAR’

press_event

The pressEvent attribute of the KeyboardCharEvent contains a reference to the associated KeyboardPressEvent that the KeyboardCharEvent is based on. The press event is the first press of the key registered with the ioHub Server before the key is released, so any key auto repeat key events are always ignored. KeyboardPressEvent class type.

duration

The ioHub time difference between the KeyboardReleaseEvent and KeyboardPressEvent events that have formed the KeyboardCharEvent. float type. seconds.msec-usec format

Notes and Considerations

None at this time.