Installation under Linux (experimental)

• Installation on a Raspberry Pi 5
• Trouble shooting and ccurrent issues
• Notes for developers

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)

1. Install the package manager uv; for details, see here:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the experimental branch of QDSpy:

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

3. 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

4. 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.

5. Create a virtual environment and make PyQt6 available:

   cd QDSpy
   uv venv
   uv pip install PyQt6 --no-build

6. 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

1. Start by creating a new Python environment in the home directory and activate the environment:

   cd ~
   python -m venv qdspy
   source qdspy/bin/activate

2. 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

3. 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

4. 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.

5. 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

1. Ì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

2. Start FTP server with:

   sudo service vsftpd restart

3. 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