Iris mic pmod

IRIS

Intelligent Responsive Interface System — a personal voice assistant with an FPGA wake-word accelerator.

Hub-and-spoke architecture: a GPU desktop runs the hub (brain + memory), and any client device connects over WebSocket to talk to it.

Architecture

Desktop PC (hub)
├── FastAPI + WebSocket server  ← brain lives here
├── Ollama LLM (llama3.1:8b)
├── SQLite memory
└── Web UI at http://localhost:7865

Clients (connect over Tailscale)
└── clients/laptop/  ← the IRIS client (orb + voice + text); hub_url set to localhost
    (same machine) or the hub's Tailscale IP (remote device)

Quick Start

1. Hub (run on your GPU desktop)

# Install deps
pip install -r hub/requirements.txt

# Configure
cp hub/.env.template hub/.env
# Edit hub/.env — set OLLAMA_BASE_URL and OLLAMA_MODEL

# Run Ollama (separate terminal)
ollama serve
ollama pull llama3.1:8b

# Start the hub
python -m hub
# → http://localhost:7865

2. Laptop Client

pip install -r clients/laptop/requirements.txt

# Install Tailscale on the laptop, log into the same account as the desktop
# Then:
cp clients/laptop/config.json.template clients/laptop/config.json
python clients/laptop/main.py

Repo Layout

Networking

Clients connect to the hub over Tailscale — a free mesh VPN that gives every device a stable private IP regardless of network. No port forwarding or domain needed.

1. Install Tailscale on all devices
2. Log into the same account
3. Desktop Tailscale IP: 100.74.253.30 (set in clients/laptop/config.json)

Hardware (FPGA Accelerator)

Target: Basys 3 (Artix-7 XC7A35T)

When the FPGA detects the wake word it sends a UART trigger → voice pipeline takes over.

Voice Pipeline

Wake word ("computer") → VAD recording → Moonshine transcription → hub WebSocket → Ollama → response

Set KERAS_BACKEND=torch before running (avoids a TensorFlow install).

Custom wake word via Picovoice Porcupine — add your .ppn file to voice/ when trained.

Secrets

Never commit: hub/.env, voice/config.json, clients/*/config.json