The launchHubServer Function

Using the launchHubServer function to start the ioHub Process and gain access to the ioHub Event Framework is ideal when only the following ioHub Devices are needed:

For details on each of these ioHub device types, please refer to the device’s documentation page.

psychopy.iohub.client.launchHubServer(**kwargs)[source]

The launchHubServer function can be used to start the ioHub Process without the need to create experiment or iohub (.yaml) configuration files.

All values passed to the launchHubServer method must be kwarg inputs.

Valid keyword args that the launchHubServer function will process are:

  • experiment_code: The label being used for the experiment being run.
  • session_code: A unique session code for the current run of the experiment.
  • psychopy_monitor_name: The name of the PsychoPy Monitor settings file that should be used to define physical characteristics of the ioHub Display device being created.
  • Any valid ioHub Device class names: Each class name would be given as a kwarg label, and the value of the kwarg must be a dict object containing the Device Configuration Settings that need to be changed from ioHub Device type defaults.

Device class name kwarg value dictionaries must be properly formatted and contain valid configuration settings for the device in question.For details on Device Configuration Settings please see the Configuration Files and Dictionary Section of the documentation.

If experiment_code is not provided, regardless of the session_code, then the ioHub DataStore will not be enabled for the experiment session and no events will be saved by the ioHub Process. Events will still be sent to the PsychoPy Process when request ofcourse.

If experiment_code is provided, but session_code is not, then it is assumed you would like an autogenerated session code to be created for the session. The session code will be based on the current system time, using the format ‘S_%Y_%b_%d_%H%M’; i.e. if the current time is 1:23 pm on May 30th, 2012, then the session_code created will be ‘S_2012_05_30_1323’.

If the psychopy_monitor_name kwarg is not provided or is None, then a PsychoPy Monitor Configuration file will be created, or updated, using the default settings for the ioHub Display Device. If a valid psychopy_monitor_name value is provided, and no Display kwarg is provided specifying ioHub Display Configuration values to use, then the physical size of the ioHub Display, as well as the eye to Display distance, are set to match those foundin the PsychoPy Monitor Configuration associated with the name given by psychopy_monitor_name.

A couple examples will help clarify how this function can be used. The examples all assume that the following python code has already been entered into the python script:

# -*- coding: utf-8 -*-       
#
## Testing the iohub.client.launchHubServer function.
#

from iohub.client import launchHubServer
from iohub.util import FullScreenWindow

# End of common script header code for these examples.

The first example can be used to create and connect to the ioHub Process, with the ioDataStore disabled, using only default device configuration settings:

io=launchHubServer()

keyboard=io.devices.keyboard

print "Press any Key to Exit Example....."

while not keyboard.getEvents():
    io.wait(0.25)

print "A Keyboard Event was Detected; exiting Test."

io.quit()

Next, lets create a simple example that ensures the ioHub Display Device that is created uses the psychopy monitor configuration file name set by psychopy_monitor_name (assuming it is a valid psychopy monitor configuration). The ioHub DataStore is still disabled.:

io=launchHubServer(psychopy_monitor_name='testMonitor')

display=io.devices.display

print 'Display Psychopy Monitor Name: ', display.getPsychopyMonitorName()        
print 'Display Default Eye Distance: ', display.getDefaultEyeDistance()        
print 'Display Physical Dimensions: ', display.getPhysicalDimensions()        

io.quit()

Next, an example that adds the kwargs necessary to enable the ioHub DataStore using an experiment_code and session_code specified by the script.:

import time

psychopy_mon_name='testMonitor'
exp_code='gap_endo_que'
sess_code='S_{0}'.format(long(time.mktime(time.localtime())))
print 'Current Session Code will be: ', sess_code

io=launchHubServer(psychopy_monitor_name=psychopy_mon_name, experiment_code=exp_code, session_code=sess_code)

display=io.devices.display

print 'Display Psychopy Monitor Name: ', display.getPsychopyMonitorName()        
print 'Display Default Eye Distance: ', display.getDefaultEyeDistance()        
print 'Display Physical Dimensions: ', display.getPhysicalDimensions()        

from pprint import pprint

print 'Experiment Metadata: '
pprint(io.getExperimentMetaData())
print 'Session Metadata: '
pprint(io.getSessionMetaData())

io.quit()

Finally, an example that only provides the experiment_code so the ioHub DataStore is enabled using an auto generated session_code.:

psychopy_mon_name='testMonitor'
exp_code='gap_endo_que'
io=launchHubServer(psychopy_monitor_name=psychopy_mon_name, experiment_code=exp_code)

display=io.devices.display

print 'Display Psychopy Monitor Name: ', display.getPsychopyMonitorName()        
print 'Display Default Eye Distance: ', display.getDefaultEyeDistance()        
print 'Display Physical Dimensions: ', display.getPhysicalDimensions()        

from pprint import pprint

print 'Experiment Metadata: '
pprint(io.getExperimentMetaData())
print 'Session Metadata: '
pprint(io.getSessionMetaData())

io.quit()  

The source code for all the above little examples is in the examples/manual/launchHubServer folder.