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

Download Raspberry Pi Imager

Install the official Raspberry Pi Imager on your computer.

Windows
macOS
Linux

Download and run the Windows installer from the official website.

Download the macOS version or install via Homebrew:

brew install --cask raspberry-pi-imager

Install via package manager or download AppImage:

# Ubuntu/Debian
sudo apt install rpi-imager

# Arch Linux
sudo pacman -S rpi-imager

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:

Click “Choose OS”
Select “Raspberry Pi OS (other)”
Choose “Raspberry Pi OS Lite (64-bit)”

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

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

Flash the SD Card

Insert SD card into your computer
Select storage device in Pi Imager
Click “Write” to begin flashing process
Wait for completion (typically 5-10 minutes)
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

First Boot

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

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

Establish SSH Connection

Find and connect to your Raspberry Pi:

Using Hostname
Using IP Address
Troubleshooting Connection

ssh your_username@your_hostname.local

Example:

ssh pi@lelamp-pi.local

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

Check router admin panel for connected devices
Use network scanner: nmap -sn 192.168.1.0/24
Connect using IP: ssh pi@192.168.1.xxx

Successful SSH connection shows the Raspberry Pi command prompt.

Step 3: LeLamp Runtime Installation

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.

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

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

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.

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.

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

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

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.

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.

Configure Audio Levels

Set appropriate audio levels using ALSA mixer:

alsamixer

In alsamixer:

Press F6 to select audio device
Choose “seeed2micvoicec” from the list
Navigate to “Line”, “Line DAC”, and “PCM” controls
Unmute channels by pressing ‘M’ (if showing “MM”)
Set volume levels to 100% initially
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.

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.

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
Troubleshooting Audio

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

Test Servo Communication

Verify servo driver connection and motor control:

Connect servo driver to Pi via USB
Find servo port:
```
uv run lerobot-find-port
```

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

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

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.

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 "your_email@example.com"

# Copy public key to Pi
ssh-copy-id pi@lelamp-pi.local

Test key-based login:

ssh pi@lelamp-pi.local
# Should connect without password prompt

System Performance Optimization

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)

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

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

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

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.

Getting Started

Hardware Setup

Operation

Raspberry Pi Setup and Configuration

Raspberry Pi Setup and Configuration

Overview

Step 1: Operating System Installation

Step 2: Initial Pi Boot and Connection

Step 3: LeLamp Runtime Installation

Step 4: Audio System Configuration

Step 5: System Component Testing

Step 6: Network Configuration Optimization

System Performance Optimization

Final System Verification

Setup Completion Checklist

What You Should Have

Getting Started

Hardware Setup

Operation

​Raspberry Pi Setup and Configuration

​Overview

​Step 1: Operating System Installation

​Step 2: Initial Pi Boot and Connection

​Step 3: LeLamp Runtime Installation

​Step 4: Audio System Configuration

​Step 5: System Component Testing

​Step 6: Network Configuration Optimization

​System Performance Optimization

​Final System Verification

​Setup Completion Checklist

​What You Should Have

Raspberry Pi Setup and Configuration

Overview

Step 1: Operating System Installation

Step 2: Initial Pi Boot and Connection

Step 3: LeLamp Runtime Installation

Step 4: Audio System Configuration

Step 5: System Component Testing

Step 6: Network Configuration Optimization

System Performance Optimization

Final System Verification

Setup Completion Checklist

What You Should Have