Installation Instructions

Clone repository onto your computer

• Open GitHub Desktop, click clone from URL
• URL: https://github.com/AllenNeuralDynamics/dynamic-foraging-task.git
• installation directory should be C:\Users\svc_aind_behavior\Documents\GitHub\

Install Bonsai on your computer

• In a file window, open C:\Users\svc_aind_behavior\Documents\GitHub\dynamic-foraging-task\bonsai
• Click on setup.cmd

Update Harp board firmware:

• Skip this step unless you know what you are doing

Update the firmware of the Harp Behavior Board

• following the instructions here.

Setting up the Harp Soundcard and uploading the GoCue soundwaveform

• follow the instruction here

Update the firmware of the Harp Sound Board

• following the instructions here.
• firmware is stored in \allen\aind\scratch\Xinxin\SoundcardFirmware.

Create a conda environment, with python version 3.11

• install conda instructions here
• Add conda to the path variable
  • instructions from here
  • Open Advanced System Settings
  • Click on "Environment Variables", then "Edit Path", then add the following paths:
    • C:\Users\svc_aind_behavior\AppData\Local\miniconda3
    • C:\Users\svc_aind_behavior\AppData\Local\miniconda3\Scripts
    • C:\Users\svc_aind_behavior\AppData\Local\miniconda3\Library\bin
    • C:\Users\svc_aind_behavior\AppData\Local\miniconda3\condabin
  • If you see an entry for AppData\Local\Microsoft\WindowsApps move this path entry to the bottom
• Open miniconda3 prompt, and type conda init. Close, and reopen the prompt
• Create an environment: conda create -n Foraging python=3.11

Use pip to install

• Open miniconda3 prompt
• Activate the environment: conda activate Foraging
• change to the directory: C:\Users\svc_aind_behavior\Documents\GitHub\dynamic-foraging-task
• run pip install -e .
• This should install all the required python packages.
• If you encounter errors in dependency or finding repositories, see below for trouble shooting.

Copy the Settings for each box

• Copy dynamic-foraging-task/src/setting_templates/Settings_box<box num>.csv to Users\svc_aind_behavior\Documents\ForagingSettings

  • Copy <box num> 1-4 depending on the computer (A,B,C,D maps to 1,2,3,4)

  • Configure the Behavior/Soundcard COM ports for each computer (instruction to find COM ports).

    • Note: if your computer is running multiple behavior boxes (447), then you can unplug the USB cables for the Behavior and Soundcard boards for one of the two behavior boxes connected to each computer.
    • In a file browser, navigate to C:\Users\svc_aind_behavior\Documents\GitHub\dynamic-foraging-task\bonsai
    • Click on Bonsai, then New Project
    • In the Toolbox window type Device (Harp)
    • Select the Node, then in the side tab in the main editor, iterate through the COM Ports and look in the console window, which will tell you which board is connected to which COM port.

  • The BonsaiOsc ports are determined by the box number, and should not be modified.

  • AINDLickDetector: use 1 if using the AIND Lickity Split detector, 0 otherwise

    • If using the AIND lick detector, then you need to set the following fields:
    • LeftLickDetector: COM port for the left lick detector
    • RightLickDetector: COM port for the right lick detector

  • HighSpeedCamera: use 0 if not using high speed cameras, 1 otherwise

    • The following settings are only relevant if HighSpeedCamera is enabled:
    • HasSideCameraLeft: use 0 if not using a high speed left camera, 1 otherwise
    • HasSideCameraRight: use 0 if not using high speed right camera, 1 otherwise
    • HasBodyCamera: use 0 if not using high speed body camera, 1 otherwise
    • HasBottomCamera: use 0 if not using high speed bottom camera, 1 otherwise
    • SideCameraLeft: serial number for high speed left side camera (instruction to find serial number)
    • SideCameraRight: serial number for high speed right side camera
    • BodyCamera: serial number for high speed body camera
    • BottomCamera: serial number for high speed bottom camera
    • codec The codec for high speed camera encoding

Set up the desktop shortcuts

• Copy dynamic-foraging-task\src\desktop_shortcuts\Box<box num>.bat to the Desktop
• Copy <box num> A-D depending on the computer
• Repeat for Box<box num> with console.bat

Configure ForagingSettings.json

• Make a folder Users\svc_aind_behavior\Documents\ForagingSettings
• Copy the template from dynamic-foraging-task\src\setting_templates\ForagingSettings.json to Users\svc_aind_behavior\Documents\ForagingSettings\ForagingSettings.json
  • You should not have to modify these settings:
    • "bonsai_path":"C:\Users\svc_aind_behavior\Documents\Github\dynamic-foraging-task\bonsai\Bonsai.exe",
    • "bonsaiworkflow_path":"C:\Users\svc_aind_behavior\Documents\Github\dynamic-foraging-task\src\workflows\foraging.bonsai"
    • "default_saveFolder": "C:\Documents\"
    • "temporary_video_folder":"C:\Users\svc_aind_behavior\Documents\temporaryvideo\",
    • "show_log_info_in_console":false (only used for debugging)
  • This field is mandatory and must be configured for each computer:
    • "current_box": For example "447-1". For computers in 446/447, use "447-<tower_number>", for example: , "447-1"
  • These settings need to be configured for each computer:
    • "Teensy_COM": For example "COM10",
      • This is only for fiber-photometry
      • Follow instructions on the wiki to install Arduino IDE (1.8x) and TeensyDuino
      • Once both are installed open ArduinoIDE, go to Tools>Port, select COMport cooresponding to Teensy4.1, and this value to the ForagingSettings.json
    • "FIP_workflow_path":
      • This is only for fiber-photometry
      • A string path to the ThorFIP.bonsai workflow in the FIP_DAQ_control repo
    • "newscale_serial_num_box1": For example 46103
    • "newscale_serial_num_box2": For example 46104
    • "newscale_serial_num_box3": For example 46105
    • "newscale_serial_num_box4": For example 46106
      • Determine the serial numbers of the Newscale Stages
        • Unplug the stages for one of the two boxes
        • Open Miniconda Prompt
        • type conda activate Foraging
        • navigate to dynamic-foraging-task/src/foraging)gui
        • python
        • from MyFunctions import NewScaleSerialY
        • serial_num = NewScaleSerialY.get_instances()[0]
      • Edit ForagingSettings.json to add a line "newscale_serial_num_box1":<serial number for rig 1>
        • (A,B,C,D maps to 1,2,3,4)

Create the log file folder

• Create a log file folder at Users\svc_aind_behavior\Documents\foraging_gui_logs

Attempt to run the GUI

• Click on the "BoxX.bat" you added to the desktop. The gui should initialize. If it does not, see the trouble shooting steps below.
• Press the start button to start the task. There should be audible 'beeps' as the sound cue plays for each trial. Confirm that the task runs for several trials.

Trouble shooting

"Instance property BufferSize is not defined for type Bonsai.DAQmx.TriggeredAnalogOutput"

Make sure the NIDaq software is installed

conda installation of the repository fails (e.g. errors about incompatible packages.)

• Open Advanced System Settings
• Click on "Environment Variables"
• Under System Variables, delete any entries for PIP_INDEX_URL and PIP_TRUSTED_HOST

Errors about git

• Note: Git errors can be sneaky, because they sometimes masquerade as python errors. For example:

  is just a git error, NOT problem with the Foraging python code.

• Ensure git is up to date and that you are using a standalone git install, not something installed by another program (usually 'cmder'). -to check the git version, type git --version in the command prompt - if its less than 2.30, install a new version of git (see below).

  • type where git into a command line to see where git is installed. If there is more than one version of git and/or the git path includes cmder, then uninstall cmder:
    • if needed uninstall cmder. 'cmder' is not registered by "Add/remove programs." To remove, you will need to delete it from 'C:/Program Files/' AND THEN THE RECYCLING BIN. It is going to ask you for admin privileges to do this, and it's easier if you select "Do this for all current files." Once it is gone, install a new version of git.

  

• TO INSTALL GIT: (re) install git:

  • If you have not already installed the Github Desktop gui, a "good" version of git will install automatically when you do. See: https://github.com/git-guides/install-git#install-git-on-windows
  • If you already did the above step, reinstalling the Desktop gui WILL NOT install git. You need to do this yourself. A link to download is here. Accept all defaults, excepting the note in the next bullet.: https://gitforwindows.org/, with more detailed instructions here if you have problems: https://github.com/git-guides/install-git#install-git-on-windows.
  • NOTE: all of the default settings work here, EXCEPT that you likely already went to the trouble of installing OpenSSH. You can therefore select the "external OpenSSH" option.

• I think I got everything under control, how do I check if it is right?

  • typing where git into a command prompt should now point you to one and only one version of git in a stand alone program folder, e.g.:

  

Errors about missing python packages.

• Try repeating the pip install -e . step in the dynamic-foraging-gui. This can happen if, for example, someone has changed pushed changes that change dependencies since you last ran this command.

PowerShell has a warning about scripts

• redo the "Allow scripts to run in PowerShell" step. Remember to run as admin, and to respond to the prompts.

Bonsai and/or the GUI complain about cameras or COM ports not existing or having the wrong ID.

• Check the Settings for the box .json in the Foraging Settings folder. Something here is probably set wrong for this computer.

Trials stall after the first trial

Make sure the firmware on the harp boards is up to date, and that you have the and that you have the driver installed for the computer