How lukassor/foid works
Foid is an offline, German-first room-control system: a person speaks a wake word and command, the voice process recognizes and interprets it, then sends a device action over newline-delimited JSON/TCP. The simulator applies actions to room state and updates its browser view; the same protocol is intended for a real room box. Settings and typed commands provide a second control surface. The graph preserves documented wake, STT, fuzzy/optional-LLM NLU, earcon, protocol, and simulator capabilities. Some voice internals are documented but unsampled, so their links reflect README-described flow.
Main entry points: app.py Voice process · server.py Simulator hub · tcp.py TCP transport · web.py Settings server
Components 26
Voice runtime
- Voice process
voice/foid_voice/app.py - Wake detection
voice/foid_voice/wake.py - Audio capture
voice/foid_voice/audio.py - Speech detection
voice/foid_voice/vad.py - Speech recognition
voice/foid_voice/stt.py - Command interpretation
voice/foid_voice/nlu.py - Local LLM fallback
voice/foid_voice/llm.py - Audio feedback
voice/foid_voice/sounds.py - Room connection
voice/foid_voice/room_client.py
Protocol and devices
- Device catalog
protocol/foid_protocol/catalog.py - Device definitions
protocol/foid_protocol/devices - Protocol messages
protocol/foid_protocol/messages.py - JSON line codec
protocol/foid_protocol/codec.py - TCP transport
protocol/foid_protocol/tcp.py
Room simulator
- Simulator hub
room-sim/foid_sim/server.py - Room state
room-sim/foid_sim/room.py - Room browser view
room-sim/foid_sim/static/room.js
User surfaces
- Settings server
voice/foid_voice/web.py - Settings page
voice/foid_voice/templates/settings.html
Settings and feedback
- Voice settings
voice/foid_voice/config.py - English/German text
protocol/foid_protocol/i18n.py - Earcon WAVs
voice/foid_voice/static/sounds
Other components
- Room user
- Microphone
- Local model runtime
- Room control box
Connections 35
- Room user → Microphone: speaks
- Microphone → Audio capture: audio frames
- Voice process → Audio capture: captures
- Voice process → Wake detection: detects wake
- Voice process → Speech detection: segments speech
- Voice process → Speech recognition: transcribes
- Voice process → Command interpretation: interprets text
- Voice process → Room connection: dispatches command
- Voice process → Audio feedback: plays cues
- Audio capture → Wake detection: audio frames
- Audio capture → Speech detection: audio frames
- Speech detection → Speech recognition: speech audio
- Command interpretation → Device catalog: matches phrases
- Command interpretation → Local LLM fallback: fallback interpretation
- Local LLM fallback → Local model runtime: runs model
- Device catalog → Device definitions: loads definitions
- Audio feedback → Earcon WAVs: loads sounds
- Room connection → TCP transport: sends commands
- TCP transport → JSON line codec: encodes lines
- JSON line codec → Protocol messages: serializes messages
- TCP transport → Simulator hub: delivers messages
- TCP transport → Room control box: protocol connection
- Simulator hub → Protocol messages: parses messages
- Simulator hub → Room state: applies actions
- Room state → Device catalog: updates device state
- Simulator hub → TCP transport: broadcasts events
- Simulator hub → Room browser view: pushes room state
- Room browser view → Simulator hub: posts commands
- Room browser view → Room user: shows room
- Room user → Settings page: enters commands
- Settings page → Settings server: submits settings
- Settings server → Voice process: updates runtime
- Settings server → Voice settings: loads and saves
- Settings server → Voice process: text command
- Simulator hub → English/German text: serves translations