Contributions:ResponseTimeBox

Synopsis

A logger that stores event information (button, sound, light, TTL) from the Response Time Box into BCI2000 states. The ResponseTime Box has 4 buttons, an audio port, a light port, a TTL in, TTL out, and a USB port. Power and serial communication is supplied through the USB port. This logger deals exclusively with version v5/6. More information on this version, along with the schematics and TTL pinouts, can be found in the Response Time Box Manual

Location

http://www.bci2000.org/svn/trunk/src/contrib/Extensions/ResponseBox

Versioning

Authors

Ryan Gladwell (gladwell@neurotechcenter.org)

Will Engelhardt (engelhardt@neurotechcenter.org)

Version History

2022/07/25: Initial public release

Source Code Revisions

Initial development: 6860
Known to compile under: 6860
Broken since: --

Functional Description

Oftentimes, the reaction time of a subject is measured by calculating the interval between a stimulus and the subject's reaction. However, difficulty can arise when devices with high latency are used to collect the exact time of the subject's reaction, or when the device clock is mismatched with the computer clock. The RTBox is designed to consolidate the entire experiment by directly measuring the stimulus onset (audio or light), the button press(es), and the time interval simultaneously with essentially no latency, thereby circumnavigating the aforementioned difficulties.

Video Overview

Event names have been updated to include "RT" at the front to aid in identification and avoid confusion

Integration into BCI2000

Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and opening Configure.sh.cmd. In the CMake GUI, enable EXTENSIONS_RESPONSETIMEBOX and then click generate. Then recompile BCI2000. Once the extension is built into the source module, enable it by appending --LogResponseTimeBox=1 along the source module line within the batch file.

Configuring ResponseTimeBoxLogger

The ResponseTimeBoxLogger is configured by the LogResponseTimeBox, RTButtonPress, RTLight, RTSound, RTSensitivity, and RTCOMPort parameters. If the LogResponseTimeBox parameter box is left unchecked, the RTBox will not be read.

The logger is written to automatically find and connect to the RTBox comport. However, if the detection process is lengthy for some reason, or if the auto-detection fails, it will be necessary for the user to enter the hardware address of the RTBox into the RTCOMPort parameter manually. Make sure the RTBox is not being used by another program before attempting to connect.

To find the hardware address for the RTBox, press WIN + R and enter devmgmt.msc. In Device Manager, expand the section labeled Ports (Com & LPT). If this section does not exist, the serial cable might not be properly connected. Find the one labeled with "USB Serial Port." The label (COM4 in this example) is the device name, and this is what the user should enter into the RTCOMPort parameter.

Figure 1. Device manager window showing RTBox USB comport

Parameters

The ResponseTimeBox is configured in the Source tab. The configurable parameters are:

LogResponseTimeBox - This parameter is a boolean that enables or disables all response time box functions.
RTButtonPress - This parameter is a boolean that enables or disables all button press or release events.
RTLight - This parameter is a boolean that enables or disables any light detection by a photodiode in the light port.
RTSound - This parameter is a boolean that enables or disables any sound detection by the sound port
RTSensitivity - This parameter is an enumeration that sets the sensitivity of the light and sound ports. The higher the sensitivity, the less light and sound needed to trigger an event. Background light in bright rooms can cause the photodiode to stay triggered when the sensitivity is too high, so it is better to lower the sensitivity in such a setting. However, when sensitivity is lower, sound triggers need to be higher, so if one intends to use both light and sound, they ought to balance the sensitivity. This is why "More" sensitive is the default setting, because it allows for both sound detection and light detection in a bright room.
RTCOMPort - This parameter sets the comport connection that the RTBox is connected to. Entering "auto" will cause BCI2000 to attempt to automatically find and connect to the RTBox comport. See above if automatic connection fails.

State Variables

RTButton1

This state has a value of 1 when button 1 is pressed, or when TTL pin 1 is stimulated, and 0 when released.

RTButton2

This state has a value of 1 when button 2 is pressed, or when TTL pin 2 is stimulated, and 0 when released.

RTButton3

This state has a value of 1 when button 3 is pressed, or when TTL pin 3 is stimulated, and 0 when released.

RTButton4

This state has a value of 1 when button 4 is pressed, or when TTL pin 4 is stimulated, and 0 when released.

RTLightEvent

This state will spike to value 1 when the photodiode detects light, or when TTL pin 6 is stimulated, then return to 0.

RTSoundEvent

This state will spike to value 1 when the sound port detects sound, or when TTL pin 5 (low active) or 9 (high active) are stimulated, then return to 0.

RTAuxEvent

This state will spike to value 1 when TTL pin 8 is stimulated, then return to 0.

Device Time

The device time is absolute (meaning the value reflects the total time the RTBox has been powered on) and is delivered in 6-bytes continuously or with every event. To find the millisecond value of the device time, it is necessary to compare it to the SourceTime state. Do this by first finding the value of the event time for the event of interest. It is 6-byte, so it occupies 48 bits and is split up into two states, RTEventTime1 and RTEventTime2. Find the value in RTContTime1 and RTContTime2 that most closely matches the event time. Take the index of this value and find the SourceTime at this index. The process is outlined below.

Event Time

RTEventTime1

This state will spike to the first 3 bytes of the current 6-byte device time whenever an event occurs (buttons, light, sound, or aux).

RTEventTime2

This state will spike to the last 3 bytes of the current 6-byte device time whenever an event occurs (buttons, light, sound, or aux).

Continuous Time

RTConTime1

This state updates continuously along with the first 3 bytes of the 6-byte device time.

RTConTime2

This state updates continuously along with the last 3 bytes of the 6-byte device time.

TTL

The TTL can be observed if the ParallelPortFilter extension is included. Information on ParallelPortFiler can be found on the ParallelPortFilter BCI2000 wiki page. Pin outs for the TTL in DA-15 and TTL out DB-25 and specific instructions for writing to/reading from the box can be found below.

RTBox TTL In

The diagram below shows the pin out for the TTL in port for the RTBox. To use this port with the ParallelPortFilter extension, one will need to buy a custom DA-15 to DB-25 male/male cable, or make their own to make sure the configurable parallel port pins line up with the TTL in pins. It should be noted that the TTL pins by default rest at 1 and go to 0 when stimulated (low active). Therefore, it is recommended to invert the stimulation condition to halt stimulating those pins when one desires their activation. For instance, if one wants the states to be value 1 when StimulusCode==1, they ought to set the pin condition (in the ParallelPort tab) to !(StimulusCode==1). To write to the RTBox TTL In pins, do not append --LogParallelPort=LPT1 in the batch file.

RTBox TTL Out

The diagram below shows the pin out for the TTL out port for the RTBox. To use this port with the ParallelPortFilter extension, one will need to buy a custom DB-25 to DB-25 male/male cable, or make their own to make sure the readable parallel port pins line up with the TTL out pins. If one is having trouble reliably detecting all events, it is recommended to attempt increasing the BCI2000 sampling rate. To use ParallelPortFilter in read mode, make sure to append --LogParallelPort=LPT1 (or whichever ParallelPort is currently in use. The port can be found by looking under Ports (Com & LPT) in device manager) to the source module line in the batch file.

Parallel Port Pin Out

The figure below shows the parallel port pin out. The ParallelPortFilter extension follows this paradigm, so using it means that only 8 pins are accessible for reading and writing at a time. With this extension, pins D0-D7 can be written to or read from. Settings for these pins will need to be adjusted in the ParallelPort tab in BCI2000.

Figure 2. Procedure for interpreting ResponseTime Box Time

Latency

The device has a fairly low latency, measured at 9.033 ± 6.3430 ms compared to the g.USBamp, a device that is generally accepted to have ~0 ms latency. To determine the device latency, trials were run where photodiodes were connected to both the ResponseTime Box and the g.USBamp. For the trials, the sampling rate was set to 4800 Hz and the block size was 50. The difference in time between the StimulusCode, which determined when the flashes would occur, and the ResponseTime box was determined to evaluate the video latency. The difference in time between the g.USB amp and the ResponseTime box was determined to evaluate the acquisition latency. Histograms showing both latencies are included below.

Figure 3. ResponseTime Box latency determined using StimulusCode onset
Figure 4. ResponseTime Box latency determined using g.USB detection