> ## 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.

# Servo Setup and Configuration

> Step-by-step guide to setting up and configuring your STS3215 servos for LeLamp operation

# Servo Setup and Configuration

> [!NOTE]
>
> **⏱️ Estimated time:** 30-45 minutes\
> **🔧 Required tools:** Computer, servo driver, USB cable\
> **📦 Required components:** 5× STS3215 servos, servo driver board

The first step in assembling LeLamp is setting up your servos with proper IDs and testing their functionality.

## Overview

Each LeLamp uses 5 STS3215 servos that must be individually configured with unique IDs. This setup process ensures each servo responds correctly to commands and operates within safe parameters.

> [!WARNING]
>
> Complete servo setup **before** mechanical assembly. Once servos are mounted in the lamp structure, configuration becomes much more difficult.

## Step 1: Download LeLamp Runtime

**1. Clone the Repository**

On your personal computer, open your terminal and clone the LeLamp Runtime Repository:

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

> [!TIP]
>
> Verify the download by checking that the `lelamp_runtime` directory contains Python files and configuration folders.

**2. Install UV Package Manager**

Install the UV package manager for Python dependency management:

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

```powershell Windows theme={null}
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

> [!NOTE]
>
> You may need to restart your terminal or source your shell configuration after installation.

**3. Setup Runtime Environment**

Install all required dependencies:

```bash theme={null}
uv sync
```

This process downloads and installs all necessary Python packages for servo control and testing.

> [!TIP]
>
> This installation will be repeated later on your Raspberry Pi, but having it on your computer allows for initial servo configuration.

## Step 2: Prepare Your Servos

**1. Unbox and Inspect Servos**

Remove all 5 servos from packaging and inspect each one:

* Check for physical damage
* Verify all servo horns are included
* Test manual rotation (should move smoothly with slight resistance)
* Ensure cables are intact and connectors are clean

![Five STS3215 servos laid out on work surface](https://mintlify.s3.us-west-1.amazonaws.com/humancomputerlab/images/servo-unboxing.jpg)

**2. Label Your Servos**

Create labels for each servo according to their intended position in LeLamp:

| Servo Name | Servo ID | Function |
| - | - | - |
| base\_yaw | 1 | Base rotation (left/right) |
| base\_pitch | 2 | Base tilt (forward/back) |
| elbow\_pitch | 3 | Elbow joint movement |
| wrist\_roll | 4 | Wrist rotation |
| wrist\_pitch | 5 | Head tilt (up/down) |

![Servos with identification labels attached](https://mintlify.s3.us-west-1.amazonaws.com/humancomputerlab/images/servo-labeling.jpg)

> [!NOTE]
>
> There's no specific servo that must be assigned to each ID. The important thing is having 5 servos with unique, labeled IDs that you can track throughout assembly.

## Step 3: Configure Servo Driver Connection

**1. Connect Servo Driver**

Connect the servo driver board to your computer using a USB cable.

> [!WARNING]
>
> Ensure the servo driver is powered off when making initial connections to prevent damage.

**2. Find the Serial Port**

Identify which port the servo driver is connected to:

```bash theme={null}
uv run lerobot-find-port
```

This command will display available serial ports. The output typically shows something like:

```bash macOS theme={null}
/dev/tty.usbmodem5A680114681
```

```bash Linux theme={null}
/dev/ttyACM0
```

```bash Windows theme={null}
COM3
```

> [!TIP]
>
> If multiple ports are shown, disconnect and reconnect the servo driver, then run the command again to identify which port appears/disappears.

## Step 4: Run Motor Setup Script

**1. Execute Setup Command**

Run the motor setup script with your specific configuration:

```bash theme={null}
uv run -m lelamp.setup_motors --id your_lamp_name --port your_port
```

**Example:**

```bash theme={null}
uv run -m lelamp.setup_motors --id lelamp --port /dev/tty.usbmodem5A680114681
```

> [!WARNING]
>
> Remember the lamp name you choose - you'll use this identifier throughout the configuration and operation process.

**2. Follow Interactive Setup**

The setup script will guide you through configuring each servo:

1. **Connect each servo individually** when prompted
2. **Verify servo response** to test commands
3. **Set servo ID** according to your labeling system
4. **Test range of motion** to ensure proper operation
5. **Save configuration** for each servo

![Servo connected to driver board during setup process](https://mintlify.s3.us-west-1.amazonaws.com/humancomputerlab/images/servo-setup-process.jpg)

**3. Verify All Servos**

After individual setup, connect all servos in a daisy chain to verify they respond correctly:

* Each servo should respond only to its assigned ID
* Movement should be smooth and controlled
* No servo conflicts or communication errors

> [!TIP]
>
> All 5 servos respond correctly to individual commands without interference.

## Servo Configuration Details

### Understanding Servo IDs

Each servo must have a unique ID (1-5) that corresponds to its position in LeLamp:

> [accordion] Base Yaw (ID: 1)
>
> **Function**: Rotates the entire lamp left and right
> **Range**: ±90° from center position
> **Critical**: This servo bears the weight of the entire upper assembly

> [accordion] Base Pitch (ID: 2)
>
> **Function**: Tilts the lamp forward and backward
> **Range**: Approximately ±45° from vertical
> **Critical**: Controls overall lamp posture and attention direction

> [accordion] Elbow Pitch (ID: 3)
>
> **Function**: Bends the lamp's "elbow" joint
> **Range**: 0-180° (fully extended to fully bent)
> **Critical**: Primary articulation for expressive gestures

> [accordion] Wrist Roll (ID: 4)
>
> **Function**: Rotates the head assembly around its axis
> **Range**: ±180° continuous rotation
> **Critical**: Adds expressiveness to head movements

> [accordion] Wrist Pitch (ID: 5)
>
> **Function**: Tilts the head up and down
> **Range**: ±45° from horizontal
> **Critical**: Fine control for attention and expression

### Communication Protocol

The servos communicate using a daisy-chain protocol:

```
Computer → Servo Driver → Servo 1 → Servo 2 → Servo 3 → Servo 4 → Servo 5
```

> [!NOTE]
>
> Each servo passes commands along the chain, responding only to messages with its specific ID. This allows control of all servos through a single communication cable.

## Testing and Validation

### Individual Servo Tests

After setup, test each servo individually:

> [tab] Range of Motion
>
> ```bash theme={null}
> # Test full range for each servo
> uv run -m lelamp.test.test_servo_range --id your_lamp_name --servo 1
> uv run -m lelamp.test.test_servo_range --id your_lamp_name --servo 2
> # ... repeat for servos 3, 4, 5
> ```

> [tab] Response Speed
>
> ```bash theme={null}
> # Test servo response timing
> uv run -m lelamp.test.test_servo_speed --id your_lamp_name
> ```

> [tab] Position Accuracy
>
> ```bash theme={null}
> # Verify position feedback accuracy
> uv run -m lelamp.test.test_servo_accuracy --id your_lamp_name
> ```

### System Integration Test

Test all servos working together:

```bash theme={null}
# Run coordinated movement test
uv run -m lelamp.test.test_all_servos --id your_lamp_name --port your_port
```

This test verifies:

* No communication conflicts between servos
* Smooth coordinated movements
* Proper power distribution
* Stable operation under load

## Success Criteria

After completing servo setup, verify the following:

> [accordion] Configuration Verification
>
> * [ ] All 5 servos labeled with intended positions
> * [ ] Each servo responds only to its assigned ID (1-5)
> * [ ] No servo ID conflicts or communication errors
> * [ ] Motor setup script completed without errors
> * [ ] Configuration saved and can be reloaded

> [accordion] Performance Verification
>
> * [ ] All servos move smoothly through full range
> * [ ] No binding, grinding, or unusual noises
> * [ ] Position feedback matches commanded positions
> * [ ] Response time is consistent across all servos
> * [ ] Power consumption within expected ranges

> [accordion] System Integration
>
> * [ ] All servos can operate simultaneously
> * [ ] Daisy-chain communication works reliably
> * [ ] No interference between servo operations
> * [ ] System remains stable during complex movements

## Troubleshooting Common Issues

> [accordion] Servo Not Detected
>
> **Symptoms**: Setup script cannot find or communicate with servo
>
> **Solutions**:
>
> * Check USB connection and try different cable
> * Verify servo driver power supply
> * Try different USB port on computer
> * Check servo cable connections
> * Restart servo driver and reconnect

> [accordion] Permission Errors
>
> **Symptoms**: "Permission denied" or "Access denied" errors
>
> **Solutions**:
>
> * **Linux**: Add user to dialout group: `sudo usermod -a -G dialout $USER`
> * **macOS**: May need to run with `sudo` for serial access
> * **Windows**: Check device manager for driver issues
> * Restart terminal after permission changes

> [accordion] Servo ID Conflicts
>
> **Symptoms**: Multiple servos respond to same command
>
> **Solutions**:
>
> * Reset all servos to factory defaults
> * Configure servos one at a time, disconnecting others
> * Verify each servo ID before connecting the next
> * Use servo manufacturer's configuration tool if available

> [accordion] Inconsistent Movement
>
> **Symptoms**: Servo moves erratically or doesn't reach target positions
>
> **Solutions**:
>
> * Check power supply voltage and current capacity
> * Verify servo cable integrity
> * Test servo individually outside of daisy chain
> * Update servo firmware if available
> * Replace servo if hardware fault is suspected

## Next Steps

> [!TIP]
>
> **Servo setup complete!** Your servos are now configured and ready for mechanical assembly.

With your servos properly configured, you can proceed to [Assembly Guide](https://humancomputerlab.mintlify.site/assembly-guide.md) where you'll mount them into the 3D printed LeLamp structure and complete the mechanical assembly.

> [!TIP]
>
> Keep your servo configuration notes handy - you'll reference the servo IDs and lamp name during software setup and calibration.


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