⚠️ Work in progress. This repository adapts the 2-axis joystick rig from Mathis et al., 2017 into a 1D forelimb object-push task. The working rig VIs have been imported, and the rest-pad-to-reward success path is bench-tested. Mechanical push-object development, animal-specific calibration, training presets and safety/edge-case validation remain in progress.

Forked and adapted from the original JoystickControlSystem (Mathis lab). The original rig trained head-fixed mice to pull a 2-axis joystick against a lateral magnetic perturbation. This fork keeps the same LabVIEW architecture and NI-DAQ backbone but reworks the task into a goal-directed forward push.

Each trial:

forepaw on rest pad  →  trial starts  →  reach to object  →  push forward
  →  (optional future axial resistance)  →  object held in target band
  →  auditory success cue  →  short delay  →  lick spout extends  →  water reward  →  spout retracts

Key differences from the original task:

• 1D push instead of 2D pull — the task-relevant axis remains in the existing coordinate structure; the lateral axis will be physically constrained by the existing 3D-printed delimiter.
• Bounded target zone — reward requires the object to end and remain within a target distance band (overshoot fails).
• Rest-pad initiation — a trial can only start when the object is home (spring-loaded) and the forepaw is on the rest pad, giving a clean pre-contact trial-start state.
• Planned axial resistance perturbation (opposing the push) instead of a lateral kick. The training rig currently has no magnet; Dev1/ao0 and the LabVIEW control path are reserved for one.
• Delayed, retractable reward with an immediate auditory success cue, separating push execution from licking/reward for cleaner neural alignment.
• Planned session blocks (via parameter files): Baseline → Random perturbation → Fixed perturbation → Washout.

• Canonical VIs imported from the behavioural rig and pushed on 18 August 2026.
• Bench-validated path: object home + FSR paw gate → trial → success cue → adjustable delay → spout extension → water → consumption wait → spout retraction.
• The acquisition helper reads joystick X/Y, lick/frame signals and the new rest-pad channel.
• A fresh GitHub copy now opens and completes the full bench sequence on the rig PC using the compatible repository helper VIs.
• Safe startup now commands water/cue LOW, spout retract and magnet 0 V. One canonical Stop cleanly ends every parallel loop; idle, reward-delay and spout-extended Stop tests passed.
• Remaining validation includes repeated-cycle testing and explicit fail/timeout checks. LabVIEW's toolbar Abort remains emergency-only because it bypasses normal cleanup.
• Remaining build work includes the final push object, animal-safe rest-pad cover, mouse-specific calibration and training-stage controls/presets.

Existing rig hardware:

• NI-DAQ card, PCIe-6321 (Dev1 on the live rig)
• Joystick base/readout (Digi-Key 679-2501-ND)
• 3D-printed lateral delimiter (constrains the task to 1D)

Mechanical adaptation still required:

• Convert the joystick handle into a spring-return push object with a larger contact surface, positioned close to the rest pad.

New components for the push task:

The validated live NI-MAX configuration, SCB-68A wiring and bench-test history are documented in RIG_INVENTORY.md.

The PCIe-6321 has two AO channels. The working design reserves AO0 for axial resistance and uses AO1 for the lick-spout actuator; the auditory cue therefore uses a digital line.

The main VI is Push Behaviour_MCHALABI.vi. Its required local dependencies are avg joystick and frame trig lick3.vi, frame counter.vi and PushTask Globals.vi.

The program retains the original occurrence-driven five-state architecture and trajectory logging while adding the FSR gate, digital success cue, retractable-spout reward sequence and shared normal-stop signal for all asynchronous loops. It requires LabVIEW and NI-DAQmx. Saved NI-MAX tasks are machine-local and must be imported or configured on each rig. The validated task/channel map is documented in RIG_INVENTORY.md, with the 20 August 2026 NI-DAQmx backup stored at ni-max/JoystickPushTask_NIMAX_2026-08-20.nce.

The original experimental parameters are loaded from a text file, one line per trial. They define the home/start/end regions, hold times, water-valve open time and perturbation command/timing.

The imported VI currently exposes bench controls for the FSR threshold, cue duration, reward delay, spout extend/retract voltages, spout settling and consumption time. These new settings have not yet been added to the per-trial parameter-file loader or logged session metadata. Training-stage presets and Baseline → Random → Fixed → Washout files also remain to be created.

Each rig must be calibrated for volts→mm on the push axis (the original demo assumes a 2.55 V rest with 0.05 V ≈ 1 mm — remeasure for your build). Test all channels in NI-MAX before running.

Please cite the original work this task is built on:

• Mathis et al., 2017 — Somatosensory Cortex Plays an Essential Role in Forelimb Motor Adaptation in Mice.

We greatly thank Dr. Ed Soucy at the Harvard CBS Center for Neuroengineering for the original LabVIEW code and expert advice throughout the development of this joystick system.