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:

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

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

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

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

Running the System

Basic Usage

python animatronic_controller.py

Using a custom configuration file

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:

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:

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:

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:

"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:

"active_idle": {
  "selection_method": "random",     // "random" or "sequential"
  "sequence_delay": 3.0,           // Seconds between animations
  ...
}

Add more idle animations:

"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:

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:

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

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