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
- Fork the repo
- Create feature branch (
git checkout -b feature/amazing-feature)
- Commit changes (
git commit -m 'Add amazing feature')
- Push to branch (
git push origin feature/amazing-feature)
- Open Pull Request
See CONTRIBUTING.md for details.
License
MIT License - see LICENSE file for details.
Links
