Analog Input Devices

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

Bases: psychopy.iohub.devices.Device

The AnalogInputDevice device is used to interface with Analog to Digitial Signal Converters, or multi-function Data Acquision Devices that support Analog to Digital input conversion.

Currently the ioHub supports two families of devices; one by LabJack and the other by Measurement Computing. Both companies provide USB based multi-function Data Acquision Devices supporting analog to digital input with an analog input range up to +/- 10 V.

The models that have been tested by each manufacturer are:

  • LabJack:
    • U6 and U6 Pro
  • Measurement Computing:
    • USB-1616FS
    • USB-1208FS

The ioHub provides a simple common interface to all supported models, providing digital sample events for 8 single ended channels of simultaniously sampled analog inputs. Currently the input channel count is fixed at 8 channels, although you do not neeed to use all channels that are being recorded obviously.

All device interfaces have been written to use the ‘data streaming’ mode each supports. This means that a sampling rate is specified and the device samples at the fixed sampling rate specified using a clock on the DAQ device itself. ioHub specifies the sampling rate on a per channel basis, so if 500 Hz is specified as the sampling rate, all 8 channels will be sampled at 500 Hz each, for a total device sample rate of 4000 samples per second, in this example. All supported devices have been tested to ensure they support a sampling rate of up to 1000 Hz for each of the 8 channels being monitored.

Note that the U6 and USB-1616FS support 1000 Hz and are of heigh enough quality for samples to settle well within the maximum suggested 1 msec sampling interval. However the USB-1208FS, being a less expensive device, can not setting within this fast of time period, so you will see ditrortion in sample readings following large changes in the alalog input level. Therefore we suggest that the USB-1208 be used for testing purposes, or for sample rate of 100 Hz or lower.

Please see the manufacturer specific implementation notes page for details on the configuration settings ioHub supports for each device and any other considerations when using the device for AnalogInputDevice MultiChannelAnalogInput Events.

OS Support:
  • Measurment Computing: Windows XP SP3 and Windows 7
  • Labjack: Only Windows XP SP3 and Windows 7 has been tested at this time, however it shuold not be a problem to use the device interface with Linux or OS X as well.
channel_sampling_rate

The channel_sampling_rate attribute specifies the ‘per channel’ rate at which samples should be collect from the analog input device, specified in Hz. The suggested maximum sampling rate per channel is 1000 Hz. For example, if the sampling rate is set to 500 (500 Hz), then the ioHub system will be acquiring 4000 samples / second in total from the device.

clearEvents()

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)

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.

Analog Input Device Configuration Settings

Note

Each Analog Input Device implementation supports a different set of configuration options. Refer to the Analog Input Device implementation being used for a full list of configuration options for that Analog Input implementation.

The configuration settings listed here are only those that are common across all analog input implementations. All implementations of analog input devices extend the base psychopy.iohub.devices.daq.AnalogInputDevice class:

[daq.hw.daq_manufacturer.AnalogInput]:
    # name: The name you want to assign to the 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. **daq** is the default name used.
    #
    name: daq

    # 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. The device will
    #           not be loaded and no events for this device will be reported by the ioHub Server.
    enable: True

    # The model_name setting specifies which of the supported models from
    # the manufacturer will be used during the experiment.
    # If the Labjack implementation is being used, 'U6' is the only
    # currently supported model. If the Measurment Computing interface is being
    # used then the model can be either 'USB-1616FS' or 'USB-1208FS'.
    model_name: [enter_model_name]

    # Specify the 'per' channel sampling rate to set the DAQ device to
    # stream analog samples at. Each of the 8 analog inputs monitored by the
    # ioHUb is sampled at this rate, which is specified in Hz.
    channel_sampling_rate: 500

    # saveEvents: *If* the ioDataStore is enabled for the experiment, then
    #   indicate if events for this device should be saved to the
    #   appropriate data_collection 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.
    saveEvents: True

    # streamEvents: Indicate if events from this device should be made available
    #   during experiment runtime to the PsychoPy Process.
    #   True = Send events for this device to the PsychoPy Process in real-time.
    #   False = Do *not* send events for this device to the Experiment Process in real-time.
    streamEvents: 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(bool) method is made.
    #   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. False is default for this device
    auto_report_events: False

    # 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: 1024

    # Specify which event types you want to be streamed and saved to the ioDataStore.
    monitor_event_types: [MultiChannelAnalogInputEvent,]

Analog Input Event Types

The Analog Input Device currently supports one Event type, regardless of the Analag Input model being used.

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

Bases: psychopy.iohub.devices.daq.AnalogInputEvent

The AnalogInputDevice supports one event type at this time, a MultiChannelAnalogInputEvent that contains all the attributes of the base ioHub Device class as well at 8 extra attributes, labeled AI_0 - AI_7, which hold the digital representation of the analog input voltage at the time the device took the analog readings from the 8 input channels being monitored for each sample read.

Note that it is taken as the case that all devices sample the eight analog input channels being monitored at the same time for each MultiChannelAnalogInputEvent.

For the USB-1616FS device this is actually the case, as each analog input has an independent ADC chip and no multiplexing is done.

For the U6 and U6 Pro,this assumption is not strictly correct, as the device has two analog input chips, each connected to an eight way MUX, resulting in the 16 possible analog input channels supported by the device hardware. Even channels are fead to MUX A, odd channels to MUX B.

However the U6 chips are of high quality and each MUX can scan though the 8 analog input channels in under 40 usec per channel when using the suggested setting rate factor for the device. Therefore if four of the eight monitored analog inputs are even, and four are odd, the estimated time difference between channel reads for a given scan is 160 usec or less. This is low enough given the suggested maximum scanning rate of 1000 Hz per channel when the device is being used with the ioHub to be considered ‘effectively’ simultanious.

AI_0

Each MultiChannelAnalogInputEvent stores the state of all eight analog inputs being monitored by the ioHub. AI_0 represents the state of the first analog input channel, which has been converted to a digital value.

AI_1

Analog Input channel number 2 (index 1) value.

AI_2

Analog Input channel number 3 (index 2) value.

AI_3

Analog Input channel number 4 (index 3) value.

AI_4

Analog Input channel number 5 (index 4) value.

AI_5

Analog Input channel number 6 (index 5) value.

AI_6

Analog Input channel number 7 (index 6) value.

AI_7

Each MultiChannelAnalogInputEvent stores the state of all eight analog inputs being monitored by the ioHub. AI_7 represents the state of the last analog input channel being monitored, in digital form.

Analog Input Hardware Implementations

The following links provide details on the ioHub Analog Input implementation for each currently supported analog input manufacturer. It is very important to review the documentation for the system you are using the ioHub with.

Analog Input implementations are listed in alphabetical order.

Notes and Considerations

None at this time.