Final project

Kinda Intelligent, Not so Great Electronic Roommate

KINGER

Based on the character Kinger from The Amazing Digital Circus by Glitch Studios.
KINGER is a modular, voice-enabled intelligent assistant that combines embedded systems and local AI inference tools.

Inspired by commercial smart speakers, KINGER is configured as an open development environment that lets users run high-level LLMs locally on a credit-card-sized computer, completely detached from cloud dependencies.

Project Objectives

Develop a completely self-hosted physical voice assistant using standard Linux Single Board Computers.
Implement low-latency local execution of Large Language Models (LLMs) and acoustic processing blocks.
Isolate high-level applications from raw input/output tasking through dedicated custom co-processing units.
Build an optimized spatial PCB distribution array using vertical interconnect strategies to maximize small-footprint form factors.

Schedule & Interactive Timeline

Nota: Puedes interactuar marcando los checkboxes de las tareas dentro del carrusel para observar cómo cambian los estados de las actividades y sus colores reflejados directamente en el calendario de la barra lateral.

System Architecture

KINGER desentrelaza las operaciones de tiempo real crítico de la inferencia neuronal masiva dividiendo su topología en dos capas principales intercomunicadas mediante conexiones seriales asíncronas UART dedicadas.

High-Level Processing Unit (Raspberry Pi 5)

Funciona como el núcleo lógico central del sistema. Captura flujos PCM crudos desde buses digitales I2S, ejecuta modelos de cuantización acústica locales, evalúa la pila conversacional mediante subprocesos y renderiza las síntesis fonéticas en tiempo de ejecución lineal.

Low-Level Control Unit (Seeed Studio XIAO)

Actúa como un escudo físico de co-procesamiento periférico. Se encarga de mitigar el ruido por rebotes en las líneas de interrupción de los botones analógicos, recibe tramas directas de estados del sistema y manipula la modulación de las líneas dinámicas de un anillo LED.

Hardware Integration Layers

La captura y salida acústica evitan las distorsiones inherentes de las conversiones analógicas convencionales mediante el uso del bus digital inter-IC (I2S). La Raspberry Pi 5 actúa como el maestro del bus, proveyendo los relojes de sincronía de línea:

Captura Digital (INMP441): Transmite datos serializados de audio a través de líneas de datos configuradas en pines GPIO nativos de la Pi. Utiliza tres señales fundamentales: Reloj de bits (SCK), Selección de canal Word Select (WS) y Datos Seriales (SD).
Amplificación de Potencia (MAX98357A): Un amplificador de alta eficiencia Clase D con DAC integrado que decodifica las señales de audio I2S directamente desde los pines dedicados de la Pi (GPIO18 -> BCLK, GPIO19 -> LRCLK, GPIO21 -> DIN) y entrega hasta 3W de potencia pura a una bocina de 4Ω.

Software Pipeline & Deployment

Para ejecutar el motor conversacional completo de KINGER de forma fluida y local en la Raspberry Pi 5 bajo Raspberry Pi OS, sigue meticulosamente la siguiente documentación técnica de despliegue.

1. Preparación del Entorno Aislado

Debido a las estrictas políticas de paquetes gestionados externamente de Python en las versiones modernas de Linux, es mandatorio instanciar un entorno virtual (venv) para evitar colisiones con las bibliotecas globales del sistema:

# Crear directorio principal del proyecto y subcarpetas necesarias
mkdir -p ~/kinger_ai/voices ~/kinger_ai/models
cd ~/kinger_ai

# Instanciar el entorno virtual aislado de Python
python3 -m venv venv

# Activar el entorno virtual (Debe ejecutarse antes de cualquier script o instalación)
source venv/bin/activate

2. Instalación de Dependencias Críticas

Con el entorno activo, procedemos a compilar e instalar las capas del pipeline fonético y utilidades del sistema:

# Instalar utilidades de sistema para captura y manipulación de audio
sudo apt-get update && sudo apt-get install -y alsa-utils sox python3-pip

# Instalar motores de IA dentro del venv activo
pip install --upgrade pip
pip install faster-whisper piper-tts ollama

3. Despliegue e Inicialización de Ollama y Qwen

Ollama gestiona de manera óptima los pesos del LLM y acelera la inferencia en arquitecturas ARM64. Instalamos el demonio del sistema y descargamos el modelo de parámetros optimizados de Alibaba:

# Descargar e instalar el binario del motor Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Verificar que el servicio esté corriendo en segundo plano o inicializar manualmente:
# ollama serve

# Descargar localmente los pesos ligeros pero avanzados del modelo Qwen2.5 de 3 mil millones de parámetros
ollama pull qwen2.5:3b

4. Estructura de Módulos Python (.py) del Sistema

La lógica modular se divide en archivos específicos coordinados por un despachador principal. A continuación se detallan las implementaciones clave:

brain.py

Mantiene el contexto histórico de la conversación en un buffer dinámico estructurado y realiza peticiones REST locales al demonio de Ollama.

from ollama import chat

conversation = [
    {"role": "system", "content": "Tu nombre es KINGER, eres el asistente de voz físico del cuarto. Responde conciso."}
]

def ask_ai(question):
    conversation.append({"role": "user", "content": question})
    response = chat(model="qwen2.5:3b", messages=conversation)
    answer = response["message"]["content"]
    conversation.append({"role": "assistant", "content": answer})
    return answer

speak.py

Toma cadenas de texto plano, las convierte mediante síntesis de voz fonética neuronal acelerada con Piper (usando el modelo en español de México) y manda los frames crudos al backend de ALSA.

import os

def speak(text):
    clean_text = text.replace('"', '').replace('\n', ' ')
    # Asegúrate de haber descargado el modelo onnx en la ruta correcta
    model_path = "~/kinger_ai/voices/es_MX-ald-medium.onnx"
    
    # Canalizar texto a Piper y escribir el WAV resultante
    os.system(f'echo "{clean_text}" | piper --model {model_path} --output_file response.wav')
    
    # Reproducción directa al hardware I2S mediante ALSA
    os.system('aplay -D plughw:0,0 response.wav')

commands.py

Filtro de intercepción previa al LLM. Si detecta intenciones explícitas de control o consultas rápidas, ejecuta macros internas inmediatas evitando llamadas pesadas de IA.

import datetime

def check_commands(text):
    text_clean = text.lower().strip()
    if "hora" in text_clean:
        now = datetime.datetime.now().strftime("%H:%M")
        return f"Son las {now}."
    if "fecha" in text_clean:
        today = datetime.datetime.now().strftime("%A %d de %B")
        return f"Hoy es {today}."
    return None # No es un comando, requiere pasar a Qwen

main.py (Orquestador Central)

El bucle continuo que une la entrada física I2S, la transcripción con Faster-Whisper a hilos de texto, la evaluación de comandos, la inferencia de Ollama y el canalizador final de audio.

import os
from faster_whisper import WhisperModel
import brain
import speak
import commands

# Inicializar modelo Whisper cuantizado para ejecución eficiente en CPU ARM
stt_model = WhisperModel("tiny", device="cpu", compute_type="int8")

def run_pipeline():
    print("Capturando audio por I2S...")
    # Grabación estéreo de 5 segundos a 48kHz nativa del hardware
    os.system('arecord -D hw:0,0 -f S32_LE -r 48000 -c 2 -d 5 raw.wav')
    # Conversión a monoaural para procesamiento óptimo en Faster-Whisper
    os.system('sox raw.wav mono.wav remix 1')
    
    # Transcripción local instantánea
    segments, _ = stt_model.transcribe("mono.wav", language="es")
    prompt = "".join([seg.text for seg in segments]).strip()
    
    if not prompt:
        print("No se detectó audio inteligible.")
        return

    print(f"Transcripción: {prompt}")
    
    # 1. Verificar comandos de control rápido
    response = commands.check_commands(prompt)
    
    # 2. Si no es comando, enviar al LLM local
    if response is None:
        response = brain.ask_ai(prompt)
        
    print(f"Respuesta de KINGER: {response}")
    
    # 3. Síntesis y salida física a bocina
    speak.speak(response)

if __name__ == "__main__":
    # Bucle operativo infinito de KINGER
    while True:
        # Aquí se integrará la escucha del flag UART enviado por el botón de la XIAO
        run_pipeline()

PCB Design Strategy

Para consolidar la electrónica de KINGER dentro de un chasis cilíndrico compacto, se estructuró un sistema modular basado en la superposición geométrica vertical de 3 placas independientes fabricadas en el laboratorio mediante fresado SRM-20:

PCB 1 — Raspberry Pi Interface Board

La placa superior. Se acopla de manera nativa al header de 40 pines de la Raspberry Pi 5. Su objetivo primordial es el aislamiento de pistas analógicas y enrutamiento limpio de los buses I2S para evitar acoplamientos electromagnéticos con los relojes lógicos del procesador.

PCB 2 — Common Distribution Board

La placa central de alimentación. Centraliza las referencias de voltajes y planos de tierra comunes (GND), evitando bucles de masa que generen zumbidos parásitos en la amplificación Clase D.

PCB 3 — XIAO Interface Board

La placa base. Aloja al microcontrolador secundario Seeed Studio XIAO. Dirige los traces lógicos del bus serial UART y los hilos de corriente continua para energizar los 16 transistores internos del arreglo LED sin interferir con la señal analógica del sistema.