SATELLITE_README.md

metadata

title: Tater Voice Sat
emoji: 🥔
colorFrom: red
colorTo: gray
sdk: static
pinned: false
short_description: Voice satellite for Tater and Home Assistant.
tags:
  - reachy_mini
  - reachy_mini_python_app
  - Voice-Assistant
  - Ai
  - Ai-Assistant
  - Conversational-Ai
  - Tater
  - voice-assistant
  - home-assistant

Tater Voice Sat

Reachy Mini as a Tater and Home Assistant voice satellite with movement.

This project treats Reachy Mini Wireless as a Linux-based satellite powered by OHF's linux-voice-assistant (LVA). LVA handles the ESPHome-style voice protocol used by Tater/Home Assistant satellites, local wake words, and the voice state machine. Audio flows through the Reachy Mini SDK media APIs. This bridge adds Reachy movement around those voice states. Until we have hardware, the movement layer can target the official Reachy Mini MuJoCo simulation.

Shape

Reachy mic array
  -> LVA local microWakeWord on the Reachy Pi
  -> LVA ESPHome voice protocol session to Tater
  -> Tater native voice pipeline
  -> LVA TTS playback URL/audio back to Reachy
  -> Reachy speaker plus Tater motion renderer

The important idea: Reachy is not a separate assistant. It is another Tater satellite, with a richer renderer than LEDs.

First Milestone

• Run on Reachy Mini Wireless Pi, or the Reachy Mini simulator with SDK media.
• Run LVA with a microWakeWord model for "Hey Tater".
• Expose LVA's ESPHome-compatible voice satellite endpoint.
• Connect to Tater's existing Voice Core ESPHome path.
• Map voice pipeline events to Reachy motion states.
• Play Tater TTS replies through Reachy's speaker.
• Simulate Reachy motion locally with reachy-mini-daemon --sim.

Later Milestones

• Reachy-specific side channel for rich motion commands.
• Tater UI card with Reachy status, motion intensity, idle animation, and room.
• Camera snapshots as Tater vision context.
• Camera stream/object awareness.
• Hydra tools like reachy_emote, reachy_look_at, and reachy_capture_frame.

Project Layout

tater_voice_sat/
  bridge.py        Main orchestration loop sketch.
  config.py        Typed config loader.
  lva_adapter.py   LVA runner plus motion-aware protocol hook.
  motion.py        Voice-state to movement renderer.
  reachy_client.py Reachy SDK wrapper.
  sdk_app.py       Reachy SDK app entrypoint and settings API.
  static/          Wake-word picker UI for the SDK app.
  wakeword_catalog.py microWakeWord catalog/install helper.
docs/
  architecture.md
  implementation-plan.md
  motion-states.md
  simulation.md
sounds/
  wake_word_triggered.wav
wakewords/
  hey_tater.json
  hey_tater.tflite
  stop.json
  stop.tflite
config.example.toml

Current Behavior

Running tater-voice-sat --config config.toml starts LVA in-process, patches LVA's VoiceSatelliteProtocol with Reachy motion hooks, and then lets LVA do the real satellite work. The bridge adapts LVA's microphone and playback calls to Reachy SDK media. Reachy motion currently dry-runs when the Reachy SDK is not installed.

The SDK app entrypoint, tater-voice-sat-app, starts the same bridge inside ReachyMiniApp and exposes a tiny settings page for choosing a microWakeWord from the shared Tater manifest.

Install Sketch

python3 -m venv .venv
. .venv/bin/activate
pip install -e .
cp config.example.toml config.toml
tater-voice-sat --config config.toml

Runtime paths in config.toml are resolved relative to the config file. The wakewords/ folder holds the local microWakeWord models LVA loads, and sounds/ holds the small playback cues LVA uses for wake, timer, processing, mute, and unmute events.

For simulation:

pip install -e ".[simulation]"
reachy-mini-daemon --sim
tater-voice-sat --config config.toml

On macOS, use mjpython -m reachy_mini.daemon.app.main --sim for the simulator and set [reachy].media_backend = "local" or "default" so the SDK exposes mic/speaker streams.

To test just the Reachy SDK microphone and wake model without ESPHome or Reachy motion:

python -m tater_voice_sat.wake_monitor --config config.toml

For the Reachy SDK app/settings flow:

tater-voice-sat-app --config config.toml

Open the app settings page from the Reachy dashboard to choose a wake word.

To test Reachy movement without the voice pipeline:

tater-voice-sat --config config.toml --motion-test
tater-voice-sat --config config.toml --motion-test obvious
tater-voice-sat --config config.toml --motion-test wake
tater-voice-sat --config config.toml --motion-test speaking --motion-intensity 1.0

Watchful Idle

The optional [watch] config watches camera frames while Reachy is idle. When motion is detected, Reachy turns toward the movement and holds a quiet watching pose. After a short quiet period, it returns to the normal idle animation.

This is enabled by default and uses lightweight frame-difference motion tracking with smoothed target updates; person/face detection can layer on later.