🤖 Bloop: Local AI Robot Companion

Bloop is a cute, energetic, and slightly sarcastic desktop robot companion. Built with a focus on speed, privacy, and physical interaction, Bloop uses a hybrid architecture combining local AI models for hearing/speaking and ultra-fast cloud inference for "thinking."

When you say "Hey Bloop," she wakes up, listens to your voice, processes her thoughts, speaks back, and physically animates her servos, RGB LED, and OLED eyes to match her current emotion, all in near real-time.

✨ Features

• Always-On Local Wake Word: Uses openWakeWord with Voice Activity Detection (VAD) to flawlessly detect "Hey Bloop" in noisy rooms without sending your passive audio to the cloud. Custom-trained on 30k+ augmented examples.
• Ultra-Fast Cloud Brain: Leverages Groq's LPU infrastructure to run Whisper (Speech-to-Text) and GPT OSS 20B (Reasoning). Groq's inference speed allows Bloop to reply in under a second.
• Synchronized Physical Reactions: The LLM is strictly prompted to output JSON containing both a verbal response and an emotional state. This emotion instantly triggers specific OLED eye animations, RGB over-head light colors, and smooth, jitter-free servo movements.
• Continuous Animations: Powered by ServoEasing, Bloop doesn't just snap to static poses. She continuously breathes, twitches, waves, and looks around based on her current emotional state.
• Dual Voice Synthesis Engines: Run completely offline using Piper TTS for zero-latency local speech, or switch to the Fish Audio API for hyper-expressive, highly emotional cloud-based voice cloning. (Note: The custom Bloop Fish Audio voice model was cloned, uploaded, and made public by me, so it works for everyone right out of the box!)
• Memory-Optimized Arduino Core: The C++ features "SRAM Surgery" (C-string parsing and Flash memory storage) to prevent heap fragmentation, allowing the Uno to run complex OLED buffers and servo arrays without crashing.

🧠 System Architecture

Bloop's brain is split into two halves: the Python Host (running on a PC or Mac) and the Hardware Controller (Arduino).

1. Wake Word (Local): openWakeWord continuously listens for "Hey Bloop" locally.
2. Transcription (Cloud): Captures 4 seconds of audio and sends it to Groq's Whisper API.
3. Reasoning (Cloud): Sends the transcript to Groq's LLaMA 3.1. The system prompt forces a JSON response: {"reaction": "happy", "response": "That is so cool! [laughing]"}.
4. Animation (Serial): The Python script parses the JSON and sends the reaction (e.g., happy\n) over USB Serial to the Arduino.
5. Hardware Execution: The Arduino reads the serial command, updates the OLED display, shifts the RGB LED color, and initiates a non-blocking ServoEasing sweep for the 3 servos.
6. Voice Synthesis: Simultaneously, the host PC synthesizes the text into speech using either Piper TTS (Local Mode) or the Fish Audio API (Cloud Mode) and plays it through the speaker.

🛠️ Hardware Requirements

• Host Computer (PC, Mac, or high-end Raspberry Pi)
• USB Microphone & Speaker
• Arduino (Uno, Nano, or Mega)
• 3x 180° Micro Servos (Head tilt, Left Arm, Right Arm)
• 1x OLED Display (I2C - SH1106 or SSD1306)
• 1x Common Cathode RGB LED + 3x 220Ω Resistors
• 1x 1000µF 16V (or 12V/25V) Electrolytic Capacitor (Critical for preventing servo brownouts/jitter)
• Breadboard and Jumper Wires
• Cardboard/Custom 3D-printed body

🔌 Wiring & Schematic

Pinout Guide:

• Head Servo: Pin 7
• Left Arm Servo: Pin 6
• Right Arm Servo: Pin 5
• RGB LED: Red 9, Green 10, Blue 11 (All via 220Ω resistors)
• OLED Display: SDA A4, SCL A5

Note: Ensure the 1000µF capacitor is placed across the 5V and GND rails as close to the servo headers as possible to absorb power spikes.

💻 Software Requirements

• Python 3.10+
• Arduino IDE
• A Groq API Key (Free)
• A Fish Audio API Key (For Cloud Voice Mode)
• Piper TTS (CLI installed and added to PATH, for Local Voice Mode)

🚀 Installation & Setup

1. Arduino Setup

1. Open the bloop-arduino-uno.ino file in the Arduino IDE.
2. Install the necessary libraries via the Library Manager:
   • ServoEasing (by Armin Joachimsmeyer)
   • Adafruit_GFX
   • SH1106 (or Adafruit_SSD1306 depending on your screen)
3. Flash the code to your Arduino and take note of the COM port (e.g., COM6 or /dev/ttyACM0).

2. Python Host Setup

1. Clone this repository:

   git clone https://github.com/gerymeee/bloop.git
   cd bloop

2. Create a virtual environment and install dependencies:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Create a .env file in the root directory and add your API keys:

   GROQ_API_KEY=your_groq_key_here
   FISH_AUDIO_API_KEY=your_fish_audio_key_here
   

4. Ensure your custom openWakeWord model (hey-bloop.onnx) is in the root directory.

3. Running Bloop

Update the COM port inside your chosen script (around line 75) to match your Arduino's port. You can run Bloop in one of two modes:

For Cloud Voice (Fish Audio - Highly Expressive):

python bloop-cloud.py

For Local Voice (Piper TTS - Fully Offline):

python bloop-local.py

Wait for the terminal to print System Online, then say "Hey Bloop" to wake her up!

🔧 Troubleshooting

• Servos are jittery or resetting: This is a power issue, not a code issue. Ensure you have installed the 1000µF capacitor across your 5V and GND lines. If using a breadboard power supply, consider upgrading to a dedicated 5V 2A wall adapter.
• Arduino freezes after a few minutes: Ensure you are using the optimized bloop-arduino-uno sketch provided, which uses C-strings and F() macros. Standard String objects will fragment the Uno's 2KB SRAM and cause a crash.
• Wake word triggers randomly: Ensure vad_threshold is set to 0.3 or higher in your Python script.
• Fish Audio returns '402 Payment Required': Ensure you are passing the "model": "s2.1-pro-free" header in your API POST request to utilize the developer free tier.
• ModuleNotFoundError for 'speexdsp_ns': If you are on Windows using Python 3.14+, this C++ package may fail to build. You can bypass it by setting enable_speex_noise_suppression=False in the Model() initialization; Silero VAD will handle the noise filtering instead.

📜 License

This project is open-source and available under the MIT License.