ILLO - AI-Powered Levitating UFO Companion

Welcome to the ILLO API documentation! ILLO is an intelligent CircuitPython application that brings levitating UFO platforms to life with adaptive artificial intelligence, music-reactive visualizations, and college team spirit integration.

Overview

ILLO transforms the Circuit Playground Bluefruit into an AI companion with four distinct operating modes:

UFO Intelligence - An adaptive AI that learns from interactions and develops personality traits over time. Features persistent memory, mood management, and college spirit integration.

Intergalactic Cruising - Ambient sci-fi lighting with adaptive brightness, audio reactivity, and optional Bluetooth control via the Bluefruit Connect app.

Meditate - Guided breathing patterns for meditation and relaxation, with four different breathing techniques and adaptive timing based on ambient light.

Dance Party - Multi-device synchronized light shows using BLE for coordination, with real-time beat detection and tempo matching.

Key Features

  • Adaptive AI Learning - Develops unique personality through interactions

  • Persistent Memory - Remembers preferences across power cycles

  • College Spirit - Customizable team colors, fight songs, and chant detection

  • Audio Processing - Real-time FFT analysis for beat-synced visualizations

  • Environmental Sensing - Adaptive brightness (2-25%) based on ambient light

  • Multi-Device Sync - BLE-based synchronization for Dance Party mode

  • Memory Optimized - Aggressive optimization for 256KB RAM constraint

Hardware Requirements

  • Board: Adafruit Circuit Playground Bluefruit (nRF52840)

  • Firmware: CircuitPython 10.2.1+ (tested with 10.2.1)

  • RAM: 256KB (requires careful memory management)

  • Storage: 2MB flash for code and libraries

  • Features: 10 NeoPixels, accelerometer, microphone, light sensor, BLE 5.0

Quick Start

  1. Flash CircuitPython 10.2.1 or later to your Circuit Playground Bluefruit

  2. Copy all .py files and the lib/ directory to the CIRCUITPY drive

  3. Copy config.json to configure your preferred mode and settings

  4. Power on and enjoy! Button A cycles routines, Button B cycles modes

Configuration

Edit config.json to customize ILLO’s behavior:

{
  "name": "ILLO",
  "routine": 1,  // 1=AI, 2=Cruising, 3=Meditate, 4=Dance
  "mode": 1,     // Mode 1-4 (routine-specific)
  "bluetooth_enabled": true,
  "college": "penn_state",
  "college_spirit_enabled": false,
  "ufo_persistent_memory": true
}

API Documentation

Main Entry Point: The code.py file serves as the CircuitPython entry point and orchestrates all routines. See the source file directly for implementation details.

Core System

Operating Routines

UFO AI Subsystems

Audio & College Integration

Bluetooth Systems

Utilities

Architecture

ILLO uses a modular architecture with lazy loading to manage the 256KB RAM constraint:

  • code.py - Main entry point, routine orchestration, task scheduling

  • ConfigManager - Persistent JSON configuration management

  • MemoryManager - Garbage collection and memory monitoring

  • InteractionManager - Unified sensor input handling

  • LightManager - Adaptive brightness and interaction detection

  • BaseRoutine - Abstract base class for all operating modes

Each routine inherits from BaseRoutine and implements the run(mode, volume) method. The AI routine lazy-loads subsystems to minimize memory usage.

Memory Management

ILLO implements aggressive memory optimization strategies:

  • Lazy imports - Modules loaded only when needed

  • Periodic GC - Automatic garbage collection every 10 seconds

  • Threshold monitoring - Warnings at <5KB, critical at <2KB free

  • Cleanup on switch - Routines cleaned before mode transitions

  • Flash protection - Throttled save frequency for persistent memory

Development

See the CLAUDE.md file in the repository for detailed development guidance, including common commands, architecture patterns, and best practices.

Support

License

MIT License - See LICENSE file for details.

Made with ❤️ in the USA by Feral Cat AI