Raspberry Pi Setup and Configuration

Complete guide to setting up Raspberry Pi OS, LeLamp runtime, and testing all system components

Raspberry Pi Setup and Configuration

⏱️ Estimated time: 1–2 hours
🔧 Required tools: Computer, USB cable, SD Card Reader
📦 Required components: Raspberry Pi, SD Card, assembled LeLamp hardware

This guide covers the complete software setup process for your LeLamp, from operating system installation to final system testing.

Overview

The Raspberry Pi serves as the central control unit for LeLamp, managing:

• Servo motor control and coordination
• Audio input/output processing
• LED matrix control and effects
• Camera input and computer vision
• Network communication and remote control

Complete the hardware assembly before beginning software setup. Software configuration requires a fully assembled and connected LeLamp system.

Step 1: Operating System Installation

1. Download Raspberry Pi Imager

   Install the official Raspberry Pi Imager on your computer.

   Windows

   Download and run the Windows installer from the official website.

   macOS

   Download the macOS version or install via Homebrew:

   brew install --cask raspberry-pi-imager
   

   Linux

   Install via package manager or download AppImage:

   # Ubuntu/Debian
   sudo apt install rpi-imager
   
   # Arch Linux
   sudo pacman -S rpi-imager
   
2. Select Operating System

   Recommended OS: Raspberry Pi OS Lite (64-bit) - Debian Bookworm version

   We use the Lite version (no desktop environment) to maximize system resources for LeLamp operations and reduce boot time.

   In Raspberry Pi Imager:

   1. Click “Choose OS”
   2. Select “Raspberry Pi OS (other)”
   3. Choose “Raspberry Pi OS Lite (64-bit)”

   Verify you’ve selected the 64-bit Lite version for optimal performance.

3. Configure Advanced Settings

   Click the gear icon (⚙️) to configure essential settings:

   Network Configuration

   WiFi Settings:

   • SSID: Your WiFi network name
   • Password: Your WiFi password
   • Country: Select your country for proper WiFi regulations

   Use a stable 2.4GHz network for better range and compatibility with the Pi’s WiFi adapter.

   User Account

   User Configuration:

   • Username: Create a memorable username (e.g., “pi”, “lelamp”)
   • Password: Use a strong password for security
   • Remember these credentials - you’ll need them for SSH access

   Write down your username and password. You’ll need these for all future access to your Pi.

   System Settings

   Hostname: Set a unique name (e.g., “lelamp-pi”, “my-lelamp”)

   SSH Configuration:

   • ✅ Enable SSH (required for remote access)
   • Choose password authentication or SSH keys

   Locale Settings:

   • Set timezone for your location
   • Configure keyboard layout if needed
4. Flash the SD Card

   1. Insert SD card into your computer
   2. Select storage device in Pi Imager
   3. Click “Write” to begin flashing process
   4. Wait for completion (typically 5-10 minutes)
   5. Safely eject SD card when finished

   The flashing process will erase all data on the SD card. Ensure you’ve backed up any important files.

Step 2: Initial Pi Boot and Connection

1. First Boot

   1. Insert SD card into Raspberry Pi
   2. Connect power supply (5V 2A USB-C)
   3. Wait for boot process (2-3 minutes for first boot)
   4. Observe LED indicators - steady red power, blinking green activity

   The first boot takes longer as the Pi expands the filesystem and completes initial setup.

2. Establish SSH Connection

   Find and connect to your Raspberry Pi:

   Using Hostname

   ssh your_username@your_hostname.local
   

   Example:

   ssh [e-mail]
   

   Using IP Address

   If hostname doesn’t work, find the IP address:

   1. Check router admin panel for connected devices
   2. Use network scanner: nmap -sn 192.168.1.0/24
   3. Connect using IP: ssh [e-mail]

   Troubleshooting Connection

   Common issues:

   • “Host not found”: Try IP address instead of hostname
   • “Connection refused”: Verify SSH is enabled in Pi settings
   • “Permission denied”: Check username and password
   • Network issues: Verify Pi and computer are on same network

   Successful SSH connection shows the Raspberry Pi command prompt.

Step 3: LeLamp Runtime Installation

1. Update System Packages

   Update the Pi’s software packages to the latest versions:

   sudo apt update && sudo apt upgrade -y
   

   This process may take 10-15 minutes depending on the number of updates available.

2. Install System Dependencies

   Install required system packages for audio processing:

   sudo apt install -y portaudio19-dev git curl
   

   These packages provide:

   • portaudio19-dev: Audio input/output support
   • git: Version control for downloading LeLamp runtime
   • curl: Network tools for downloading additional software
3. Clone LeLamp Runtime Repository

   Download the LeLamp runtime software:

   git clone https://github.com/humancomputerlab/lelamp_runtime.git
   cd lelamp_runtime
   

   Verify the download by listing directory contents: ls -la

4. Install UV Package Manager

   Install UV for Python dependency management:

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

   Reload your shell to use UV:

   source ~/.bashrc
   # or restart your SSH session
   

   UV provides faster and more reliable Python package management compared to pip.

5. Install LeLamp Runtime

   Install all Python dependencies and hardware support:

   uv sync --extra hardware
   

   This installation process takes 15-30 minutes as it compiles several packages for the Pi’s ARM architecture.

   The --extra hardware flag includes additional packages needed for:

   • GPIO control and hardware interfaces
   • Camera and sensor support
   • Real-time audio processing
   • LED matrix control libraries

Step 4: Audio System Configuration

Configure the ReSpeaker Hat for microphone input and speaker output.

1. Install ReSpeaker Device Tree

   Download and install the device tree overlay for ReSpeaker 2-Mics Pi HAT:

   # Download device tree source
   curl https://raw.githubusercontent.com/Seeed-Studio/seeed-linux-dtoverlays/refs/heads/master/overlays/rpi/respeaker-2mic-v2_0-overlay.dts -o respeaker-2mic-v2_0-overlay.dts
   
   # Compile device tree overlay
   dtc -I dts respeaker-2mic-v2_0-overlay.dts -o respeaker-2mic-v2_0-overlay.dtbo
   
   # Install overlay temporarily
   sudo dtoverlay respeaker-2mic-v2_0-overlay.dtbo
   
   # Install overlay permanently
   sudo cp respeaker-2mic-v2_0-overlay.dtbo /boot/firmware/overlays
   
2. Configure Boot Settings

   Add ReSpeaker support to boot configuration:

   sudo tee -a /boot/firmware/config.txt >/dev/null <<'EOF'
   dtoverlay=respeaker-2mic-v2_0-overlay
   dtoverlay=i2s-mmap
   EOF
   

   This configuration:

   • Enables the ReSpeaker device tree overlay
   • Activates I2S memory mapping for better audio performance
3. Configure Audio System

   Set up ALSA (Advanced Linux Sound Architecture) for the ReSpeaker:

   sudo tee /etc/asound.conf > /dev/null <<'EOF'
   # Default capture & playback device = Seeed 2-Mic
   pcm.!default {
       type plug
       slave {
           pcm "hw:3,0"      # input/output device (Seeed 2-Mic)
       }
   }
   
   ctl.!default {
       type hw
       card 3
   }
   EOF
   

   The card number (3) may vary depending on your Pi model and other connected devices. We’ll verify this in the testing step.

4. Reboot and Verify Audio

   Restart the Pi to apply audio configuration:

   sudo reboot
   

   After reboot, reconnect via SSH and verify audio devices:

   aplay -l
   

   Expected output should include:

   card 2: seeed2micvoicec [seeed2micvoicec], device 0: 1f000a4000.i2s-tlv320aic3x-hifi tlv320aic3x-hifi-0 [1f000a4000.i2s-tlv320aic3x-hifi tlv320aic3x-hifi-0]
     Subdevices: 1/1
     Subdevice #0: subdevice #0
   

   ReSpeaker device appears in audio device list with correct driver.

5. Configure Audio Levels

   Set appropriate audio levels using ALSA mixer:

   alsamixer
   

   In alsamixer:

   1. Press F6 to select audio device
   2. Choose “seeed2micvoicec” from the list
   3. Navigate to “Line”, “Line DAC”, and “PCM” controls
   4. Unmute channels by pressing ‘M’ (if showing “MM”)
   5. Set volume levels to 100% initially
   6. Press Esc to exit

   Audio channels may be muted by default. Look for “MM” indicators and press ‘M’ to unmute.

Step 5: System Component Testing

Test each LeLamp subsystem to verify proper installation and configuration.

1. Test LED Matrix

   Verify LED matrix control and effects:

   sudo uv run -m lelamp.test.test_rgb
   

   Expected behavior:

   • LEDs should light up in sequence
   • Multiple colors and patterns displayed
   • Smooth transitions between effects

   If UV command not found as root

   Find UV path and use full path:

   which uv
   # Output example: /home/pi/.local/bin/uv
   
   sudo /home/pi/.local/bin/uv run -m lelamp.test.test_rgb
   

   Add UV to sudo PATH (optional)

   For convenience, add UV to sudo’s secure path:

   sudo visudo
   

   Add your user’s .local/bin to the secure_path line:

   Defaults secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/pi/.local/bin"
   

   Be careful when editing sudoers file. Syntax errors can lock you out of sudo access.

2. Test Audio System

   Verify microphone input and speaker output:

   uv run -m lelamp.test.test_audio
   

   Expected behavior:

   • Test tone plays through speaker
   • Microphone records and plays back audio
   • No distortion or audio artifacts

   Audio Test Success

   • Clear audio output from speaker
   • Microphone picks up voice/sounds
   • Playback matches recorded audio
   • No crackling or distortion

   Troubleshooting Audio

   No audio output:

   • Check speaker connections
   • Verify audio levels in alsamixer
   • Test with different audio card number

   No microphone input:

   • Check ReSpeaker Hat connection
   • Verify device tree overlay loaded
   • Test microphone gain settings
3. Test Servo Communication

   Verify servo driver connection and motor control:

   1. Connect servo driver to Pi via USB

   2. Find servo port:

      uv run lerobot-find-port
      

   3. Test servo communication:

      uv run -m lelamp.test.test_motors --id your_lamp_name --port /dev/ttyACM0
      

   Replace your_lamp_name with the name you used during servo setup, and /dev/ttyACM0 with the actual port found.

   Expected behavior:

   • All 5 servos respond to commands
   • Smooth movement through range of motion
   • No communication errors or timeouts
   • Position feedback matches commanded positions
4. Test Camera (Optional)

   If using Pi Camera, test camera functionality:

   # Test camera capture
   libcamera-hello --timeout 2000
   
   # Capture test image
   libcamera-still -o test_image.jpg
   

   Expected behavior:

   • Camera preview displays for 2 seconds
   • Test image captured successfully
   • Image quality appropriate for intended use

Step 6: Network Configuration Optimization

1. Configure Static IP (Optional)

   For consistent network access, configure a static IP address:

   sudo nano /etc/dhcpcd.conf
   

   Add configuration for your network:

   interface wlan0
   static ip_address=192.168.1.100/24
   static routers=192.168.1.1
   static domain_name_servers=192.168.1.1 8.8.8.8
   

   Adjust IP addresses to match your network configuration. Ensure the chosen IP doesn’t conflict with other devices.

2. Enable SSH Key Authentication (Recommended)

   For improved security, set up SSH key authentication:

   On your computer:

   # Generate SSH key pair (if you don't have one)
   ssh-keygen -t rsa -b 4096 -C "[e-mail]"
   
   # Copy public key to Pi
   ssh-copy-id [e-mail]
   

   Test key-based login:

   ssh [e-mail]
   # Should connect without password prompt
   

System Performance Optimization

1. Configure GPU Memory Split

   Optimize memory allocation for headless operation:

   sudo raspi-config
   

   Navigate to: Advanced Options → Memory Split Set GPU memory to 16MB (minimum for headless operation)

2. Disable Unnecessary Services

   Disable services not needed for LeLamp operation:

   # Disable Bluetooth (if not needed)
   sudo systemctl disable bluetooth
   
   # Disable WiFi power management
   sudo iwconfig wlan0 power off
   
   # Add to /etc/rc.local for persistence
   echo 'iwconfig wlan0 power off' | sudo tee -a /etc/rc.local
   
3. Configure Automatic Startup (Optional)

   Set up LeLamp to start automatically on boot:

   # Create systemd service file
   sudo tee /etc/systemd/system/lelamp.service > /dev/null <<'EOF'
   [Unit]
   Description=LeLamp Service
   After=network.target
   
   [Service]
   Type=simple
   User=pi
   WorkingDirectory=/home/pi/lelamp_runtime
   ExecStart=/home/pi/.local/bin/uv run -m lelamp.main --id your_lamp_name
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   # Enable service
   sudo systemctl enable lelamp.service
   

   Replace your_lamp_name with your actual lamp identifier and adjust paths as needed.

Final System Verification

1. Complete System Test

   Run comprehensive system test to verify all components:

   # Test all subsystems
   sudo uv run -m lelamp.test.test_all_systems --id your_lamp_name --port /dev/ttyACM0
   

   This test verifies:

   • Servo motor control and coordination
   • LED matrix effects and control
   • Audio input/output functionality
   • System performance and stability
2. Performance Monitoring

   Monitor system performance during operation:

   # Check CPU and memory usage
   htop
   
   # Monitor system temperature
   vcgencmd measure_temp
   
   # Check system logs for errors
   sudo journalctl -f
   

   Healthy system indicators:

   • CPU usage < 50% during normal operation
   • Temperature < 70°C under load
   • No error messages in system logs
   • Stable network connectivity

Setup Completion Checklist

Operating System

• Raspberry Pi OS Lite installed and configured
• SSH access working reliably
• Network connectivity stable
• System packages updated to latest versions
• User account properly configured

LeLamp Runtime

• Runtime repository cloned successfully
• UV package manager installed and working
• All Python dependencies installed
• Hardware support packages configured
• Runtime tests pass without errors

Hardware Integration

• ReSpeaker Hat configured and working
• Audio input/output tested successfully
• LED matrix control functional
• Servo communication established
• Camera working (if applicable)

System Optimization

• Performance optimizations applied
• Unnecessary services disabled
• Memory allocation optimized
• Network configuration stable
• System monitoring tools configured

What You Should Have

At this stage, you should have:

• Fully configured Raspberry Pi running optimized LeLamp software
• Working audio system with microphone input and speaker output
• Functional LED matrix with programmable effects
• Reliable servo communication for motor control
• Stable network connectivity for remote access and control
• Comprehensive testing confirming all subsystems work correctly

Raspberry Pi Setup Complete! Your LeLamp is now ready for calibration and operation.

---

Previous: Assembly Guide | Next: Lamp Control

Document your configuration settings and test results. This information will be valuable for troubleshooting and future maintenance.