> ## Documentation Index
> Fetch the complete documentation index at: https://humancomputerlab.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

> [!NOTE]
>
> **⏱️ 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

> [!WARNING]
>
> 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](https://www.raspberrypi.com/software/) on your computer.

> [tab] Windows
>
> Download and run the Windows installer from the official website.

> [tab] macOS
>
> Download the macOS version or install via Homebrew:
>
> ```bash theme={null}
> brew install --cask raspberry-pi-imager
> ```

> [tab] Linux
>
> Install via package manager or download AppImage:
>
> ```bash theme={null}
> # 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

> [!NOTE]
>
> 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)"**

> [!TIP]
>
> Verify you've selected the 64-bit Lite version for optimal performance.

**3. Configure Advanced Settings**

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

> [accordion] Network Configuration
>
> **WiFi Settings**:
>
> * **SSID**: Your WiFi network name
>
> * **Password**: Your WiFi password
>
> * **Country**: Select your country for proper WiFi regulations
>
> > [!TIP]
> >
> > Use a stable 2.4GHz network for better range and compatibility with the Pi's WiFi adapter.

> [accordion] 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
>
> > [!WARNING]
> >
> > Write down your username and password. You'll need these for all future access to your Pi.

> [accordion] 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

> [!NOTE]
>
> 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

> [!NOTE]
>
> 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:

> [tab] Using Hostname
>
> ```bash theme={null}
> ssh your_username@your_hostname.local
> ```
>
> Example:
>
> ```bash theme={null}
> ssh pi@lelamp-pi.local
> ```

> [tab] 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 pi@192.168.1.xxx`

> [tab] 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

> [!TIP]
>
> 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:

```bash theme={null}
sudo apt update && sudo apt upgrade -y
```

> [!NOTE]
>
> 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:

```bash theme={null}
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:

```bash theme={null}
git clone https://github.com/humancomputerlab/lelamp_runtime.git
cd lelamp_runtime
```

> [!TIP]
>
> Verify the download by listing directory contents: `ls -la`

**4. Install UV Package Manager**

Install UV for Python dependency management:

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Reload your shell** to use UV:

```bash theme={null}
source ~/.bashrc
# or restart your SSH session
```

> [!TIP]
>
> UV provides faster and more reliable Python package management compared to pip.

**5. Install LeLamp Runtime**

Install all Python dependencies and hardware support:

```bash theme={null}
uv sync --extra hardware
```

> [!WARNING]
>
> 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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
```

> [!NOTE]
>
> 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:

```bash theme={null}
sudo reboot
```

After reboot, reconnect via SSH and verify audio devices:

```bash theme={null}
aplay -l
```

**Expected output should include**:

```bash theme={null}
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
```

> [!TIP]
>
> ReSpeaker device appears in audio device list with correct driver.

**5. Configure Audio Levels**

Set appropriate audio levels using ALSA mixer:

```bash theme={null}
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

> [!TIP]
>
> 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:

```bash theme={null}
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

> [accordion] If UV command not found as root
>
> Find UV path and use full path:
>
> ```bash theme={null}
> which uv
> # Output example: /home/pi/.local/bin/uv
>
> sudo /home/pi/.local/bin/uv run -m lelamp.test.test_rgb
> ```

> [accordion] Add UV to sudo PATH (optional)
>
> For convenience, add UV to sudo's secure path:
>
> ```bash theme={null}
> sudo visudo
> ```
>
> Add your user's .local/bin to the secure\_path line:
>
> ```bash theme={null}
> Defaults secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/pi/.local/bin"
> ```
>
> > [!WARNING]
> >
> > 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:

```bash theme={null}
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

> [tab] Audio Test Success
>
> * Clear audio output from speaker
> * Microphone picks up voice/sounds
> * Playback matches recorded audio
> * No crackling or distortion

> [tab] 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**:
   ```bash theme={null}
   uv run lerobot-find-port
   ```

3. **Test servo communication**:
   ```bash theme={null}
   uv run -m lelamp.test.test_motors --id your_lamp_name --port /dev/ttyACM0
   ```

> [!NOTE]
>
> 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:

```bash theme={null}
# 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:

```bash theme={null}
sudo nano /etc/dhcpcd.conf
```

Add configuration for your network:

```bash theme={null}
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
```

> [!NOTE]
>
> 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**:

```bash theme={null}
# 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**:

```bash theme={null}
ssh pi@lelamp-pi.local
# Should connect without password prompt
```

## System Performance Optimization

**1. Configure GPU Memory Split**

Optimize memory allocation for headless operation:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

> [!NOTE]
>
> 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

> [accordion] 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

> [accordion] 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

> [accordion] Hardware Integration
>
> * [ ] ReSpeaker Hat configured and working
> * [ ] Audio input/output tested successfully
> * [ ] LED matrix control functional
> * [ ] Servo communication established
> * [ ] Camera working (if applicable)

> [accordion] 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

> [!TIP]
>
> **Raspberry Pi Setup Complete!** Your LeLamp is now ready for calibration and operation.

***

**Previous**: [Assembly Guide](https://humancomputerlab.mintlify.site/assembly-guide.md) | **Next**: [Lamp Control](https://humancomputerlab.mintlify.site/lamp-control.md)

> [!TIP]
>
> Document your configuration settings and test results. This information will be valuable for troubleshooting and future maintenance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.