# PC Animatronic Playback System - Installation and Usage Guide

## Required Python Libraries

Before running the system, you need to install the required Python libraries. Open a command prompt or terminal and run these commands:

```bash
pip install pyserial
pip install python-vlc
pip install pygame
```

**Note**: You also need to have VLC Media Player installed on your computer for video playback to work.

## Hardware Setup

1. **Connect ESP32-S3**: Plug your ESP32-S3 into a USB port and note the COM port (e.g., COM3)
2. **Connect Mini Maestro**: Plug your Pololu Mini Maestro into a USB port and note the COM port (e.g., COM4)
3. **Update COM ports in code**: Edit the `animatronic_controller.py` file and change these lines:

```python
ESP32_COM_PORT = "COM3"        # Change COM3 to your ESP32 port
MAESTRO_COM_PORT = "COM4"      # Change COM4 to your Mini Maestro port
```

## File Organization

Create the following folder structure:

```
animatronic_system/
├── animatronic_controller.py          # Main program file
├── animatronic_config.json           # Configuration file
├── videos/
│   ├── main_performance.mp4          # 4.5 minute main video
│   └── 15min_countdown.mp4           # 15 minute countdown video
├── animations/
│   ├── intro_sequence.json           # Servo animation files
│   ├── middle_dialog.json
│   ├── climax_movement.json
│   ├── finale_bow.json
│   ├── idle_look_left.json
│   ├── idle_look_right.json
│   ├── greeting_wave.json
│   └── ... (other animation files)
└── audio/
    ├── hello_there.mp3               # Audio files for dialogue
    ├── how_are_you.mp3
    ├── funny_laugh.mp3
    └── ... (other audio files)
```

## Configuration Setup

1. **Copy the sample configuration**: Use the provided `animatronic_config.json` as a starting point
2. **Update file paths**: Make sure all video, animation, and audio file paths in the config match your actual files
3. **Customize animations**: Add or remove animations from the `active_idle.animations` list as needed

## Running the System

### Basic Usage
```bash
python animatronic_controller.py
```

### Using a custom configuration file
```bash
python animatronic_controller.py --config my_custom_config.json
```

### Stopping the System
- Press `Ctrl+C` to stop the system gracefully
- The system will automatically send reset commands to LEDs and stop all playback

## Configuration Options You Can Easily Change

### In the Python Code (animatronic_controller.py):

**Hardware Settings:**
```python
ESP32_COM_PORT = "COM3"        # Your ESP32 USB port
MAESTRO_COM_PORT = "COM4"      # Your Mini Maestro USB port
ESP32_BAUD_RATE = 115200       # ESP32 communication speed
MAESTRO_BAUD_RATE = 9600       # Mini Maestro communication speed
```

**Timing Settings:**
```python
TIMING_PRECISION = 0.01        # How often to check timing (smaller = more precise)
SERVO_COMMAND_DELAY = 0.001    # Delay between servo commands
MAIN_PERFORMANCE_DURATION = 270    # Main performance length (4.5 minutes)
ACTIVE_IDLE_DURATION = 900         # Active idle length (15 minutes)
```

**LED Commands:**
```python
LED_START_COMMAND = "p"        # Command to start main LED performance
LED_RESET_COMMAND = "r"        # Command to reset/stop LEDs
LED_DIALOGUE_PREFIX = "s"      # Prefix for dialogue LEDs (s1, s2, etc.)
```

### In the Configuration File (animatronic_config.json):

**Add more servo sequences to main performance:**
```json
"servo_sequences": {
  "0.0": "animations/intro_sequence.json",
  "30.5": "animations/early_dialog.json",
  "45.5": "animations/middle_dialog.json",
  "90.2": "animations/action_sequence.json",
  "120.8": "animations/climax_movement.json",
  "180.2": "animations/finale_bow.json"
}
```

**Change active idle behavior:**
```json
"active_idle": {
  "selection_method": "random",     // "random" or "sequential"
  "sequence_delay": 3.0,           // Seconds between animations
  ...
}
```

**Add more idle animations:**
```json
"animations": [
  {
    "json_file": "animations/new_idle_animation.json",
    "audio_enabled": false,
    "led_enabled": false
  },
  {
    "json_file": "animations/new_dialogue.json",
    "audio_enabled": true,
    "mp3_file": "audio/new_speech.mp3",
    "led_enabled": true,
    "led_command": "s4"
  }
]
```

## Troubleshooting

### Common Issues:

**"Failed to initialize serial connections"**
- Check that COM ports are correct in the code
- Make sure devices are plugged in and drivers are installed
- Try different USB ports

**"Video file not found"**
- Check file paths in configuration file
- Make sure video files exist in the specified locations
- Use forward slashes (/) in file paths, not backslashes (\)

**"Animation file not found"**
- Check that JSON animation files exist
- Verify file paths in configuration file
- Make sure JSON files are valid format

**LEDs not responding**
- Check ESP32 serial connection
- Verify ESP32 has correct firmware that responds to "p", "r", and "s1" commands
- Check ESP32 COM port setting

**Servos not moving**
- Check Mini Maestro serial connection
- Verify Mini Maestro COM port setting
- Check that JSON animation files have correct servo channel numbers (0-6 for 7 servos)

### Log Files:
The system creates a log file called `animatronic_system.log` that contains detailed information about what the system is doing. Check this file if you're having problems.

### Testing Individual Components:

**Test ESP32 LED communication:**
```python
import serial
esp32 = serial.Serial("COM3", 115200)  # Use your COM port
esp32.write(b"p")  # Should start LED performance
esp32.write(b"r")  # Should reset LEDs
esp32.close()
```

**Test Mini Maestro servo communication:**
```python
import serial
maestro = serial.Serial("COM4", 9600)  # Use your COM port
# Move servo 0 to center position (approximately)
command = bytes([0x84, 0, 0x50, 0x46])  # Channel 0, position ~1500
maestro.write(command)
maestro.close()
```

## Performance Tips

1. **Use an SSD**: Store video files on a solid-state drive for better performance
2. **Close other programs**: Close unnecessary programs to free up system resources
3. **Test thoroughly**: Run through complete cycles to ensure reliable operation
4. **Monitor logs**: Check log files regularly for any warning messages
5. **Backup configurations**: Keep backup copies of your configuration and animation files