HID Input Element

Modified on 2018/08/03 00:51 by Administrator Categorized as 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=HID Input
| category=Input Registration
| icon=[image|Element Icon|{UP(HID-Input-Element)}HID-Input-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
|-
| HID Device        
| Selected HID device        
| {s:atDesign}        
| String        
|  
|-
| Axis Scaling        
| Defines whether the physical axis values are automatically scaled into the device's defined logical range. If false, the physical axis values are returned.        
| {s:atNormal}        
| Boolean        
|  
|-
| 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" | Device Info
|-
| Button Number        
| Number of buttons on the selected HID device        
| {s:atStatus}        
| Int32        
|  
|-
| Axis Number        
| Number of analog axis on the selected HID device        
| {s:atStatus}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Status
|-
| Raw Input        
| Returns the HID data string contains the newest raw input in HEX format. You can use this value for decoding data of non-standard HID devices        
| {s:atStatus}        
| String        
|  
|-
| Axis Values        
| Returns an integer array of current values of the device's analog axis. The length of the array is always equal to the number of analog axis on the selected device. You can open the associated analog axis monitor to see what axis corresponds to each of the array indices.        
| {s:atStatus}        
| Int32[]        
|  
|-
| 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" |   
|-
|          
|          
| {s:atNormal}        
| Boolean        
|  
|-
|          
|          
| {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>
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
'''HID Input Element''' allows receiving and decoding an input of [^http://en.wikipedia.org/wiki/Human_interface_device|HID] (Human Interface Devices). HID protocol is supported by a broad range of USB computer input devices, like keyboards, mouses, joysticks and response boxes. The element is capable of reading both device's button states and analog axis. IMPORTANT! DONT use this element to listen the primary keyboard/mouse, only secondary are allowed. For the primary keyboard/mouse use the [Button-element|Button element] instead.<br><br>
{TOC}

== Description ==

The HID Input element collects accurate timing statistics of key presses/releases and changes in analog axis, hence, it can be used for recording response times of a participant. Multiple HID Input elements can be used in EventIDE, in order to record from one or several input devices in parallel. The HID Input element monitors an input device only within a scope of it's parent event. The element collects timing statistics, e.g. a press time as the number of milliseconds since the onset of the parent event.


== Selecting the monitored button ==

The HID Input element can monitor either one specific button, or all buttons 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. Given flexibility of the HID Input element, for the 2ADC tasks you can use different design patterns:

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

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 the button element.

== Selecting the triggering modes for buttons ==

When monitoring buttons, the HID Input element is not limited to registering just button presses. There are 5 'triggering' modes for buttons, in which the HID Input 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 ignores all successive presses. Other modes are self-explanatory, save for the holding down mode, which detects continuously presses, common in the game-like activities.

== HID Button Names ==

The HID Input element uses the button naming defined by an HID device. For example, the keyboard number buttons in the horizontal row are denoted as 'D1','D2'..'D0'. Other HID devices name their buttons as: 'Button 1', 'Button 2' and so on. Be aware that you need to maintain capital letter in the button names, when operating with them in C# code.
You can easily find out the actual button name, using the design-time press detector on the HID Input 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(Button-Element)}PressDetector-sm.png|{UP(Button-Element)}PressDetector.png]
|}


== Triggered Snippet ==

The HID Input 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=="NumPad4")
Positon.X=PositionX-1;
if (TriggeringButton=="NumPad6")
Positon.X=PositionX+1;
@@

== Monitoring the analog axis ==

The HID element allows to monitor the analog axis of HID devices via the '''Axis Values''' property. For example, a position of the joystick stick is described by the two integers values, along the X and Y axis. You can get each axis position by index, e.g. AxisValues<nowiki>[0]</nowiki> and AxisValues<nowiki>[1]</nowiki>. To find out what axis are available on the selected HID device and their indices, expand the '''Axis Values''' property in the properties Panel:

{|
| [imageleft|Checking the analog axis of the HID device |{UP(HID-Input-Element)}HIDElementAxis.png|{UP(HID-Input-Element)}HIDElementAxis.png]
|}

If you move the analog control into extreme positions, you can also find the minimal and maximal values on the corresponding axis.


== Practical Use ==

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

# Add the button element to the 'stop' event
# Browse the button element properties in the property panel
# Select the '''Input Device''', for example, a keyboard
# 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 button element to the 'measurement' event, normally one where the stimulus is presented
# Browse the button element properties in the Properties panel
# Select the '''Input Device''', for example, a keyboard
# 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 button element properties in the Properties panel
# Select the '''Input Device''', for example, a keyboard
# 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);
@@

=== Moving a visual marker by HID joystick ===

# Add the HID Input element to the event, in what the marker is presented
# Browse the HID Input element properties in the Properties panel
# Select your joystick via the '''Input Device''' property
# Expand '''Analog Axis''' property and move joystick in the extreme positions in each direction
# Find the axis indices that corresponds to the stick control. Write down the minimal and maximal values on these axis.
# Create a proxy variable linked to the '''Analog Axis''' property
# Add the [Renderer element] with any marker shape and create a proxy variable linked to Renderer's '''Position''' property
# Add the following code to the Control Loop snippet of the parent event. The code will update the marker position based on the current joystick axis values.

@@ csharp

/// Define the actual limits of each axis
/// empirically measured in the '''Axis Values''' editor
double MinX=0;
double MaxX=255;
double MinY=0;
double MaxY=255;

/// Updating the position of the visual marker in the normalized screen coordinates
Position.CX=(AxisValues[1]-MinX)/(MaxX-MinX)-0.5;
Position.CY=(AxisValues[0]-MinY)/(MaxY-MinY)-0.5;
@@

== Notes ==

* If the monitored button is already pressed on the event onset, the element is not triggered by press immediately, it happens only on the next press. However, you can use the '''Is Down''' property, which identifies a state of the monitored button at any moment.
* 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 state flag, independently of the selected triggering mode
Meta Keywords:
Meta Description:
Change Comment:
EventIDE Wiki

Navigation¶

HID Input Element
