Cedrus XID Element

Modified on 2018/08/03 00:48 by Administrator Categorized as Base Elements, Elements, Input Registration
<div style="margin-right: 10px; margin-left: 16px; margin-bottom:10px; float: right; width: 500px; overflow: hidden; height: auto; padding: 0px; background: #fafafa; background: -webkit-gradient(linear, left top, left bottom, from(#fbfbfb), to(#fafafa));background: -moz-linear-gradient(top, #fbfbfb, #fafafa);border: 1px dashed #ddd;box-shadow: 0 0 0 3px #fff, 0 0 0 5px #ddd, 0 0 0 10px #fff, 0 0 2px 10px #eee;">
== Summary ==
{s:Element Info Panel
| title=Cedrus XID
| category=Input Registration
| icon=[image|Element Icon|{UP(Cedrus-XID-Element)}Cedrus-XID-Element-Icon.png]
| author= OkazoLab
| addin= Base Layer
| scope= Parent event
| usage= Snippets
| ownsnippets= None
}
== Properties ==
{|
|-
! Name
! Description                              
! Constraints
! Type
! On<br/>runtime<br/>change
|-
| colspan="5" bgcolor="#AADDDDD" | Settings
|-
| Cedrus Port        
| Defines the selected serial port by its name in the system. The name can be selected from the dropdown list, which queries the available serial ports.        
| {s:atDesign}        
| String        
|  
|-
| Baud Rate        
| Defines the serial baud rate        
| {s:atDesign}        
| Int32        
|  
|-
| Triggering Mode        
| Defines the triggering mode for button. The 'First Press Only' mode is recommended for response time measurements        
| {s:atDesign}        
| enButt..        
|  
|-
| Monitored Button        
| Defines a button monitored by the element. If 'Any Button' selected, the element monitors all buttons on the selected input device. In this case, a name of the pressed button is indicated by the Triggering Button property at runtime.        
| {s:atDesign}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" |   
|-
|          
|          
| {s:atNormal}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Status
|-
| Triggering Time        
| Returns a local event time (in ms) of the last button triggering. The value can be used an accurate measure of the response time        
| {s:atStatus}        
| clTime        
|  
|-
| Is Triggered        
| Indicates whether a button has been triggered at least once, since the onset of the parent event. This property can be naturally used to gate switching between events.        
| {s:atNormal}        
| Boolean        
|  
|-
| Triggered Button        
| Returns a system name of the triggered button. The keyboard symbol buttons are always shows by the capital letters, whereas the mouse and gamepad buttons are shown by names like 'Button 1'        
| {s:atStatus}        
| String        
|  
|-
| Is Down        
| Indicates whether the monitored button is currently in the down state        
| {s:atNormal}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Control
|-
| Is Enabled        
| If set to false the element is completely omitted when the experiment is run        
| {s:atDesign}        
| Boolean        
|  
|-
| Title        
| Title of the element        
| {s:atDesign}        
| String        
|  
|-            
|}
== ==
</div>
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
'''Cedrus XID Element''' detects button and line states on the [http://cedrus.com/|Cedrus input devices] that support the [http://cedrus.com/xid|XID (eXperimental Interface Device) protocol]. The supported XID devices include the [http://cedrus.com/rb_series/|RB Series] and [http://cedrus.com/lumina/|Lumina] response pads, [http://cedrus.com/stimtracker/|StimTracker marker] and [http://cedrus.com/sv1/|SV-1 voice key].<br><br>
{TOC}

== Description ==

The Cedrus XID element monitors a state of input device and collects accurate timing statistics of button presses, button releases and changes in the device's auxiliary input lines. The element uses an internal timer of Cedrus hardware (when available), which allows to record more accurate response times than when a standard keyboard is used. Multiple Cedrus XID element elements can be used to record from one or several input devices in parallel. The Cedrus XID element monitors button presses only within a scope of its parent event and return timing statistics relatively the onset of the parent event.


== Supported Cedrus devices (with links) ==

{|
| [imageleft|RB Series response pads|http://cedrus.com/wp-content/uploads/2012/11/Screen-Shot-2012-09-28-at-10.17.36-AM-290x154.png|http://cedrus.com/rb-series/]
|}


{|
| [imageleft|MRI compatible Lumina response unit|http://cedrus.com/wp-content/themes/cedrus/images/lumina_heading.png|http://cedrus.com/lumina/]
|}

{|
| [imageleft|StimTracker marker unit|http://cedrus.com/wp-content/uploads/2012/11/Screen-Shot-2012-09-28-at-11.27.39-AM-290x147.png|http://cedrus.com/stimtracker/]
|}

{|
| [imageleft|SV-1 voice key unit|http://cedrus.com/wp-content/uploads/2012/11/Screen-Shot-2012-09-28-at-10.18.40-AM1-235x160.png|http://cedrus.com/sv1/]
|}

== Enabling the XID protocol on Cedrus devices ==

For maximum compatibility with various application programs, the Cedrus devices support several communication protocols. The native communication protocol is called 'XID' (or XID mode) and this protocol is one that is supported by the Cedrus XID element. To use the element, you have to check whether the XID mode is enabled on your device.
* for RB Series response pads check this [http://cedrus.com/support/rb_series/tn1044_dip_switches.htm|Cedrus support page].
* for Lumina unit check this [http://cedrus.com/lumina/controller_features.htm|Cedrus support page].

== Selection of the monitored button or line ==

Cedrus XID element can monitor either one specific button or line, or all buttons and lines in the same time (when '''Any''' Button is selected in the '''Monitored Button''' property). In many experimental tasks, e.g.[http://en.wikipedia.org/wiki/Two-alternative_forced_choice|2AFC], there are two response buttons for a participant. Due to flexibility of the Cedrus XID element, for the 2ADC tasks you can use different design patterns:

# Create two Cedrus XID elements, each monitoring one of the predefined response buttons or lines
# Create one Cedrus XID element monitoring '''Any''' button and write code that checks what button is pressed. The name of the pressed button is returned by the '''Triggered Button''' property

Both patterns are eligible. The first pattern allows to automatically ignore presses of irrelevant buttons. The second pattern is more convenient for collecting a reaction time in trial, because you can get from a single [proxy variables|proxy variable] link to the '''Triggering Time''' property of Cedrus XID element.

== Triggering modes ==

The Cedrus XID element can detect any button state, not only presses. There are 5 'triggering' modes, in which the element can operate. You need to select the triggering mode in advance, according to your requirements:

* First Press Only
* First Release Only
* Multiple Presses
* Multiple Releases
* Holding Down

Depending on the working mode, the element becomes 'triggered' when a specific input pattern is detected. The '''First Press Only''' mode is the default choice for registering the fastest reaction time, because in this mode the element picks up the first button press ignoring the rest. Other modes are self-explanatory, save for the holding down mode, which detects continuous presses, commonly used in the game-like activities.

== Button Names ==

The Cedrus XID element uses simple button naming, based on the button index: "Button 1", "Button 2" and so on. The input lines are named similarly: "Line 1","Line 2" and so on. Be aware that you need to maintain capital letter in the names, while operating on them in C# code.
You can easily find out the actual button name, using the design-time press detector on the Cedrus XID element. Open an editor for the '''Monitored Button''' property and move the mouse cursor over the picture with a web. Then, press the desired button and check its name in the top row:

{|
| [imageleft|Using the press detector <br/> to set the monitored button <br/> or find out the button name |{UP(Cedrus-XID-Element)}PressDetector-sm.png|{UP(Cedrus-XID-Element)}PressDetector.png]
|}

== Triggered Snippet ==

The button element can invoke custom user code each time, when it becomes triggered (e.g. on a button press). To engage the triggering snippet, open it via the snippet panel and write your code there. Note that the triggered snippet is invoked only once, on the first press, when the '''First Press Only''' triggering mode is selected. The triggered snippet can be used for checking a name of the pressed button:

@@ csharp
if (TriggeringButton=="Button 4")
Positon.X=PositionX-1;
if (TriggeringButton=="Line 2")
Positon.X=PositionX+1;
@@

== Practical Use ==

=== Implementing the "Press any button to continue" design pattern ===

# Add the Cedrus XID element to the 'stop' event
# Browse the Cedrus XID element properties in the property panel
# Define a name of the '''Cedrus Port''' as it's set in your system, for example, 'COM1'
# Select the baud rate according to the settings of your Cedrus device.
# Leave '''Triggering Mode''' and '''Monitored Button''' with the default values, 'First Press Only' and 'Any Button'
# Create a proxy variable linked to the '''Is Triggered''' property of the element
# Go back to the parent event and add the conditional flow route leading to a successive event.
# Write an expression for the conditional route as (IsTriggered==true), where the first part is a name of the proxy variable linked to the button element

=== Implementing the reaction time measurement with a single button ===

# Add the Cedrus XID element to the 'measurement' event, normally one where the stimulus is presented
# Browse the Cedrus XID element properties in the property panel
# Define a name of the '''Cedrus Port''' as it's set in your system, for example, 'COM1'
# Select the baud rate according to the settings of your Cedrus device
# Leave '''Triggering Mode''' with the default value, 'First Press Only'
# Select '''Monitored Button'''
# Create a proxy variable linked to the '''Is Triggered''' property of the element
# Create a proxy variable linked to the '''Triggering Time''' property
# Go back to the parent event and add the conditional flow route leading to a successive event, if you want to terminate the event on a button press.
# Write an expression for the conditional route as (IsTriggered==true), where the first part is a name of the proxy variable linked to the '''Is Triggered''' property
# After offset of the 'measurement' event, pick up the value of the '''Triggering Time''' proxy variable. For example, you can save it to the [Report|data report] via the [Reporter-Element|Reporter Element]

=== Recording times of multiple button presses within a single event ===

# Add the button element to the 'measurement' event, normally one where the stimulus is presented
# Browse the Cedrus XID element properties in the property panel
# Define a name of the '''Cedrus Port''' as it's set in your system, for example, 'COM1'
# Select the baud rate according to the settings of your Cedrus device
# Set '''Triggering Mode''' to 'Multiple presses'
# Select '''Monitored Button'''
# Create a proxy variable linked to the '''Triggering Time''' property
# Open the triggered snippet of the button element via the snippet panel
# Add the following code to the snippet. The code adds a time of the current button press to a dedicated array list.

@@ csharp
/// PressTime is a list declared in the header, e.g.
/// ArrayList PressTimes=new ArrayList();

PressTimes.Add(TriggeringTime);
@@

== Notes ==

* If the monitored button is already pressed on the event onset, the element is not triggered by press immediately, it will happen only on the next press. Also, you can not rely on the '''Is Down''' property, which identifies a state of the monitored button only after a message from a Cedrus device is received within the parent event. The same logic is applied to monitored input lines.
* The '''Triggering Time''', '''Is Triggered''' and '''Triggered Button''' properties are nullified on the onset of the parent event. However, you can read these values in other events after the offset of the parent event
* '''Is Down''' property can be used a button or line state flag, independently of the selected triggering mode
Meta Keywords:
Meta Description:
Change Comment:
EventIDE Wiki

Navigation¶

Cedrus XID Element
