ioHub Device and Device Event API

Devices and DeviceEvents refer to the classes associated with monitoring both physical and virtual devices, and bundling these data for use by the ioHub Process for storage in the ioDataStore and/or by the PsychoPy process for event handling in the experiment script.

The device and device event API has been designed to try and provide a consistent interface across different device and event types, only breaking from this common framework when required. Two abstract classes (i.e. you never get a instance of one of the classes directly) construct the basis for all Device and DeviceEvent classes used within the ioHub.

In general, attributes of a class are named using ‘_’ format (e.g., eventclass.device_time), while method names of a class use camel case format (i.e. deviceclass.getEvents() ). I find these notations make it very easy to distinguish attributes from methods or functions when scanning a code completion list for a class in your IDE of choice for example.

If device events are being saved to the ioDataStore, the hdf5 table for a given event class contains columns with the same names as the attributes of the event object that is stored in the table. This makes it somewhat easier to remember both event object attributes and event data storage tables formats.

Note

A user script never creates an instance of a Device or DeviceEvent class. The ioHub Event Framework creates all Device and DeviceEvent representations for PsychoPy Process as needed.

Note

Technically, the Device and DeviceEvent classes documented here are used by the ioHub Process only. The PsychoPy Process accesses the Device class instances via a dynamically created PsychoPy Process side class called an ioHubDeviceView. However, the ioHubDeviceView instance created on the PsychoPy Process associated with an actual ioHub Process Device instance has an identical public interface that is used by the PsychoPy script. Therefore, providing documentation for the ioHub Process Devices and DeviceEvents is also providing the API specification that can be used by the PsychoPy Process ( and it is much easier to document classes that exist for a period longer than just when the PsychoPy process runs.) :)

The Root Device and DeviceEvent Classes

All device and event types supported by the ioHub are extensions of two abstract class definitions.

ioHub Device Class

The parent class of all supported ioHub Device types.

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

Bases: psychopy.iohub.devices.ioObject

The Device class is the base class for all ioHub Device types. Any ioHub Device class (i.e Keyboard, Mouse, etc) also include the methods and attributes of this class.

name

The user defined name given to this device instance. A device name must be unique for all devices of the same type_id in a given experiment.

device_number

For device classes that support having multiple of the same type being monitored by the ioHub Process at the same time (for example XInput gamepads), device_number is used to indicate which of the connected devices of that type a given ioHub Device instance should connect to.

event_buffer_length

The maximum size ( in event objects ) of the device level event buffer for this device instance. If the buffer becomes full, when a new event is added, the oldest event in the buffer is removed.

monitor_event_types

A list of event class names that can be generated by this device type and should be monitored and reported by the ioHub Process.

manufacturer_name

The name of the manufacturer of the device.

model_name

The model of this Device subclasses instance. Some Device types explicitedly support different models of the device and use different logic in the ioHub Device implementation based on the model_name given.

model_number

Model number can be optionally used to hold the specific model number specified on the device.

software_version

The software version attribute can optionally be used to store the devices software / API version being used by the ioHub Device

hardware_version

The hardware version attribute can optionally be used to store the physical devices hardware version / revision.

firmware_version

The firmware version attribute can optionally be used to store the physical devices hardware version / revision.

serial_number

The unique serial number of the specific device instance being used, if applicable.

manufacture_date

The manufactured date of the specific device instance being used, if applicable.(Use DD-MM-YYYY string format.)

getConfiguration()[source]

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)[source]

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.
clearEvents()[source]

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

Note that calling clearEvents() atthe device level only clears the given device’s event buffer. The ioHub Process’s Global Event Buffer is unchanged.

Args:
None
Returns:
None
enableEventReporting(enabled=True)[source]

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.
isReportingEvents()[source]

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

Args: None

Returns:
(bool): Current reporting state.

ioHub DeviceEvent Class

The parent class of all ioHub DeviceEvents, regardless of the device type has generated the event.

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

Bases: psychopy.iohub.devices.ioObject

The DeviceEvent class is the base class for all ioHub DeviceEvent types.

Any ioHub DeviceEvent class (i.e MouseMoveEvent, MouseScrollEvent, MouseButtonPressEvent, KeyboardPressEvent, KeyboardReleaseEvent, etc.) also has access to the methods and attributes of the DeviceEvent class.

experiment_id

The ioHub DataStore experiment ID assigned to the experiment that is running when the event is collected. 0 indicates no experiment has been defined.

session_id

The ioHub DataStore session ID assigned for teh current experiment run. Each time the experiment script is run, a new session id is generated for use by the ioHub DataStore within the hdf5 file.

event_id

The id assigned to the current event instance. Every device event generated by the ioHub Process is assigned a unique id, starting from 0 for each session, incrementing by +1 for each new event.

type

The type id for the event. This is used to create DeviceEvent objects or dictionary representations of an event based on the data from an event value list. Event types are all defined in the iohub.constants.EventConstants class as class attributes.

device_time

If the device that generates an event type also time stamps the events, this field is the time of the event as given by the device, converted to sec.msec-usec for consistancy with all other device times. If the device that generates the event does not time stamp events, then the device_time is set to the logged_time for the event.

logged_time

The sec.msec time that the event was ‘received’ by the ioHub Process. For devices where the ioHub polls for events, this is the time that the poll method was called for the device and the event was retrieved. For devices that use the event callback to inform the ioHub of new events, this is the time the callback began to be executed. Time is in sec.msec-usec

time

The calculated ioHub time is in the normalized time base that all events share, regardless of device type. Time is calculated differently depending on the device and perhaps event type. Time is what should be used when comparing times of events across different devices or with times given py psychopy.core.getTime(). Time is in sec.msec-usec.

confidence_interval

This property attempts to give a sense of the amount to which the event time may be off relative to the true time the event may have become available to te ioHub Process. confidence_interval is calculated differently depending on the device and perhaps event types. In general though, the smaller the confidence_interval, the more accurate the calculated time of the event will be. For devices where a meaningful confidence_interval can not be calculated, a value of 0.0 is used. Valid confidence_interval values are in sec.msec-usec and will range from 0.000001 sec.msec-usec and higher.

delay

The delay of an event is the known (or estimated) delay from when the real world event occurred to when the ioHub received the event for processing. This is often called the real-time end-to-end delay of an event. If the delay for an event can not be reasonably estimated or is not known at all, a delay of 0.0 is set. Delays are in sec.msec-usec and valid values will range from 0.000001 sec.msec-usec and higher. the delay of an event is suptracted from the initially determined ioHub time for the eventso that the event.time attribute reports the actual event time as accurately as possible.

Device Type Constants

class psychopy.iohub.constants.DeviceConstants[source]

Bases: psychopy.iohub.constants.Constants

DeviceConstants provides access to the ioHub Device type constants, with methods to convert between the different associated constant value types for a given device type:

* int constant
* str constant
* device class associated with a constant

The DeviceConstants class is initialized when ioHub is started. All constants and methods available are class level attributes and methods. Therefore do nit ever create an instance of a Constants class; simply access it directly, such as:

int_kb_dev_constant=iohub.DeviceConstants.KEYBOARD
str_kb_dev_constant=iohub.DeviceConstants.getName(int_kb_dev_constant)
iohub_kb_dev_class=iohub.DeviceConstants.getClass(int_kb_dev_constant)

print 'Keyboard Device Type ID Constant: ',int_kb_dev_constant
print 'Keyboard Device Type String Name Constant: ',str_kb_dev_constant
print 'Keyboard Device Type ioHub Class: ',iohub_kb_dev_class
OTHER = 1

Constant for a Device Type not currently categoried.

KEYBOARD = 20

Constant for a Keyboard Device.

MOUSE = 30

Constant for a Mouse Device.

EYETRACKER = 50

Constant for an EyeTracker Device.

GAMEPAD = 80

Constant for Gamepad Device.

ANALOGINPUT = 120

Constant for an AnalogInput Device.

EXPERIMENT = 150

Constant for an Experiment Device.

DISPLAY = 190

Constant for a Display Device.

COMPUTER = 200

Constant for a Computer Device.

classmethod getClass(id)

Return the constant’s ioHub CLass Name given constant id. If no class is associated with the specified constant value, None is returned.

Args:
id (int): The constant’s id value to look-up the string name for.
Returns:
class: The ioHub class associated with the constant id provided.
classmethod getID(name)

Return the constant’s id given a valid constant name string.

Args:
name (str): The constant’s name value to look-up the int id for.
Returns:
int: The id for the given constant name.
classmethod getName(id)

Return the constant’s name given a valid constant id.

Args:
id (int): The constant’s id value to look-up the string name for.
Returns:
str: The name for the given constant id.

Device Event Type Constants

class psychopy.iohub.constants.EventConstants[source]

Bases: psychopy.iohub.constants.Constants

EventConstants provides access to the ioHub Device Event type constants, with methods to convert between the different associated constant value types for a given event type:

  • int constant
  • str constant
  • event class associated with a constant

The EventConstants class is initialized when ioHub is started. All constants and methods available are class level attributes and methods. Therefore do not ever create an instance of a Constants class; simply access it directly, such as:

int_kb_press_constant=iohub.EventConstants.KEYBOARD_PRESS
str_kb_press_constant=iohub.EventConstants.getName(int_kb_press_constant)
iohub_kb_press_class=iohub.EventConstants.getClass(int_kb_press_constant)

print 'Keyboard Press Event Type ID Constant: ',int_kb_press_constant
print 'Keyboard Press Event  Type String Name Constant: ',str_kb_press_constant
print 'Keyboard Press Event  Type ioHub Class: ',iohub_kb_press_class
KEYBOARD_PRESS = 22

Constant for a Keyboard Press Event.

KEYBOARD_RELEASE = 23

Constant for a Keyboard Release Event.

KEYBOARD_CHAR = 24

Constant for a Keyboard Char Event.

MOUSE_BUTTON_PRESS = 32

Constant for a Mouse Button Press Event.

MOUSE_BUTTON_RELEASE = 33

Constant for a Mouse Button Release Event.

MOUSE_DOUBLE_CLICK = 34

Constant for a Mouse Double Click Event. Deprecated for MOUSE_MULTI_CLICK in 0.6RC1

MOUSE_MULTI_CLICK = 34

Constant for a Mouse Multiple Click Event.

MOUSE_SCROLL = 35

Constant for a Mouse Scroll Wheel Event.

MOUSE_MOVE = 36

Constant for a Mouse Move Event.

MOUSE_DRAG = 37

Constant for a Mouse Drag Event.

MONOCULAR_EYE_SAMPLE = 51

Constant for an Eye Tracker Monocular Sample Event.

BINOCULAR_EYE_SAMPLE = 52

Constant for an Eye Tracker Binocular Sample Event.

FIXATION_START = 53

Constant for an Eye Tracker Fixation Start Event.

FIXATION_END = 54

Constant for an Eye Tracker Fixation End Event.

SACCADE_START = 55

Constant for an Eye Tracker Saccade Start Event.

SACCADE_END = 56

Constant for an Eye Tracker Saccade End Event.

Constant for an Eye Tracker Blink Start Event.

Constant for an Eye Tracker Blink End Event.

GAMEPAD_STATE_CHANGE = 81

Constant for a Gamepad Event.

MULTI_CHANNEL_ANALOG_INPUT = 122

Constant for an Eight Channel Analog Input Sample Event.

MESSAGE = 151

Constant for an Experiment Message Event.

LOG = 152

Constant for an Experiment Log Event.

classmethod getClass(id)

Return the constant’s ioHub CLass Name given constant id. If no class is associated with the specified constant value, None is returned.

Args:
id (int): The constant’s id value to look-up the string name for.
Returns:
class: The ioHub class associated with the constant id provided.
classmethod getID(name)

Return the constant’s id given a valid constant name string.

Args:
name (str): The constant’s name value to look-up the int id for.
Returns:
int: The id for the given constant name.
classmethod getName(id)

Return the constant’s name given a valid constant id.

Args:
id (int): The constant’s id value to look-up the string name for.
Returns:
str: The name for the given constant id.