Wundio

Open-source interactive box for kids, built on Raspberry Pi. Spotify via RFID, games, voice and AI. Free. Self-hosted.

Quick Install

curl -fsSL https://wundio.dev/install.sh | sudo bash

Works on Raspberry Pi 3, 4 and 5. AI features are automatically enabled or disabled based on the model.

Full guide: wundio.dev/docs/quickstart

Updates

Keep your Wundio Box up to date:

# Quick update (code from GitHub, ~10 seconds)
sudo bash /opt/wundio/scripts/wundio-pull

# Full update (code + frontend rebuild, ~5 minutes)
sudo bash /opt/wundio/scripts/wundio-pull --full

# System update (OS packages + Python libraries)
sudo bash /opt/wundio/scripts/update.sh

After updates:

sudo systemctl restart wundio-core

Full update documentation

Repository structure

wundio/
├── core/                  # FastAPI backend + hardware services (Python)
│   ├── api/routes/        # REST endpoints
│   ├── services/          # Hardware abstraction (RFID, OLED, Buttons, Spotify)
│   │   └── ai/            # Phase 3: STT, TTS, Wake-Word, Intent, Voice
│   ├── models/
│   ├── database.py        # SQLite via SQLModel
│   ├── config.py          # Central config (pydantic-settings)
│   └── main.py
│
├── web/                   # React SPA (Vite + Tailwind) – served by FastAPI on the Pi
│
├── scripts/               # Shell scripts
│   ├── install.sh         # Main install (one-liner)
│   ├── uninstall.sh       # Full removal
│   ├── update.sh          # System update (OS + Python libs)
│   ├── wundio-pull        # Code update from GitHub (NEW)
│   ├── setup-hotspot.sh   # WiFi hotspot for first-run setup
│   ├── install-whisper.sh # Whisper STT (Phase 3)
│   ├── install-piper.sh   # Piper TTS (Phase 3)
│   └── install-ollama.sh  # Ollama LLM (Phase 4, Pi 5 only)
│
├── systemd/               # systemd service definitions
├── tests/                 # pytest (Phase 0-3, 155 tests, no Pi required)
└── .github/workflows/     # CI: tests, lint, script sync to wundio-website

The website and documentation live in a separate repository: clemensgoering/wundio-website Scripts in scripts/ are synced there automatically on every push to main.

Development

Local Development (PC)

Backend:

cd core
python3 -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
uvicorn main:app --reload

Frontend:

cd web
npm install
npm run dev  # http://localhost:5173

Deploy to Pi

Option 1: Git Pull (Recommended)

# On Pi:
sudo bash /opt/wundio/scripts/wundio-pull
sudo systemctl restart wundio-core

Option 2: Direct Push from PC

# On PC:
git push origin main

# On Pi:
cd /opt/wundio
git pull
sudo systemctl restart wundio-core

Testing

# Run tests locally (no Pi required)
pytest tests/

# Run with coverage
pytest --cov=core tests/

Contributing

1. Fork the repo
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

See CONTRIBUTING.md for details.

License

MIT License - see LICENSE file for details.

Links

• Website: wundio.dev
• Documentation: wundio.dev/docs
• Hardware Guide: wundio.dev/docs/hardware
• Community: GitHub Discussions