This guide explains — in plain language — how a SunFounder Pidog is wired to a little "router" program that decides, for every single thing you say, the smartest and cheapest way to answer it. No jargon required.
A quick look at the Pidog Router doing its thing — listening, deciding, and responding in real time.
The Pidog itself is a small Raspberry Pi computer. It's great at listening, talking, moving, and seeing — but it isn't powerful enough to run a serious AI. So it hands the thinking to a second computer (a Mac) running the Router. They talk over your home Wi-Fi.
Two things run: the brain on the Mac, and the voice on Astro (the dog). Start the brain first, then the dog.
Starts both local models + the router together. Leave this window open — it is the running brain; closing it (or Ctrl-C) stops everything.
$ cd "MLX LLM" $ ./start-all.sh # dashboard: http://localhost:8000/dashboard
Connect to the dog by name (astro.local), then launch the
voice loop. sudo is needed for the speaker & servos.
$ ssh simpsong00@astro.local $ sudo MAC_IP=192.168.68.101 \ ~/pidog-venv/bin/python ~/pidog_voice.py # wait for "🎤 listening..." then talk
astro.local is
the dog's address (used from the Mac to connect to it). MAC_IP
(192.168.68.101) is the Mac's address — Astro needs it to reach
the brain. If the Mac's IP ever changes, update that number (a router "DHCP
reservation" keeps it fixed).| Run this | What it does |
|---|---|
| ./start-all.sh | Mac: start the brain (both models + router). Ctrl-C stops it. |
| ./push-to-dog.sh | Mac: copy an updated pidog_voice.py to astro.local and restart the dog. |
| python chat.py | Mac: type to the dog to test it (no voice needed). |
| pidog_voice.py --selftest | Astro: check brain/mic/camera/deps are all reachable, then exit. |
| pidog_voice.py --test-actions | Astro: run through every move once (a physical smoke-test). |
Set these in the .env file, or type them right before the launch
command (e.g. sudo MAC_IP=… STT_PAUSE=2 ~/pidog-venv/bin/python ~/pidog_voice.py).
| Option | What it changes |
|---|---|
| MAC_IP | Which Mac the dog talks to (default 192.168.68.101). |
| STT_PAUSE | Seconds of silence that end a sentence. Raise it (e.g. 2) if it cuts you off. |
| STT_ENERGY | Mic sensitivity — set a number if it clips mid-word (lower = more sensitive). |
| WAKE_WORD | Only respond after a phrase, e.g. "hey pidog". Empty = always listening. |
| TTS_ENGINE | The voice — see “A nicer voice” below: auto (robotic, free) · ha (Piper, free & natural) · elevenlabs (most lifelike, paid plan). |
| CLOUD_MODEL | claude-haiku-4-5 (cheap) · claude-sonnet-5 · claude-opus-4-8. |
| ROUTER_DEFAULT_ROUTE | Force every question to one place, e.g. cloud (skips the local models). |
| PIDOG_SOUND_REFLEX | 1 to enable the “turn head toward sounds” reflex (off by default). |
| IDLE_MINUTES | Do a random idle move after N quiet minutes (0 = never). |
The default voice is a free, offline, slightly robotic one (espeak). Two upgrades, both set on Astro (voice runs on the dog):
HA’s built-in neural voice — clearly nicer than espeak, free and offline, no monthly cap. Needs your HA connection set up (same token as home commands):
$ export TTS_ENGINE=ha $ export HA_URL=http://homeassistant.local:8123 $ export HA_TOKEN=<long-lived token> $ export HA_TTS_ENGINE=tts.piper
Requires a paid ElevenLabs plan (Starter ~$5/mo). As of 2026 the free tier can’t use any voices through the API — there are no free default voices anymore. With a subscription:
$ ~/pidog-venv/bin/pip install elevenlabs $ export TTS_ENGINE=elevenlabs $ export ELEVENLABS_API_KEY=sk_... $ export ELEVENLABS_VOICE_ID=<a voice from your account>
~/dog.sh (or the systemd service’s
Environment= lines) so they stick. If a fancy voice is ever
unavailable, the dog automatically falls back to the built-in one — it never
goes silent. Free & natural = Piper. ElevenLabs is the paid,
even-more-lifelike option.| “sit” · “shake hands” · “walk backwards” | instant moves (no AI) |
| “ask Claude …” | force a smart cloud answer |
| “go to sleep” → “wake up” | nap & rouse (keeps listening while asleep) |
| “shut down” | actually stop the voice program |
Not every question deserves the same effort. Asking "who's a good boy?" shouldn't cost money or wait on the internet. The Router keeps a ladder of options and climbs it only as far as a question needs.
A compact 3-billion-parameter model (Qwen2.5-3B) running right on the Mac.
Instant, free, private. Handles greetings, jokes, quick chit-chat.
A 7-billion-parameter model (Qwen2.5-7B), also on the Mac. Slower but
better at reasoning: "why", "how does", "compare", "explain". Still free and private.
Anthropic's Claude models via the API. Reserved for the hard stuff: current events, long or expert answers, and anything needing a web search. Costs a little per use, so it's used sparingly.
Not an AI at all — your existing smart-home hub. "Turn off the kitchen" is sent straight here so it controls the lights and speaks the confirmation back.
| Brain | Lives | Good for | Speed | Cost |
|---|---|---|---|---|
| FAST (3B) | Mac | chit-chat, quick replies | very fast | free |
| SMART (7B) | Mac | reasoning, explanations | ~20 words/sec | free |
| CLOUD (Claude) | internet | current events, expertise, search | fast, has network hop | pennies |
| HOME (HA) | your hub | lights, locks, thermostats | instant | free |
The Router reads your words and checks them against simple rules — key phrases and length — before any AI is even involved. This costs microseconds and keeps easy things cheap.
All the listening and speaking happens on the Pi. Each half has options so you can trade convenience against privacy and quality.
Google (default) — accurate, needs internet.
Vosk — fully offline, private.
Home Assistant — use your HA voice engine (e.g. Whisper).
Local (default) — the Pidog's built-in voice, free & offline.
ElevenLabs — a far more natural cloud voice.
Home Assistant — HA's Piper/cloud voices.
Talking is only half a robot dog. There are two ways it physically acts.
Say a plain command — sit, come, shake hands,
turn left — and the dog does it instantly, without asking any AI at all.
Works even if the internet and the Mac are off. Rock-solid and fast.
For anything conversational, the AI can attach a hidden action to its reply. Ask it to "pretend you're sleepy" and it might yawn a sentence and lie down. It can even chain a short routine — turn, walk, sit — in one go.
[[action:turn_left,forward,sit]]
to its reply. The Router removes that tag before the dog speaks (so it's never said aloud) and
passes the moves to the Pi to perform in order. Unknown moves are ignored safely — a bad guess never
crashes the dog.Ask the dog what it sees and it snaps a photo with its camera, sends the picture along with your question, and describes what's in front of it. Because only Claude can look at images, vision questions always go to the CLOUD brain automatically.
Trigger phrases include "what do you see", "who is this", "what am I holding", and "take a look". Any other time, the camera stays off.
If you run Home Assistant, commands like "turn off the kitchen" are forwarded to it. HA does the understanding — it already knows your rooms and devices — then acts and hands back a spoken reply. If HA doesn't recognise the phrase, it quietly falls through to the AI instead.
The CLOUD brain can search the web on its own. Ask for the weather or today's news and Claude decides by itself to look it up, then answers with live information. You don't program the "when" — it just knows. (Local models can't search, which is another reason those questions route to the cloud.)
Some behaviours don't involve thinking at all — they're reflexes, just like a real dog, and run quietly in the background on the Pi.
Touch its head and it wags its tail — instantly, no AI.
Tilts its head curiously toward an unexpected noise.
Refuses to walk into something close ahead — barks instead of bumping.
Open http://<your-mac>:8000/dashboard in any browser on your network to see a
running feed of every question: which brain answered, how fast, how many words, the estimated
cost, any moves performed, and the full conversation. It updates every couple of seconds — handy
for tuning and genuinely fun to watch.
Every major feature is a simple switch in a settings file (.env). A few examples:
| Setting | What it does |
|---|---|
| CLOUD_MODEL | Which Claude model to use (cheaper Haiku vs. smarter Sonnet). |
| CLOUD_WEB_SEARCH | Let the cloud brain search the web. 0 to turn off. |
| ROUTER_DEFAULT_ROUTE | Send everything to one brain — e.g. cloud if you run no local models. |
| PIDOG_ACTIONS | Allow the AI to move the dog. 0 for a text-only setup. |
| STREAM_TTS | Speak sentence-by-sentence as the answer generates. |
| PIDOG_CAMERA · PIDOG_REFLEXES · IDLE_MINUTES | Vision, reflexes, and idle behaviours. |