Manual Software Installation

You can download a ready-to-use disk image containing the operating system (Raspberry Pi OS) along with all necessary libraries and Python code pre-installed here.

Follow the instructions on this page if you prefer a manual installation. The process can be challenging, so proceed only if you have a basic understanding of Linux distributions and are comfortable using the terminal.

What You Need

  • Raspberry Pi 5 - 8GB

  • Fan

  • Micro SD 128GB

  • Keyboard

  • Mouse

  • Screen

  • Micro HDMI to HDMI cable

  • Power supply for Raspberry Pi

  • 2 Raspberry Pi Camera Module 3 Wide Noir

  • Ethernet cable (optional)

  • Raspberry Pi Dac Pro (optional)

  • 2 servo motors

  • RFID sensor

  • Weight sensor

  • Temperature sensor

Launch Raspberry Pi OS for the First Time

  1. Connect a keyboard, mouse, and screen to the Raspberry Pi.

  2. Connect the fan.

  3. Connect the Ethernet cable if you are going to use an Ethernet connection.

  4. If your SD card has the OS preinstalled, jump to step 4.

  5. If your SD card is empty, follow these instructions to download the OS and copy it to the SD: Raspberry Pi OS. Don’t customize it, we will do it later.

  6. Insert the SD card and start the Raspberry Pi.

  7. Select your country and keyboard language and choose English as the general language.

  8. Type pi as the username and choose the password you want.

  9. Select your Wi-Fi or Ethernet connection.

  10. Choose your preferred web browser (Chromium).

  11. Select “Yes” when asked to update software (if you have your internet connection ready).

Updating the System

  1. Make sure you have internet connection and then update the software. Detailed instructions.

sudo apt update
sudo apt full-upgrade

Installing Needed Libraries

  1. The OS comes with python 3.13 pre-installed.

  2. Install OpenCV (the library used for video processing).

sudo apt install -y python3-opencv
sudo apt install -y opencv-data

  1. Install sound library.

sudo apt-get install libportaudio2

  1. Install PyQT5 multimedia

sudo apt install python-pyqt5
sudo apt install python3-pyqt5.qtmultimedia
sudo apt install libqt5multimedia5-plugins

  1. Install evdev

sudo apt install python3-evdev

  1. Install evtest

sudo apt install evtest

  1. Install VS Code:

sudo apt install code

Creating a Python Environment and Installing pip Libraries

  1. Create a .env environment that includes all the packages installed in the global Python environment:

python -m venv --system-site-packages ~/.env

  1. Activate it:

source ~/.env/bin/activate

  1. Install the required libraries with pip.

pip install python-dateutil
pip install setuptools_scm
pip install sounddevice
pip install python-telegram-bot
pip install scipy
pip install gpiod
pip install fire
pip install pyserial
pip install pandas
pip install seaborn
pip install calplot
pip install PCA9685-smbus2
pip install pi5neo
pip install pyarrow
pip install ahrs
pip install bleak

Screen Settings

  1. Run the raspi-config.

sudo raspi-config

  1. Go to Advanced Options and select X11 (instead of Wayland).

Then, you need to configure the system to recognize a screen even if none is physically connected, so the software renders properly when accessed remotely. If you want to use an additional screen to present stimuli in the operant box, you need to set the system to work with two screens.

  1. Modify the file: /boot/firmware/cmdline.txt

sudo nano /boot/firmware/cmdline.txt

  1. Add the following text: vc4.force_hotplug=1 video=HDMI-A-1:1600x900@60D if you are using only one screen, or vc4.force_hotplug=3 video=HDMI-A-1:1600x900@60D video=HDMI-A-2:1280x720@60D if you are using two screens.

Explanation of values: (=1 makes the system operate as if a screen is connected to HDMI 1). (=2 makes the system operate as if a screen is connected to HDMI 2). (=3 makes the system operate as if screens are connected to both HDMI 1 and HDMI 2). HDMI-A-1 and HDMI-A-2 are used to specify the desired resolution.

  1. After every reboot, the system will recognize two screens at the specified resolution. You can change the screen resolution (or resolutions) at any time in: Preferences -> Screen Configuration.

  2. Reboot the system to use X11.

Changing Preferences

  1. Enable auto-login by clicking on Preferences -> Control Centre -> System -> Auto login.

  2. Enable the following interfaces: SPI, I2C, Serial Port. The rest of the options should be disabled. By clicking on Preferences -> Control Centre -> Interfaces .

  3. Set Screen Blanking OFF and On-screen keyboard DISABLED by clicking on Preferences -> Control Centre -> Display.

  4. Add CPU monitors to the toolbar: Right-click on the toolbar, select Add/Remove Panel Items, and click Add. Select CPU Temperature Monitor and CPU Usage monitor.

Accessing UART Pin for Communication

To allow the use of the UART Pin for communication with the sensors you need to edit the file /boot/firmware/config.txt:

  1. Edit with sudo nano /boot/firmware/config.txt to include the following:

[all]
enable_uart=1

Udev Rules for Consistent USB Device Naming

When you connect your behavioral controller (e.g., Bpod, Arduino, or compatible boards) to the Raspberry Pi, the operating system assigns it a device path in /dev/. Depending on the specific serial chip used by your board, it is typically named ttyACM0 or ttyUSB0.

However, this designation can change dynamically (ttyACM1, ttyUSB1, etc.) upon reboot or if other USB peripherals are connected. To guarantee that the Training Village software can always locate the hardware, you can create a persistent symbolic link that maps the physical USB port directly to a static name.

  1. Navigate to the system directory where custom hardware rules are stored:

cd /etc/udev/rules.d

  1. Create a new rule file named 99-usb.rules:

sudo nano 99-usb.rules

  1. Add the following line to the file. By targeting the serial tty subsystem instead of a specific naming pattern, this rule seamlessly captures both ttyACM* and ttyUSB* devices, mapping whichever device is plugged into that exact physical port to the alias controller:

SUBSYSTEM=="tty", KERNELS=="1-1:1.0", SYMLINK+="controller"

Note: The USB port identifier (KERNELS==“1-1:1.0”) may vary depending on the physical USB port you are using. For reference, the 1-1:1.0 port on the Raspberry Pi is usually the bottom USB port next to the Ethernet connection. To confirm the exact port identifier, you can use the command dmesg after connecting the device.

  1. Activate the new rule by triggering the Udev process:

sudo udevadm trigger

Now, whenever your Bpod or Arduino controller is plugged into that designated USB port, the system will automatically expose it at /dev/controller, completely bypassing any dynamic or unpredictable ttyACM or ttyUSB reassignments.

Grant Permissions for Maximum Process Priority

To allow your Python script to run with the highest priority, you need to grant special permissions to the Python interpreter. Replace python3.13 with the actual Python version you are using if it’s different.

sudo setcap cap_sys_nice=eip /usr/bin/python3.13

This command gives Python permission to change its own scheduling priority without needing to run as root.

Adjust Memory and Disk Cache Behavior

  1. Open the system configuration file:

sudo nano /etc/sysctl.conf

  1. Add the following lines at the end of the file, then save and exit:

vm.swappiness=10
vm.vfs_cache_pressure=50

These settings prioritize the use of RAM over disk cache whenever possible, in order to achieve better performance.

  1. Apply the changes immediately (without rebooting):

sudo sysctl -p

Grant access to input devices

The touchscreen is read via evdev, which requires access to /dev/input/ devices. Add your user to the input group:

sudo usermod -aG input $USER

Log out of the desktop session and log back in for the change to take effect (a full reboot also works, but is not necessary). You can verify it with groups, which should include input in the output.

Optional: Increase SPI buffer size for LED strip

  1. Modify the file: /boot/firmware/cmdline.txt

sudo nano /boot/firmware/cmdline.txt

  1. Add the following text on the same line (e.g. after the vc4 edit done previously): spidev.bufsiz=32768.

Install Training Village

  1. Make sure you are in .env environment.

source ~/.env/bin/activate

  1. Go to your /home/pi/ directory.

cd

  1. Clone the repository.

git clone https://github.com/BrainCircuitsBehaviorLab/village.git

  1. Navigate to folder village.

cd village

  1. Install the repository.

pip install -e .

  1. You’re ready to start the system by simply running the main.py file.

python /home/pi/village/village/main.py

Create an Alias and Run the Training Village

  1. Edit the .bashrc file:

nano ~/.bashrc

  1. Add the following line to create an alias:

alias village='/home/pi/.env/bin/python /home/pi/village/village/main.py'

  1. Reload the .bahsrc:

source ~/.bashrc

  1. Run Training village:

village