ZunoBotics/pearlguide

Africa's first AI Powered Robot Tour Guide # Robot Head — Gemini Live Museum Guide An interactive robot head that holds real-time voice conversations with museum visitors using the Google Gemini Live API. The jaw servo animates in sync with the robot's speech. > **Project:** Pearl Guide — ZunoBotics AI Powered Tour Guide Robot > **Branch:** `robot-head` --- ## Quick Start (TL;DR) ```bash # 1 — clone and enter the directory git clone github.com -b robot-head cd pearlguide # 2 — install system packages (once) sudo apt update sudo apt install -y python3-pip python3-dev i2c-tools libportaudio2 portaudio19-dev # 3 — install Python dependencies (inside your conda / venv) pip install -r requirements.txt # 4 — set your Gemini API key echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc && source ~/.bashrc # 5 — run python main.py ``` --- ## Hardware | Component | Details | |-----------|---------| | Servo driver | PCA9685 16-channel, I2C address `0x40` | | Eye tilt | MG90S → **D0 (CH0)** | | Eye pan | MG90S → **D1 (CH1)** | | Head pan | MG996 → **D2 (CH2)** | | Jaw | MG996 → **D3 (CH3)** | | Camera | USB camera (mounted on one eye) | | Audio | 7.1-channel USB audio adapter (mic + speaker) | ### I2C wiring to Raspberry Pi | PCA9685 pin | Pi GPIO | Pi physical pin | |-------------|---------|-----------------| | SCL | GPIO3 | Pin 5 | | SDA | GPIO2 | Pin 3 | | VCC | 3.3 V | Pin 1 | | GND | GND | Pin 6 | > **Verify the PCA9685 is detected** before running: > ```bash > sudo i2cdetect -y 1 > # Should show "40" at row 40, column 0 > ``` --- ## Raspberry Pi Setup ### 1. Enable I2C ```bash sudo raspi-config # → Interface Options → I2C → Enable sudo reboot ``` ### 2. Install system packages ```bash sudo apt update sudo apt install -y python3-pip python3-dev i2c-tools libportaudio2 portaudio19-dev ``` ### 3. Install Python dependencies Always install into your active conda environment or venv — **not system Python** — to avoid permission issues with CircuitPython's ha …