🐶

The Pidog Router

a robot dog with a brain that knows when to think small, think big, or phone home

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.

🗣️ Voice in & out 🧠 3 AI brains 🦴 Real movement 📷 Vision 🏠 Smart home 🔎 Web search

See it in action

The dog in motion

A quick look at the Pidog Router doing its thing — listening, deciding, and responding in real time.

The big picture

Two computers, one dog

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.

The Pidog captures speech and sends the text to the Router. The Router picks one of four destinations, gets an answer, and sends it back for the dog to speak — and act on.

Turning it on

Starting Astro

Two things run: the brain on the Mac, and the voice on Astro (the dog). Start the brain first, then the dog.

1 · The brain — on the Mac

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

2 · The voice — on Astro

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

MAC_IP vs astro.local: 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).

Handy commands

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).

Options you can add

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).

A nicer voice

The default voice is a free, offline, slightly robotic one (espeak). Two upgrades, both set on Astro (voice runs on the dog):

🗣️ Piper (via Home Assistant) — free

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

🎙️ ElevenLabs — most lifelike (paid)

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>

Put these in ~/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.

Things to say

“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

Hands-free option: Astro can start listening the moment it powers on (no terminal) via a small “systemd service” — see the project README. Then you only ever start the brain on the Mac.

The brains

Three AI "brains" plus your smart home

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.

FAST — a small local model

A compact 3-billion-parameter model (Qwen2.5-3B) running right on the Mac. Instant, free, private. Handles greetings, jokes, quick chit-chat.

SMART — a bigger local model

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.

CLOUD — Claude, over the internet

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.

HOME — Home Assistant

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

Automatic fallback. If a chosen brain is unavailable (a model isn't running, the internet is down, the smart home doesn't recognise a command), the Router quietly tries the next option and tells you what it did. The dog never just goes silent.

The decision

How it chooses, in a blink

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.

Simple keyword & length rules pick a destination first. You can also force one, or set the whole dog to "always use CLOUD" for a setup with no local models.

Voice

Ears and a mouth

All the listening and speaking happens on the Pi. Each half has options so you can trade convenience against privacy and quality.

👂 Speech → text (hearing)

Google (default) — accurate, needs internet.
Vosk — fully offline, private.
Home Assistant — use your HA voice engine (e.g. Whisper).

🗣️ Text → speech (talking)

Local (default) — the Pidog's built-in voice, free & offline.
ElevenLabs — a far more natural cloud voice.
Home Assistant — HA's Piper/cloud voices.

Streaming speech. The dog doesn't wait for the whole answer. As the AI writes, the Router sends text over as it appears; the dog speaks each sentence the moment it's finished while the rest is still being written. A long, web-searched answer starts coming out of the speaker in a second or two instead of after a long silence.

Movement

Making the dog actually move

Talking is only half a robot dog. There are two ways it physically acts.

⚡ Direct commands

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.

🧠 AI-chosen actions

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.

Do a little routine for me — turn around and then sit.

Woohoo, routine time! Turning, then plopping into a sit like a good pup! 🐾

cloud · claude · performs: turn_left → forward → sit

Behind the scenes the AI adds a tiny tag like [[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.

Vision

“What do you see?”

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.

📷 What do you see?

I see a red ball on the wooden floor, and a person's sneakers just past it! Fetch? 🎾

cloud · claude · 📷 photo sent with the question

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.

Reaching outside

The smart home & the whole web

🏠 Home Assistant

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.

🔎 Web search

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.)

What's the weather right now?

Woof! It's mostly cloudy and 56° right now — sweater weather, not shorts weather! 🐾

cloud · claude · 🔎 searched the web

Personality

Instincts & idle life

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.

🖐️ Head pat

Touch its head and it wags its tail — instantly, no AI.

👂 Loud sound

Tilts its head curiously toward an unexpected noise.

🧱 Obstacle

Refuses to walk into something close ahead — barks instead of bumping.

Idle behaviours. Left alone for a while, the dog stretches, dozes off, or wags on its own, so it feels alive rather than switched-off. All movement — commands, reflexes, idle — is coordinated so the dog never tries to do two things at once.

Start to finish

The journey of one question

You speak. The Pi's microphone captures it and turns it into text.
Quick check. Is it a direct command like "sit"? Do it now, done. A camera question? Take a photo.
Ask the Router. The Pi sends the text (and photo, if any) over Wi-Fi to the Mac.
Choose a brain. The Router matches keywords & length → FAST, SMART, CLOUD, or HOME.
Get the answer — searching the web or attaching an action if the moment calls for it.
Speak & move. The dog talks sentence-by-sentence as the answer streams back, then performs any actions.
Log it. Every exchange appears on a live dashboard so you can watch what happened and what it cost.

Watching it work

The live dashboard

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.

fast smart cloud home

Under your control

Turn things on and off

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.

Two people can share the exact same code but behave completely differently — one with local models and a real dog, another bypassing all of that to use only Claude in the cloud — just by changing their own private settings file.

🐶 The Pidog Router — a friendly guide.
Built on SunFounder Pidog · Apple MLX (local models) · Anthropic Claude (cloud) · Home Assistant.