Installation under Linux (experimental) - eulerlab/QDSpy GitHub Wiki

Installation on a Raspberry Pi 5

The following procedure was tested on a Raspberry Pi 4B (4 GB) and 5 (8 GB) running 64-bit Raspbian (bookworm). Note that the last adjustments of these instructions were based on an installation on a Raspberry Pi 5. For the installation, we assume that:

the hostname is rpi5qdspy,
with a user qdspy and the password being Rabbit.
SSH and I2C must be enabled; bluetooth should be off if not needed.
The system is up to date (sudo apt update, sudo apt dist-upgrade).
Make sure that the graphics card runs at 60 Hz refresh rate.

NOTE: When remote-connecting via SSH and if a warning appears ( WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!), then remove all keys belonging to that host with ssh-keygen -R raspberrypi.

Installation using the package manager `uv` (recommended)

Install the package manager uv; for details, see here:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Clone the experimental branch of QDSpy:

git clone -b experimental https://github.com/eulerlab/QDSpy.git

Install required packages:

sudo apt install python3-pyqt6
sudo apt-get install libatlas-base-dev
sudo apt-get install mesa-utils
sudo apt install libhidapi-hidraw0
sudo apt install libhidapi-libusb0

Make sure that the QDSpy directory is known to the system by editing .bashrc:

sudo nano ~/.bashrc

Add the following lines at the end:

PATH="${PATH}:/home/qdspy/QDSpy"
export PATH
PYTHONPATH="${PYTHONPATH}:/home/qdspy/QDSpy"
export PYTHONPATH
export DISPLAY=:0

... and reboot.

Create a virtual environment and make PyQt6 available:
```
cd QDSpy
uv venv
uv pip install PyQt6 --no-build
```
Finish installation by running QDSpy via uv for the first time. The same command will also be used to run QDSpy later.
```
uv run QDSpy_GUI_main.py
```

"Conventional" installation

Start by creating a new Python environment in the home directory and activate the environment:
```
cd ~
python -m venv qdspy
source qdspy/bin/activate
```

Make sure that pip is up to date and clone the experimental branch of QDSpy:

pip install --upgrade pip
git clone -b experimental https://github.com/eulerlab/QDSpy.git

Install required packages:

sudo apt install python3-pyqt6
sudo apt-get install libatlas-base-dev
pip install --upgrade numpy
sudo apt-get install mesa-utils
sudo apt install libhidapi-hidraw0
sudo apt install libhidapi-libusb0
pip install hidapi hid
pip install pyglet==1.5.29
pip install moviepy 
pip install psutil pyserial
pip install pyopengl
pip install pygame
pip install lgpio
pip install gpiozero
pip install colorama
pip install paho-mqtt

Make sure that the QDSpy directory is known to the system by editing .bashrc:

sudo nano ~/.bashrc

Add the following lines at the end:

PATH="${PATH}:/home/qdspy/QDSpy"
export PATH
PYTHONPATH="${PYTHONPATH}:/home/qdspy/QDSpy"
export PYTHONPATH
export DISPLAY=:0

... and reboot.

Test the installation

After the reboot, re-activate the Python environment and change into the QDSpy folder:
```
source qdspy/bin/activate
cd QDSpy
export DISPLAY=:0
```
The export DISPLAY=:0 is only needed if you are in a remote SSH shell and if the command is not already included in the .bashrc file (see above).
Start a test stimulus:
```
python Stimuli/noise_Colored1.py
```
If you get error messages, some parameters may not have been correctly set yet (see next point).

After the installation

Change some settings from the default in the respective sections of the configuration file (QDSpy.ini). A fresh configuration file is always generated when starting QDSpy, if no QDSpy.ini is found:

To direct the stimulus window as fullscreen to display #0:
```
[Stage]
int_screen_width_pix = 0
int_screen_index = 0
```
To enable the use of movies, which are internally treated as textures:
```
[Tweaking]
bool_use3dtextures = 1
```
To disable sound, which is not yet supported:
```
[Sound]
bool_use_sound = False
```

To use digital I/O:

[Timing]
str_digitalio_board_type = RaspberryPi

Trouble shooting and current issues

For a detailed list of open and solved issues, see release notes.

If you need to uninstall uv and its data (e.g., for a fresh start), follow the instructions here.
If import PyQt6 fails, try to install it using pip install PyQt6 --only-binary :all: from within the virtual environment.
OpenGL support for SwapIntervalEXT() not present? So far not an issue?

Notes for developers

Use remote SFTP to work on the RPi from Visual Studio Code

Ìnstructions on the RPi side were based on this:

sudo apt install vsftpd
sudo nano /etc/vsftpd.conf

Change the configuration settings to:

anonymous_enable=NO
local_enable=YES
write_enable=YES
local_umask=022
chroot_local_user=YES
user_sub_token=$USER
local_root=/home/$USER

Start FTP server with:
```
sudo service vsftpd restart
```
In Visual Studio Code, install the Remote FS extension and add the following configuration. Make sure that you use the IP address of your RPi and change "username" and "rootPath" if your installation is different from what is described above.
```
"remotefs.remote": {
   "dev": {
   "scheme": "sftp",
   "host": "172.20.10.2",
   "username": "qdspy",
   "rootPath": "/home/qdspy/QDSpy"
   }
}
```

GitHub

If the repository was cloned using HTTPS, it is recommended to use GitHub CLI for managing credentials. To install gh, go here. Then authenticate to Git using gh auth login and follow the instructions.

To contribute changes:

git config --global user.name "user_name"
git config --global user.email "email_address"
git add .
git commit -m "what has changed"
git push origin experimental