Skip to content

Raspberry Pi Setup Guide

This guide provides essential commands for setting up Ethopy on a Raspberry Pi (RP) device.

Prerequisites

  • Raspberry Pi image Follow the instructions in the Raspberry Pi documentation to install the image and set up your Raspberry Pi.

  • SSH Setup Enable the SSH service to allow remote access to your Raspberry Pi via the terminal:

1
2
sudo systemctl enable ssh  # Enables SSH to start automatically at boot
sudo systemctl start ssh   # Starts SSH service immediately

EthoPy setup

Step 1: Ethopy Installation

Once your Raspberry Pi is set up, you can connect to it from your computer's terminal based on Raspberry Pi documentation.

  1. Verify python version: 
    1
    python --version

EthoPy requires Python >=3.8, < 3.12

  1. Setting Up a Virtual Environment

1
2
conda create --name myenv python=3.x
conda activate myenv
More details

1
2
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
More details

1
2
uv venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
More details

Once activated, proceed with installation.

  1. Install Ethopy:

    1
    pip install ethopy

  2. Create configuration file at ~/.ethopy/local_conf.json: 

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    {
    "dj_local_conf": {
        "database.host": "YOUR DATABASE",
        "database.user": "USERNAME",
        "database.password": "PASSWORD",
        "database.port": "PORT",
        "database.reconnect": true,
        "database.enable_python_native_blobs": true
    },
    "source_path": "LOCAL_RECORDINGS_DIRECTORY",
    "target_path": "TARGET_RECORDINGS_DIRECTORY"
}

For detailed desciption of configuration files, see Local configuration.

Step 2: Database connection

1
ethopy-db-connection     # Tests database connection to verify setup

Step 3: GPIO Hardware Support

Enable pigpio daemon for GPIO control:

1
2
sudo systemctl enable pigpiod.service  # Enables pigpio daemon to start at boot
sudo systemctl start pigpiod.service   # Starts pigpio daemon for immediate GPIO access

Install GPIO libraries:

1
2
pip install pigpio              # Python library for pigpio daemon communication
sudo apt-get install python3-rpi.gpio  # Alternative GPIO library for Raspberry Pi

Step 4: Display Configuration

Configure display settings for GUI applications via SSH:

1
2
3
export DISPLAY=:0                           # Sets display to primary screen
sed -i -e '$aexport DISPLAY=:0' ~/.profile  # Persists DISPLAY setting in profile
sed -i -e '$axhost +  > /dev/null' ~/.profile  # Allows X11 forwarding access

Step 5: Screen Blanking Disable

To prevent screen from turning off, run raspi-config:

1
sudo raspi-config

Navigate to "Display Options" → "Screen Blanking" → Set to "No"

Step 6: Run your first experiment

1
ethopy --task-path grating_test.py --log-console

Troubleshooting

Common Issues

  1. Display Issues

  2. Ensure DISPLAY is set correctly in ~/.profile

  3. Check X server is running

  4. Verify permissions with xhost +

  5. GPIO Access

  6. Verify pigpiod service is running: systemctl status pigpiod

  7. Check user permissions for GPIO access

  8. Database Connection

  9. Test connection: ethopy-db-connection

  10. Check network connectivity to database server
  11. Verify credentials in local_conf.json

Where to Go Next

Now that you have a basic understanding of EthoPy:

  1. Creating Custom Components
  2. How to create a Task
  3. Explore the Plugin System to extend functionality
  4. Dive deeper into Local Configuration for advanced settings
  5. Understand setup configuration index
  6. Learn more about Database Setup
  7. Study the API Reference for detailed documentation
  8. Check Contributing if you want to help improve EthoPy