Installation guide

Prerequisites

  • A computer running Windows 10 or 11,

  • A working installation of git for windows, and

  • Notepad++ or some other decent text editor.

Tip

iblrigv8 can be installed alongside older versions of iblrig without affecting the latter.

Tip

If you believe this guide is incomplete or requires improvements, please don’t hesitate to reach out and submit a bug report.

Preparing Windows PowerShell

Open Windows PowerShell in administrator mode:

  • Click on the Windows Start button or press the Windows key on your keyboard.

  • Type “PowerShell” into the search bar.

  • You should see “Windows PowerShell” or “PowerShell” in the search results.

  • Right-click on it.

  • In the context menu that appears, select “Run as administrator.”

Now, run the following command at the prompt of Windows PowerShell:

Set-ExecutionPolicy RemoteSigned -Force

Tip

Keep the Administrator PowerShell open for the next step.

Background

In PowerShell, there are execution policies that determine the level of security for running scripts. The default execution policy is often set to Restricted, which means that scripts are not allowed to run. However, to install Python or run certain scripts, you need to adjust the execution policy. By setting the execution policy to RemoteSigned, you are allowing the execution of locally created scripts without any digital signature while requiring that remotely downloaded scripts (from the internet) must be digitally signed by a trusted source to run. This strikes a balance between security and usability.

Installing Visual C++ Redistributable

With the Administrator PowerShell still open, run the following commands:

New-Item -ItemType Directory -Force -Path C:\Temp
Invoke-WebRequest -Uri https://download.microsoft.com/download/1/6/B/16B06F60-3B20-4FF2-B699-5E9B7962F9AE/VSU_4/vcredist_x64.exe  -OutFile C:\Temp\vcredist_x64.exe
Start-Process -NoNewWindow -Wait -FilePath C:\Temp\vcredist_x64.exe -ArgumentList "/install", "/quiet", "/norestart"
Invoke-WebRequest -Uri https://aka.ms/vs/17/release/vc_redist.x64.exe  -OutFile C:\Temp\vc_redist.x64.exe
Start-Process -NoNewWindow -Wait -FilePath C:\Temp\vc_redist.x64.exe -ArgumentList "/install", "/quiet", "/norestart"

Warning

Make sure you exit the Administrator PowerShell before continuing with the next steps!

Background

These commands will create a temporary directory, download and install the Visual C++ Redistributable package for 64-bit Windows systems. The installer is retrieved from a Microsoft server and executed with parameters to ensure a seamless and unobtrusive installation process.

Installing Python 3.10

Open a new Windows Powershell prompt (no administrator mode) and run the following:

New-Item -ItemType Directory -Force -Path C:\Temp
Invoke-WebRequest -Uri https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe -OutFile C:\Temp\python-3.10.11-amd64.exe
Start-Process -NoNewWindow -Wait -FilePath C:\Temp\python-3.10.11-amd64.exe -ArgumentList "/passive", "InstallAllUsers=0", "Include_launcher=0", "Include_test=0"

Check that everything worked by running the following command:

&$env:UserProfile\AppData\Local\Programs\Python\Python310\python.exe --version

The command should return Python 3.10.11

Background

These commands will create a temporary directory, download the Python installer from a specific URL, and then execute the installer with specific installation options, all in a controlled and automated manner.

Installing iblrigv8

  1. From the Powershell command line, clone the iblrigv8 branch of iblrig to C:\iblrigv8:

    git clone -b iblrigv8 https://github.com/int-brain-lab/iblrig.git C:\iblrigv8

  2. Install a new virtual environment and update pip:

    &$env:UserProfile\AppData\Local\Programs\Python\Python310\python.exe -m venv C:\iblrigv8\venv
C:\iblrigv8\venv\scripts\python.exe -m pip install --upgrade pip wheel

  3. Install iblrig in editable mode:

    C:\iblrigv8\venv\scripts\Activate.ps1
cd C:\iblrigv8
pip install -e .

  4. Install Spinnaker SDK and PySpin:

    install_spinnaker
install_pyspin

  5. Install Bonsai in portable mode:

    cd C:\iblrigv8\Bonsai
powershell.exe .\install.ps1
cd ..

  6. Install additional tasks and extractors for personal projects (optional):

    git clone https://github.com/int-brain-lab/project_extraction.git C:\project_extraction
cd C:\project_extraction
pip install -e .

  7. Continue with the next section.

Configuration Instructions

Rig Configuration Files

Copy the template settings files:

cd C:\iblrigv8\settings
cp hardware_settings_template.yaml hardware_settings.yaml
cp iblrig_settings_template.yaml iblrig_settings.yaml
explorer C:\iblrigv8\settings

Update the two settings files using a text-editor:

  • iblrig_settings.yaml

  • hardware_settings.yaml

If the computer has been used with IBLRIG version 7 or earlier, the correct values can likely be found in C:\iblrig_params\ .iblrig_params.json.

Setting up ONE

Setup ONE to connect to https://alyx.internationalbrainlab.org, you will need your Alyx username and password.

See instructions for that here: https://int-brain-lab.github.io/iblenv/notebooks_external/one_quickstart.html

Make sure you can connect to Alyx !

Open a Python shell in the environment and connect to Alyx (you may have to setup ONE)

C:\iblrigv8\venv\scripts\Activate.ps1
ipython

Then at the IPython prompt

from one.api import ONE
one = ONE(username='your_username', password='your_password', base_url='https://alyx.internationalbrainlab.org')

You can check that everything went fine by running the test suite:

cd C:\iblrigv8
python -m unittest discover

The tests should pass to completion after around 40 seconds

Updating iblrigv8

To update iblrigv8 to the newest version:

C:\iblrigv8\venv\scripts\Activate.ps1
cd C:\iblrigv8
git pull
pip install --upgrade -e .

To update the additional tasks and extractors (see Installing iblrigv8, point 5):

cd C:\project_extraction
git pull

Tip

While usually quite snappy, upgrading the virtual environment in some instances can take longer than expected. Please be patient during the upgrade procedure.

Switch to specific iblrig version

Warning

Downgrading is not recommended and may not work as some releases break compatibility with earlier versions.

First fetch all available version tags and list them:

C:\iblrigv8\venv\scripts\Activate.ps1
cd C:\iblrigv8
git fetch --all --tags --prune
git tag --list '8.*'

Then switch to the desired version, for example 8.15.5:

git checkout tags/8.15.5
pip install --upgrade -e .