VisuomotorJoystickTask

Synopsis

USBHIDJoystickTask is a BCI2000 application module that implements a center-out visuomotor reaching task controlled with a USB HID joystick. The task is designed to compare movements made under a normal joystick-to-cursor mapping with movements made under an inverted mapping.

During each experimental trial, the participant moves a cursor to the center of the display, holds it there, waits through a warning period, and then moves to a peripheral target. In the automatic condition (labeled Normal to the participant), joystick and cursor movements are congruent. In the controlled condition (labeled Reversed to the participant), joystick-to-cursor movement is inverted after the target appears. The numerical TaskCondition encodings remain 0 and 1, respectively.

The task also includes an optional participant introduction and practice sequence. Before the experiment begins, participants may receive task instructions, explore both normal and reversed cursor mappings, and complete automatic and controlled practice trials. Tutorial and practice periods are recorded in the BCI2000 data stream but remain separate from experimental trial numbering and experimental performance summaries.

The task is based on the visuomotor paradigm described by Neumann et al. (2018), which was developed to compare automatic and controlled movements and investigate their relationship to basal ganglia function and subthalamic deep brain stimulation in Parkinson's disease. The BCI2000 implementation adapts the original paradigm for USB joystick control and synchronized BCI2000 state recording.

Video Overview

The following video demonstrates the Visuomotor Joystick Task running in BCI2000, including the participant display and joystick-controlled task behavior:

Load video

YouTube

YouTube might collect personal data. Privacy Policy

Continue Dismiss

This video displays version 1 of the task, and as such does not include the pre-experiment participant tutorial and practice sequence.

Location

In the inspected development checkout, the USB HID Visuomotor Joystick Task is located at:

src/custom/usb_hid_joystick_task/

The main application implementation is contained in:

USBHIDJoystickTask.cpp

with the corresponding header and build configuration in:

• USBHIDJoystickTask.h
• CMakeLists.txt

The CMake target is usb_hid_joystick_task_custom (configured with NOBUNDLE), and the target explicitly requires C++17. This checkout is tracked in Git; the former src/private/Application/VisuomotorJoystickTask SVN location does not describe the inspected source tree.

The paths and target above describe the checkout inspected for this documentation update; another deployed BCI2000 tree may arrange custom modules differently.

Versioning

Author

Alexander Speer

Friedman Lab, Department of Neurosurgery

Washington University in St. Louis

Developed in the Friedman Lab.

Contact: speer@wustl.edu

Version History

The task was developed as a USB HID joystick implementation of the automatic/controlled visuomotor reaching paradigm described by Neumann et al. (2018).

The current implementation includes:

• Automatic and controlled visuomotor conditions.
• Ordered and pseudorandom experimental blocks.
• Configurable trial counts and trial timing.
• An optional participant tutorial and practice sequence.
• Automatic and controlled practice trials.
• Free-movement demonstrations of normal and reversed cursor control.
• Joystick-button and experimenter-controlled tutorial progression.
• USB joystick input through BCI2000's input logging system.
• Selection of the participant display on multi-monitor Windows systems.
• BCI2000 state logging of task timing, cursor position, target position, condition, block structure, tutorial status, practice trials, and trial events.
• A separate diagnostic window with visible performance metrics, tutorial controls, manual trial reset, researcher skip controls, and pause/resume.
• Trial-level reaction time, movement time, and total time measurements.
• Configurable cursor and target diameters, with target size affecting acquisition tolerance.
• Dedicated one-processing-block states for researcher skip events and a persistent pause state.
• Participant-facing Normal/Reversed terminology and condition cues, without changing automatic/controlled state encodings.
• Separation of tutorial/practice data from experimental trial numbering and run-summary metrics.
• Behavioral recording through synchronized BCI2000 states; this version does not create a separate results CSV.

The inspected development checkout contains the task under src/custom/usb_hid_joystick_task and has Git history through 2026-10-12 (commit 83404dd).

Source Code Revisions

• Initial development: 8/26/26
• Tested under (earlier revision): BCI2000 framework 3.6.9528.4, Release x64, MSVC 19.35
• Known to compile under: Visual Studio 2022 / MSVC 19.35 for a prior version of the current source
• Earlier documented source revision: 9/1/26
• New version, 10/12/26: Latest inspected task commit 83404dd. Added researcher pause/resume and skip controls with corresponding states, configurable cursor/target diameters, participant-facing Normal/Reversed labels and condition cues, and updated diagnostic metrics display; removed secondary CSV output and ResultsFile. Source moved to the inspected custom-module location and CMake target described above.
• Current inspected source revision: 10/12/26 (Git commit 83404dd)
• Broken since: No known breaking revision

The earlier framework and compiler information above does not establish a successful build or runtime test of the 10/12/26 source revision; the present update is based on source comparison.

Functional Description

Scientific Basis

This task is a BCI2000 adaptation of the visuomotor task described by Neumann et al. (2018).

In the original experiment, participants controlled a cursor using a pen and digitizing tablet. Targets appeared around a central fixation point. In the automatic condition, movement of the pen and cursor was congruent. In the controlled condition, the pen-to-cursor mapping was inverted. Automatic targets were shown in green and controlled targets in red.

Trials in the original experiment began at a central fixation cross. Participants remained at the center for 3 seconds, after which a yellow warning cue appeared for 500 ms. The target appeared 500 ms after the warning cue. The original experiment used eight possible target positions arranged around the center and included both ordered condition blocks and a pseudorandom block.

The present BCI2000 implementation preserves the central features of this paradigm, including the automatic and inverted controlled mappings, green and red targets, 3-second default experimental center hold, 500-ms warning period, 500-ms pre-target delay, and ordered and mixed experimental structures. The current participant-facing descriptions call these mappings Normal and Reversed, respectively; the legacy condition identifiers are retained in code and parameters.

There are several implementation differences. The BCI2000 version uses a USB HID joystick (Any joystick should work, provided that Windows recognizes it as a game controller.) rather than a digitizing tablet, allows the timing and number of trials to be configured, and generates experimental targets over a continuous range of angles rather than restricting targets to eight positions. It also provides an optional tutorial and practice sequence and records task variables directly as synchronized BCI2000 states.

See References for the original study.

Experiment Structure

Four experiment modes are available:

Value	Mode	Description
1	Automatic Only	Runs one block containing only automatic trials.
2	Controlled Only	Runs one block containing only controlled trials.
3	Ordered	Runs one automatic block and one controlled block. OrderedStartCondition determines which condition occurs first.
4	Ordered + Pseudorandom	Runs an ordered automatic block, an ordered controlled block, and then a mixed pseudorandom block containing both conditions.

In the mixed block, the application shuffles the configured numbers of automatic and controlled trials. The randomization attempts to avoid both strict alternation and excessively long runs of a single condition.

When the tutorial is enabled, its content depends on ExperimentMode:

Experiment mode	Tutorial content
Automatic Only	General introduction, normal free movement, automatic instructions, automatic practice, completion
Controlled Only	General introduction, normal free movement, controlled instructions, controlled free movement, controlled practice, completion
Ordered	Automatic tutorial and practice followed by controlled tutorial and practice
Ordered + Pseudorandom	Automatic tutorial and practice followed by controlled tutorial and practice

When both conditions are present, the tutorial always presents automatic training before controlled training. OrderedStartCondition affects the experimental block order but does not change the tutorial order. The participant sees Normal/Reversed wording for these conditions, while the experiment parameters and state names continue to use Automatic/Controlled identifiers.

Tutorial and Practice Sequence

When EnableIntroduction=1, the tutorial begins at the start of each run before the first experimental block.

The tutorial consists of the following stages:

TutorialPhase	Stage	Description
0	None	Tutorial inactive; normal experiment operation
1	Introduction	General explanation of the task and upcoming conditions
2	Normal free movement	Participant explores normal direct joystick-to-cursor movement
3	Normal instructions	Explanation of the automatic (Normal) condition and green targets
4	Normal practice	Automatic practice trials using the normal mapping
5	Reversed instructions	Explanation of the controlled (Reversed) condition and red targets
6	Reversed free movement	Participant explores continuous reversed joystick-to-cursor control
7	Reversed practice	Controlled practice trials using the inverted mapping
8	Complete	Practice-complete summary before the experiment begins

When EnableIntroduction=0, the tutorial is skipped and the task begins with the original experimental block-announcement sequence.

Tutorial Continuation

Tutorial screens that require participant acknowledgement may be advanced using either:

• Joystick button 1, or
• The experimenter's CONTINUE button in the diagnostic window.

Joystick continuation uses rising-edge detection. Pressing the button advances one eligible tutorial screen, while holding the button does not repeatedly advance the tutorial. The button must be released and pressed again to produce another continuation event.

Button presses are ignored during active practice trials and during tutorial transitions that require the participant to return the joystick or cursor to center.

During the experimental portion of the run, joystick button presses do not control trial progression. The researcher CONTINUE control displays CONTINUE UNAVAILABLE when continuation is not permitted. The researcher can also use context-specific skip controls to bypass eligible tutorial stages; these actions are documented under Researcher Skip Controls. The task can be paused during tutorial stages.

Normal Free Movement

During the normal free-movement stage, the participant may freely move the cursor using the direct absolute joystick mapping.

There is no timer or trial progression during this stage. It continues until the participant presses the joystick button or the experimenter selects CONTINUE.

Automatic Practice

Automatic practice uses the same direct mapping and the same basic trial phases as experimental automatic trials:

1. Waiting for center
2. Holding center
3. Warning
4. Pre-target delay
5. Target visible
6. Feedback

Practice trials differ from experimental trials in several ways:

• Center hold is determined by PracticeCenterHoldTime rather than CenterHoldSeconds.
• Practice targets follow a deterministic sequence.
• TaskBlock and TaskTrial remain 0.
• PracticeTrial identifies the active practice trial.
• Practice activity is recorded in BCI2000 states; this application writes no separate trial-level CSV file.
• Practice results are excluded from experimental completion counts and timing summaries.
• Practice reset attempts do not increment experimental reset metrics.

After the final automatic practice trial, the participant must return the cursor to the center before the tutorial advances.

Controlled Free Movement

The controlled free-movement stage allows the participant to explore reversed cursor control without a target.

The participant is first asked to return the cursor to center. Once centered, the application records the current joystick and cursor positions as anchors and enables the same relative inverted mapping used during target-directed controlled movement.

When the participant requests continuation, the task requires the joystick to return to the anchored position before advancing. This prevents an abrupt cursor jump when the mapping changes.

Controlled Practice

Controlled practice uses the same basic controlled-trial behavior as the experiment:

• Direct absolute mapping is used during centering.
• Joystick and cursor anchors are recorded when the target appears.
• Target-directed cursor movement uses the relative inverted mapping.
• The participant returns the joystick toward its anchor after target acquisition.

Controlled practice uses PracticeCenterHoldTime and deterministic practice targets and remains separate from experimental numbering and performance summaries. Its states are recorded in the BCI2000 data stream; no secondary CSV is written.

After the final controlled practice trial, the participant must complete the return-to-center and return-to-anchor transition before the completion screen appears.

Tutorial Completion

The completion screen summarizes the condition mappings:

• Normal (automatic): cursor movement follows joystick movement.
• Reversed (controlled): cursor movement is opposite joystick movement.
• Green targets identify automatic trials.
• Red targets identify controlled trials.

After continuation, the tutorial ends, Introduction returns to 0, the originally generated first experimental target is restored, and the experiment begins with the normal 1.5-second block announcement.

Experimental Trial Sequence

Each experimental block begins with a 1.5-second announcement indicating whether the upcoming block is Normal, Reversed, or Mixed. These visible labels correspond to the existing automatic, controlled, and mixed block types; their numerical encodings are unchanged.

A trial then proceeds as follows:

1. The participant moves the cursor into the center region.
2. Once centered, the participant must remain there for CenterHoldSeconds.
3. A yellow warning marker appears for WarningSeconds.
4. A pre-target interval lasting PreTargetDelaySeconds follows.
5. The target appears.
6. The participant moves the cursor into the target.
7. Target acquisition records the trial timing measurements and begins the feedback interval.
8. After FeedbackSeconds, the task advances to the next trial or block.

If the participant leaves the center during the center-hold, warning, or pre-target interval, the task returns to the waiting-for-center phase and the preparation sequence begins again.

A new target is generated when advancing to a new experimental trial. Manually resetting a trial does not generate a new target. Skipping an experimental trial instead advances to the next trial and generates a new target (unless the experiment has finished). A skip-block action advances past the remaining trials in the block.

Automatic Condition (Normal)

During an automatic trial, cursor position follows the joystick using a direct mapping. Moving the joystick in one direction moves the cursor in the corresponding direction.

Automatic targets are displayed in green.

Controlled Condition (Reversed)

During a controlled trial, the normal direct mapping is initially used while the participant returns to and holds the center.

When the target appears, the current joystick position and cursor position are recorded as anchors. Cursor movement then becomes relative to those anchors and inverted. Moving the joystick away from its target-onset position causes the cursor to move in the opposite direction.

Conceptually:

cursor position = anchor cursor position - joystick displacement

The cursor is constrained to the participant display.

After completion of a controlled trial, the inverted mapping remains active until the joystick has returned close to the joystick position recorded at target onset. This prevents an abrupt cursor jump when returning from the controlled mapping to the normal mapping.

Controlled targets are displayed in red.

Joystick Input

Joystick input is provided through BCI2000's input logging system.

Joystick position states are expected to range from 0 through 32767. The application converts these values into internal task coordinates ranging from 0 through 1023.

The application reads:

• JoystickXpos
• JoystickYpos
• JoystickButtons1

JoystickButtons1 is used during the tutorial as a participant continuation button. A rising button press may advance eligible tutorial screens. It does not advance active practice trials and has no effect on experimental trial progression.

Joystick recording is normally enabled using the LogJoystick option. See LogJoystick for configuration details.

Experimental Target Generation

A new target angle is generated for each new experimental trial.

The random target generator produces an integer between 0 and 3599. TargetAngle therefore represents tenths of a degree:

angle in degrees = TargetAngle / 10

This produces target angles from 0.0 through 359.9 degrees.

Targets are positioned at a fixed distance from the center using the generated angle.

Unlike the original Neumann et al. experiment, which used eight circularly arranged target locations, the BCI2000 implementation allows experimental targets to appear over a continuous range of angles.

Practice Target Generation

Practice trials use a deterministic six-angle sequence rather than the experimental random target generator:

Sequence value	Target angle
150	15 degrees
450	45 degrees
750	75 degrees
1050	105 degrees
1350	135 degrees
1650	165 degrees

Automatic practice begins with the 15-degree target and follows the sequence in order.

Controlled practice begins with an offset of two positions, producing:

75°, 105°, 135°, 165°, 15°, 45°

If more than six practice trials are configured, the sequence repeats.

These targets are positioned in the lower half of the participant display to reduce overlap with tutorial text.

The random target generated for the first experimental trial is saved before the tutorial begins and restored after practice finishes.

Trial Phases

The current trial phase is recorded in TaskPhase.

Value	Phase	Description
0	Block announcement / no active practice trial	During the experiment, the upcoming block type is being displayed. During non-trial tutorial screens, TaskPhase is also 0.
1	Waiting for center	The task is waiting for the cursor to enter the center region.
2	Holding center	The participant is completing the required center hold.
3	Warning	The yellow warning cue is visible.
4	Pre-target delay	The warning has ended and the task is waiting for target onset.
5	Target visible	The peripheral target is visible and movement may occur.
6	Feedback	The target has been acquired and the task is waiting before advancing.
7	Finished	All configured experimental trials have been completed.

During active automatic or controlled practice trials, values 1 through 6 retain the same meanings as they do during experimental trials.

Because non-trial tutorial screens use TaskPhase=0, analysts should use Introduction to distinguish tutorial screens from experimental block announcements.

An experimental target onset is identified by:

Introduction == 0
and TaskPhase transitions from 4 to 5

A practice target onset is identified by:

Introduction == 1
and PracticeTrial > 0
and TaskPhase transitions from 4 to 5

Condition and Block Encodings

State/Parameter	Value	Meaning
TaskCondition	0	Automatic
TaskCondition	1	Controlled
TaskBlockType	0	Ordered automatic block
TaskBlockType	1	Ordered controlled block
TaskBlockType	2	Pseudorandom mixed block
OrderedStartCondition	0	Automatic first
OrderedStartCondition	1	Controlled first

During the tutorial, TaskCondition reflects the tutorial condition rather than the first experimental condition. It begins at 0 during the general introduction and normal free-movement stages, including in Controlled Only mode, and changes to 1 once the controlled portion of the tutorial begins.

During the tutorial, TaskBlockType is forced to 0 and should not be interpreted as an experimental ordered-automatic block. The participant sees Normal for TaskCondition=0 and Reversed for TaskCondition=1; these labels do not change the state values.

Participant Display

The participant-facing ApplicationWindow contains:

• A light gray background (0xEBEBEB).
• A black cursor whose diameter is configured by CursorDiameterPixels (default 16 pixels in the reference display).
• A black central fixation cross.
• A gray center marker.
• A larger yellow warning marker.
• A green target during automatic (Normal) trials.
• A red target during controlled (Reversed) trials.
• A target diameter controlled by TargetDiameterPixels (default 36 pixels). This value also affects the elliptical target-hit tolerance, not just appearance.
• A visible NORMAL or REVERSED condition cue near the top of the participant display during relevant tutorial stages and block announcements.
• A progress bar near the top of the display during the experiment.
• Tutorial and practice instructions when the introduction is enabled, including white text in a dark gray message box.
• Block announcements using the terms Normal, Reversed, or Mixed.
• An "ended" message when all experimental trials are complete.

The experimental progress bar is hidden throughout the tutorial and practice sequence. Practice trials do not contribute to experimental progress. When a researcher skips the remainder of an experimental block, the bar can advance to reflect the skipped trial positions even though those trials are not counted as successfully completed.

The StimulusDisplay parameter may be used to select the physical monitor on which the participant window appears.

The Normal/Reversed cue is intentional in this USB HID task. The underlying state encoding remains TaskCondition=0 for automatic/Normal and TaskCondition=1 for controlled/Reversed.

Diagnostic Window

A separate diagnostic window is shown to the experimenter. In the currently inspected version, the visible panel is the performance metrics panel. During the tutorial it presents the introduction/practice context, mapping condition and applicable practice-trial information; live timing is shown as placeholders where appropriate, and run averages are not yet available. During experimental trials it presents:

• Normal or Reversed condition and trial numbering within the block and overall experiment.
• Real-time reaction time, movement time, and total time.
• Overall and condition-specific (automatic and controlled) mean timing measurements.

The application still assembles a more detailed diagnostic text label containing tutorial phase, task phase, target position, joystick and cursor coordinates, movement status, block type, completion/reset counts, and other status information. However, that text widget is explicitly hidden in the inspected build (mpDiagnosticText->hide()). These detailed values are not visible in the current diagnostic window and should not be mistaken for on-screen readouts. Relevant values can still be obtained from the recorded states.

Researcher Controls

The diagnostic window contains a blue CONTINUE button on eligible tutorial screens. When continuation is unavailable, it displays CONTINUE UNAVAILABLE.

Its context-sensitive reset button displays:

• RESET PRACTICE TRIAL during eligible practice trials.
• RESET CURRENT TRIAL during eligible experimental trials.
• RESET UNAVAILABLE when reset is not permitted.

The current window also includes SKIP TRIAL, SKIP CURRENT BLOCK, SKIP INTRODUCTION, SKIP PRACTICE, SKIP SANDBOX, and PAUSE/RESUME. Controls are enabled only in the appropriate task context. Skipping the current block and skipping the introduction prompt for confirmation; the other skip controls act without a confirmation dialog.

Researcher Skip Controls

Control	When available	Behavior	Recorded event
SKIP TRIAL	During an experimental trial before feedback, while not paused	Immediately advances to the next trial (or finishes the run if it was the last trial). A new target is generated for the next trial. A skipped trial does not increment completed-trial or reset metrics. In a controlled trial the return-to-anchor behavior is retained as needed.	TrialSkipped
SKIP CURRENT BLOCK	During an experimental trial before feedback, while not paused; confirmation required	Skips the remaining trials in the current block, advances to the next block or ends the run, and increments the overall trial-position counter by the number skipped. It does not count these trials as completed.	ConditionSkipped
SKIP INTRODUCTION	During the tutorial, while not paused; confirmation required	Exits the entire tutorial, restores the saved first experimental target, and enters the experimental block-announcement sequence.	IntroductionSkipped
SKIP PRACTICE	During an active practice trial, while not paused	Ends the remaining practice trials for that practice condition. After Normal practice, proceeds to Reversed instructions if configured, otherwise tutorial completion; after Reversed practice, proceeds to completion.	PracticeSkipped
SKIP SANDBOX	During Normal or Reversed free movement, while not paused	Ends the free-movement stage and proceeds to the appropriate next instructions, practice stage, or completion screen.	SandboxSkipped

Each skip event is written as a one-processing-block state pulse and is cleared at the beginning of the next processing block. Skip actions can bypass the regular end-of-Process() state synchronization. Therefore, the event pulse may precede the updated TaskPhase, TaskTrial, TaskBlock, target, or cursor states by one processing block. If a skip ends the entire run, the last recorded phase/trial values may retain their pre-skip values rather than representing the usual Finished-phase state. Offline analyses should therefore use the event states, not rely solely on a simultaneous change in other states.

Pause and Resume

The PAUSE/RESUME control is available during both tutorial and experimental portions of the run, but not after the task finishes.

• Pausing sets TaskPaused=1. Task trial and cursor progression stop, but the BCI2000 stream continues to record samples with the pause state high.
• Resuming sets TaskPaused=0. The program shifts the applicable phase, tutorial, target-onset, and movement-onset clocks forward by the paused duration.
• Paused time is excluded from the application's reaction time, movement time, total time, and active phase durations.
• Researcher skip actions are unavailable while paused.

A paused BCI2000 recording is not the same as a stopped BCI2000 run. Analysts should explicitly account for samples with TaskPaused=1.

Trial Reset

Experimental trials may be manually reset before they reach the feedback phase.

Resetting an experimental trial:

• Returns the task to the waiting-for-center phase.
• Clears the current movement and timing states.
• Generates a TrialReset event.
• Increments the experimental diagnostic reset count.
• Keeps the same trial number.
• Keeps the same target.
• Does not generate a successful-trial event or count as a completed experimental trial.

Practice trials may also be reset before feedback.

Resetting a practice trial:

• Returns the practice trial to the waiting-for-center phase.
• Clears movement and timing states.
• Generates a TrialReset event.
• Keeps the same PracticeTrial value.
• Keeps the same deterministic target.
• Does not increment experimental reset metrics.
• Does not increment experimental completed-trial metrics.

Reset is unavailable during tutorial instruction/free-movement screens and after a trial has entered feedback. Resetting a controlled trial after its target is visible also enables return-to-anchor handling so that resuming normal cursor control does not produce an abrupt jump. Reset preserves the current trial and its target, whereas SKIP TRIAL advances to a new one.

Timing Measurements

The task calculates reaction time, movement time, and total time for successfully completed practice and experimental trials.

Reaction time is the interval between target appearance and detected movement onset.

Movement time is the interval between detected movement onset and target acquisition.

Total time is the interval between target appearance and target acquisition.

Movement onset is detected when either joystick axis differs from the center-hold baseline by more than the task's joystick deadzone.

Timing is measured using a steady clock, but movement onset and target acquisition are detected during calls to Process(). The effective temporal resolution is therefore limited by the BCI2000 processing-block interval.

Practice timing values are recorded in the BCI2000 states but are excluded from experimental timing summaries. The task writes no application-specific CSV. When the researcher pauses the task, clock offsets are adjusted on resume so that the reported RT, MT, and total time exclude the paused interval, even though the paused samples remain in the BCI2000 data stream.

Data Recording

The task records its behavioral and tutorial variables as BCI2000 states, allowing them to be synchronized with the normal BCI2000 .dat recording.

Joystick coordinates are also recorded when joystick input logging is enabled.

Tutorial and practice samples are part of the same BCI2000 run as the experiment. The Introduction state should therefore be used when separating tutorial/practice data from experimental data during offline analysis.

Practice trials record:

• Cursor trajectory.
• Target coordinates and angle.
• Trial phase.
• Practice condition.
• Movement onset.
• Target acquisition.
• Reaction time.
• Movement time.
• Total time.
• Practice reset events.
• Practice trial number.

Practice trials are intentionally excluded from:

• Experimental TaskTrial numbering.
• Experimental TaskBlock numbering.
• Automatic and controlled completion counts.
• Automatic and controlled reset counts.
• Mean reaction-time summaries.
• Mean movement-time summaries.
• Mean total-time summaries.

No secondary results file is created by this application in the current version. The ResultsFile parameter and trial-level CSV writer were removed. All per-trial behavioral information must be reconstructed from the recorded BCI2000 .dat states; joystick state recording additionally depends on the normal LogJoystick configuration.

Researcher skip events (TrialSkipped, ConditionSkipped, IntroductionSkipped, PracticeSkipped, SandboxSkipped) and the persistent TaskPaused state are also recorded. They identify deviations from ordinary trial/tutorial progression and samples recorded during pause.

The application writes BCI2000 console messages when the task starts and stops and when practice or experimental trials succeed. Messages include the applicable trial/condition and reaction/movement times; these console messages are not an additional trial-level results file and should not be treated as synchronized state data.

Parameters

Parameters for experimental structure, timing, and display are grouped under Application:USBHIDJoystick in the BCI2000 parameter tree. EnableIntroduction, AutomaticPracticeTrials, ControlledPracticeTrials, and PracticeCenterHoldTime are grouped under Application:Introduction. Existing parameter files should use the current group definitions.

EnableIntroduction

Enables or disables the participant tutorial and practice sequence.

Type: integer boolean

Default: 1

Range: 0-1

Values:

• 0: Skip the tutorial and begin the experiment normally.
• 1: Run the tutorial and practice sequence before the experiment.

This parameter applies to all experiment modes.

AutomaticPracticeTrials

Number of automatic practice trials presented during the tutorial.

Type: integer

Default: 3

Range: 0-20

The parameter is used only when the selected experiment mode contains automatic trials.

A value of 0 skips automatic practice trials while retaining the automatic instruction page.

Practice trials do not count toward the experimental trial-count parameters.

ControlledPracticeTrials

Number of controlled practice trials presented during the tutorial.

Type: integer

Default: 3

Range: 0-20

The parameter is used only when the selected experiment mode contains controlled trials.

A value of 0 skips controlled practice trials. The controlled instruction page and controlled free-movement demonstration are still presented.

Practice trials do not count toward the experimental trial-count parameters.

PracticeCenterHoldTime

Center-hold duration used during automatic and controlled practice trials.

Type: floating-point time

Default: 1s

Range: 0s-60s

This parameter replaces CenterHoldSeconds during practice trials only.

Experimental trials continue to use CenterHoldSeconds.

ExperimentMode

Selects the overall experimental structure.

Type: integer enumeration

Default: 1

Range: 1-4

Values:

• 1: Automatic only
• 2: Controlled only
• 3: Ordered automatic and controlled
• 4: Ordered automatic, ordered controlled, and pseudorandom mixed

The application verifies during preflight that the trial-count parameters required by the selected mode are at least 1.

The selected mode also determines which condition-specific tutorial sections are presented when EnableIntroduction=1.

AutomaticTrials

Number of automatic experimental trials used by experiment modes 1 and 3.

Type: integer

Default: 5

Declared range: 0-10000

When used by the selected experiment mode, the value must be at least 1.

Practice trials are additional and do not reduce or increment this count.

ControlledTrials

Number of controlled experimental trials used by experiment modes 2 and 3.

Type: integer

Default: 5

Declared range: 0-10000

When used by the selected experiment mode, the value must be at least 1.

Practice trials are additional and do not reduce or increment this count.

OrderedStartCondition

Determines which experimental condition is presented first in experiment mode 3.

Type: integer enumeration

Default: 0

Values:

• 0: Automatic first
• 1: Controlled first

This parameter does not affect experiment modes 1, 2, or 4.

It also does not affect tutorial order. When both conditions are included, the tutorial always presents automatic training before controlled training.

OrderedAutomaticTrials

Number of experimental automatic trials in the ordered automatic block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

OrderedControlledTrials

Number of experimental controlled trials in the ordered controlled block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

RandomAutomaticTrials

Number of experimental automatic trials included in the pseudorandom block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

RandomControlledTrials

Number of experimental controlled trials included in the pseudorandom block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

StimulusDisplay

Selects the physical display used for the participant-facing application window.

Type: integer enumeration

Default: 0

Values:

• 0: Automatic/default ApplicationWindow placement.
• 1 and above: Select one of the displays detected when the parameters are published.

On Windows, available monitors are enumerated with their dimensions and primary-display status.

The application verifies during preflight that the selected display exists.

CenterHoldSeconds

Duration for which the participant must keep the cursor within the center region during experimental trials.

Type: floating point

Default: 3.0 seconds

Range: 0.0-60.0 seconds

Leaving the center during this interval restarts the center-acquisition sequence.

This parameter does not control practice center-hold duration. Practice trials use PracticeCenterHoldTime.

WarningSeconds

Duration of the yellow warning cue.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

Leaving the center during the warning interval restarts the center-acquisition sequence.

This parameter applies to both practice and experimental trials.

PreTargetDelaySeconds

Delay between the end of the warning cue and target appearance.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

The participant must remain centered during this interval.

This parameter applies to both practice and experimental trials.

FeedbackSeconds

Interval between successful target acquisition and advancement to the next trial, tutorial transition, or experimental block.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

This parameter applies to both practice and experimental trials.

CursorDiameterPixels

Cursor diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.

Type: floating point

Default: 16.0

Range: 1.0-1000.0

A positive value is required by preflight validation.

TargetDiameterPixels

Target diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.

Type: floating point

Default: 36.0

Range: 1.0-1000.0

A positive value is required by preflight validation. In addition to determining visual size, this parameter affects the ellipse used to determine target acquisition. Consequently, changing it can change the effective movement tolerance and behavioral measurements.

The ResultsFile parameter was removed; see Data Recording.

States

The following states are defined by USBHIDJoystickTask and are recorded with the normal BCI2000 data stream.

Introduction

1-bit state indicating whether the participant tutorial/practice sequence is active.

Initial value: 0

Values:

• 0: Tutorial inactive or disabled; experimental data
• 1: Tutorial or practice sequence active

When EnableIntroduction=1, this state becomes 1 at the beginning of the run and returns to 0 when the tutorial completes and the experiment begins.

This is the primary state for separating tutorial/practice samples from experimental samples during offline analysis.

TutorialPhase

4-bit state indicating the current stage of the tutorial.

Initial value: 0

Values:

• 0: Tutorial inactive
• 1: General introduction
• 2: Normal free movement
• 3: Automatic instructions
• 4: Automatic practice
• 5: Controlled instructions
• 6: Controlled free movement
• 7: Controlled practice
• 8: Practice complete

After the final automatic or controlled practice feedback interval, TutorialPhase may remain 4 or 7 while PracticeTrial has returned to 0 and the task waits for the participant to return to center.

Outside the tutorial, TutorialPhase is 0.

PracticeTrial

8-bit state identifying the active practice trial.

Initial value: 0

Values:

• 0: No active practice trial
• 1 and above: One-based practice trial number within the current practice condition

The state remains nonzero through the practice trial's feedback phase.

After the final practice feedback interval it returns to 0 while the tutorial may still wait for the participant to return to center.

Resetting a practice trial does not increment PracticeTrial.

CursorX

10-bit state representing the current horizontal cursor coordinate.

Initial value: 512

Produced range: 0-1023

The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.

CursorY

10-bit state representing the current vertical cursor coordinate.

Initial value: 512

Produced range: 0-1023

The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.

TaskPhase

3-bit state containing the current trial phase.

Initial value: 0

Values:

• 0: Experimental block announcement or non-trial tutorial screen
• 1: Waiting for center
• 2: Holding center
• 3: Warning
• 4: Pre-target delay
• 5: Target visible
• 6: Feedback
• 7: Finished

During active practice trials, values 1 through 6 have the same meanings as during experimental trials.

During non-trial tutorial screens, TaskPhase is forced to 0. Therefore, TaskPhase=0 alone no longer uniquely identifies an experimental block announcement.

Use:

Introduction == 0 and TaskPhase == 0

to identify an experimental block announcement.

TaskCondition

1-bit state identifying the current movement condition.

Initial value: 0

Values:

• 0: Automatic (participant-facing Normal)
• 1: Controlled (participant-facing Reversed)

During active practice trials, this state identifies the practice condition.

During the general introduction and normal free-movement tutorial stages, it initially reports 0 even when the configured experiment is Controlled Only.

During the experiment it retains its original meaning.

TaskBlockType

2-bit state identifying the type of the current experimental block.

Initial value: 0

Values:

• 0: Ordered automatic
• 1: Ordered controlled
• 2: Pseudorandom mixed

During the tutorial, this state is forced to 0. It should therefore only be interpreted as an experimental block type when Introduction=0.

TargetAngle

12-bit state containing the target angle in tenths of a degree.

Initial value: 0

During experimental trials, generated values range from 0-3599.

To convert to degrees:

degrees = TargetAngle / 10

During practice trials, the state contains the deterministic practice-target angle.

During non-trial tutorial screens, the state is set to 0.

After tutorial completion, the saved first experimental target is restored.

TargetX

10-bit state containing the horizontal coordinate of the current target.

Initial value: 512

Coordinate units correspond to the task's 0-through-1023 coordinate system.

During practice trials, it describes the current deterministic practice target.

During non-trial tutorial screens, the target coordinate is written as 0 rather than retaining its initial value 512; gate it by task phase and tutorial status during analysis.

TargetY

10-bit state containing the vertical coordinate of the current target.

Initial value: 512

Coordinate units correspond to the task's 0-through-1023 coordinate system.

During practice trials, it describes the current deterministic practice target.

During non-trial tutorial screens, the target coordinate is written as 0 rather than retaining its initial value 512; gate it by task phase and tutorial status during analysis.

TaskBlock

8-bit state containing the current one-based experimental block number.

Initial value: 0

While Introduction=1:

TaskBlock = 0

When the tutorial completes, the first experimental block begins with:

TaskBlock = 1

Practice trials do not consume experimental block numbers.

TaskTrial

16-bit state containing the current one-based overall experimental trial number.

Initial value: 0

While Introduction=1:

TaskTrial = 0

When the tutorial completes, the first experimental trial begins with:

TaskTrial = 1

Trial numbering continues across experimental block boundaries. Manually resetting an experimental trial does not increment TaskTrial.

Practice trials do not consume experimental trial numbers.

MovementStarted

1-bit state indicating whether movement onset has been detected during the current active practice or experimental trial.

Initial value: 0

The state changes to 1 when joystick displacement exceeds the movement deadzone after target onset. It remains high during the remainder of the movement and feedback period.

A rising transition from 0 to 1 identifies movement onset.

During non-trial tutorial screens, the state is forced to 0.

Use Introduction to distinguish practice movement onset from experimental movement onset.

TargetHit

1-bit event-like state indicating successful target acquisition.

Initial value: 0

The state is set to 1 when the cursor reaches a practice or experimental target and is cleared at the beginning of the following processing block. It therefore acts as a one-processing-block pulse.

Experimental acquisition:

TargetHit == 1 and Introduction == 0

Practice acquisition:

TargetHit == 1 and Introduction == 1

TrialReset

1-bit event-like state indicating a manual trial reset.

Initial value: 0

The state is set to 1 when the experimenter successfully resets a practice or experimental trial and is cleared at the beginning of the following processing block.

Experimental reset:

TrialReset == 1 and Introduction == 0

Practice reset:

TrialReset == 1 and Introduction == 1

TrialSkipped

1-bit event state for the researcher's SKIP TRIAL command during an eligible experimental trial.

Initial value: 0

The state is set to 1 when an experimental trial is skipped and cleared on the following processing block. Skipping advances trial position without counting a successful target acquisition and without increasing completed/reset metrics. The next trial receives a newly generated target, unless the run ends.

ConditionSkipped

1-bit event state for the researcher's SKIP CURRENT BLOCK command.

Initial value: 0

The state is set to 1 for one processing block when the remainder of the current experimental block is skipped. This command advances the overall trial-position counter over the skipped trials, which can change the progress indicator without changing completed-trial counts. The control requires experimenter confirmation.

IntroductionSkipped

1-bit event state for the researcher's SKIP INTRODUCTION command.

Initial value: 0

The state is set to 1 for one processing block when the tutorial is exited before normal completion. The current run proceeds directly to the experimental block-announcement sequence and restores the saved first experimental target. This control requires confirmation.

PracticeSkipped

1-bit event state for the researcher's SKIP PRACTICE command.

Initial value: 0

The state is set to 1 for one processing block when the remaining trials in the current practice condition are bypassed. It identifies incomplete tutorial practice and is distinct from experimental TrialSkipped.

SandboxSkipped

1-bit event state for the researcher's SKIP SANDBOX command.

Initial value: 0

The state is set to 1 for one processing block when a Normal or Reversed free-movement sandbox is bypassed. The tutorial advances to the appropriate next stage.

TaskPaused

1-bit persistent (level) state showing whether the task is paused.

Initial value: 0

• 0: Task running normally.
• 1: Task paused; task progression is suspended, while the BCI2000 data stream continues.

Unlike the five skip states, TaskPaused remains high throughout a pause and returns to 0 on resume. Paused time is excluded from the task's reported timing intervals by shifting the relevant clock references on resume.

ReactionTimeMs

32-bit state containing reaction time in milliseconds.

Initial value: 0

Reaction time is measured from target appearance to detected movement onset.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

MovementTimeMs

32-bit state containing movement time in milliseconds.

Initial value: 0

Movement time is measured from detected movement onset to target acquisition.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

TotalTimeMs

32-bit state containing total target-directed trial time in milliseconds.

Initial value: 0

Total time is measured from target appearance to target acquisition.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

External Joystick States

The application also uses states provided by BCI2000's input logging system. These states are not defined by USBHIDJoystickTask itself.

State	Description
JoystickXpos	Horizontal joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
JoystickYpos	Vertical joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
JoystickButtons1	State of joystick button 1. During the tutorial, a rising press may advance eligible instruction or free-movement screens. It does not advance active practice trials and does not control experimental progression.
Running	Standard BCI2000 system state. The application sets it to 0 when all configured experimental trials have been completed.

For details about enabling joystick recording and the joystick states provided by BCI2000, see Logging Input.

Data Analysis Notes

Because the tutorial and practice sequence are recorded within the same BCI2000 run as the experiment, analyses should use Introduction to distinguish experimental data from tutorial and practice data.

Measurement/Event	Recommended identification
Experimental samples	Introduction == 0
Tutorial/practice samples	Introduction == 1
Experimental trial	Introduction == 0 and TaskTrial > 0; check skip events when reconstructing completed trials
Practice trial	Introduction == 1 and PracticeTrial > 0
Experimental block announcement	Introduction == 0 and TaskPhase == 0
Non-trial tutorial screen	Introduction == 1, typically with TaskPhase == 0
Experimental target onset	Introduction == 0 and transition from TaskPhase=4 to TaskPhase=5
Practice target onset	Introduction == 1, PracticeTrial > 0, and transition from TaskPhase=4 to TaskPhase=5
Experimental movement onset	Rising transition of MovementStarted with Introduction == 0
Practice movement onset	Rising transition of MovementStarted with Introduction == 1
Experimental target acquisition	TargetHit == 1 and Introduction == 0
Practice target acquisition	TargetHit == 1 and Introduction == 1
Experimental reset	TrialReset == 1 and Introduction == 0
Practice reset	TrialReset == 1 and Introduction == 1
Experimental trial number	TaskTrial
Practice trial number	PracticeTrial
Experimental block number	TaskBlock
Automatic vs. controlled	TaskCondition, interpreted together with Introduction
Ordered vs. mixed experimental block	TaskBlockType when Introduction == 0
Reaction time	ReactionTimeMs, gated by Introduction and the relevant trial event
Movement time	MovementTimeMs, gated by Introduction and the relevant trial event
Total time	TotalTimeMs, gated by Introduction and the relevant trial event
Cursor trajectory	CursorX and CursorY
Target coordinates	TargetX and TargetY on actual trials; non-trial tutorial screens set these to 0
Target angle	TargetAngle
Skipped experimental trial	TrialSkipped == 1
Skipped experimental block remainder	ConditionSkipped == 1
Introduction bypassed	IntroductionSkipped == 1
Practice bypassed	PracticeSkipped == 1
Free-movement sandbox bypassed	SandboxSkipped == 1
Samples recorded while the task is paused	TaskPaused == 1

TargetHit, TrialReset, TrialSkipped, ConditionSkipped, IntroductionSkipped, PracticeSkipped, and SandboxSkipped are single-processing-block pulses. MovementStarted remains high after movement onset until the trial advances or is reset. TaskPaused is a level state that remains high throughout a pause.

Analyses written for earlier versions of the task should be updated before use with tutorial-enabled data. In particular:

• TaskPhase=0 no longer always identifies an experimental block announcement.
• TargetHit=1 may indicate a practice or experimental success.
• TrialReset=1 may indicate a practice or experimental reset.
• Nonzero timing states may belong to practice trials.
• TaskCondition and TaskBlockType should not be interpreted as experimental condition/block variables while Introduction=1.
• Skip events mark incomplete trials or tutorial stages; skipped experimental trials do not produce TargetHit or increase completed-trial metrics.
• ConditionSkipped can cause the progress indicator and overall trial-position counter to jump across uncompleted trials.
• On a skip processing block, non-event states such as TaskTrial, TaskBlock, TaskPhase, and target coordinates may not update until the following block because skip dispatch returns before the normal state synchronization. A skip that finishes the run can leave final values at their pre-skip settings.
• Samples recorded during TaskPaused=1 remain in the .dat stream. Exclude or flag them as appropriate; RT/MT/total-time values already exclude the pause duration.
• TargetX and TargetY are 0 during non-trial tutorial screens, not their initial 512 values.
• Condition names printed on screen and in console messages are Normal/Reversed, but the numeric TaskCondition codes remain Automatic=0 and Controlled=1.
• No application-specific CSV is created in the current version; reconstruct trial-level results from synchronized BCI2000 state recordings.

References

Neumann WJ, Schroll H, de Almeida Marcelino AL, Horn A, Ewert S, Irmen F, Krause P, Schneider GH, Hamker F, Kühn AA. Functional segregation of basal ganglia pathways in Parkinson's disease. Brain. 2018;141(9):2655-2669. doi:10.1093/brain/awy206.

See also

• Logging Input
• LogJoystick
• Module Command Line Options
• ApplicationWindow Class
• BCI2000 File Format
• ApplicationBase Class