How to build Peeqo (GIF-speaking desktop companion robot): the whole process
111 steps to build Peeqo (GIF-speaking desktop companion robot), from buying parts, printing and assembly to software, calibration and training, with the bill of materia…
The dev kit is sold out (peeqo.com, 2026‑11‑01, waitlist only) and has no current price; neither the repos nor the wiki give a parts list or total
Buy parts
- Join the Peeqo Dev Kit Waitlist
Open the waitlist page and enter your email address to join the waitlist for a Peeqo dev kit.
Assemble
- Assemble Peeqo Using the Wiki
Open the Assembly wiki page and follow the full assembly instructions provided there.
- Position the neck servos
Position the servo shafts 27.32 mm from the centre and 42 mm up. Fit each servo with a U-horn and its hubs.
- Pin the neck legs
Pin each leg 7 mm from its shaft. Each leg consists of two arms.
- Position the neck rod ends
Position the rod ends 34.32 mm from the centre and 100.1 mm up. Each eye turns freely on its screw and tilts by at most 18°; it would touch the lugs at 23.7°.
- Identify Servo Channels and LED Position
Identify which PCA9685 channel drives each servo and where LED 0 is located.
Software
- Install workspace dependencies
Run npm install once in the project root.
- Set up the wake word
With Python 3.10 or newer, run the setup command once for the @peeqo/wakeword workspace.
- Check code and build
Run the typecheck, unit tests, and production build.
- Deploy Robot Software to Raspberry Pi
Flash Raspberry Pi OS Lite 64-bit with SSH enabled, then run `npm run deploy -w @peeqo/robot` from a laptop. The installer sets up everything else.
- Set Up Wi-Fi From a Phone
Set up Wi-Fi from a phone. When Peeqo knows no Wi-Fi, it displays a QR code for its setup network.
- Set up the Wi-Fi network
If Peeqo knows no Wi-Fi network, it starts its own network, "Peeqo-Setup-XXXX", and shows a QR code on its face.
- Connect a phone or laptop
Phone: scan the QR code with the camera; the phone joins the network and opens the setup page. Laptop: join the network shown on the screen, then open `http://10.42.0.1`.
- Configure Wi-Fi on the page
On the page, choose your Wi-Fi, a PIN for the panel and, optionally, the API keys. Peeqo joins your network and shows its address.
- Repeat the Wi-Fi setup
If the password was wrong, the setup network comes back and both the page and the face say why. Hold a button for 10 s to do this again, for example after moving house.
- Create Custom Commands
Open the creating-a-custom-command tutorial and create your own commands by following it, even without a Peeqo.
- Install simulator dependencies
Run npm install once from the repository root. Install the simulator's package dependencies before launching it.
- Configure the live brain
The live brain uses OpenRouter with `google/gemini-3.8-flash` as the default model; it accepts audio and uses tools.
- Set environment variables and run
Put `OPENROUTER_API_KEY` in the repository's `.env`, plus `KLIPY_API` for GIFs; Git ignores this file. Then run the simulator.
- Record and send voice input
Your speech is sent to the model as a recording without a transcription step. The model writes down what it heard, and this appears in the transcript.
- Install the wake-word model
The wake-word feature requires Python 3.10 or newer. Run the workspace setup command once; the model is in `packages/wakeword`.
- Save recent conversation
Save the last 12 to 16 exchanges in `conversation.json` so a reload can continue; clearing chat starts afresh but keeps the memory.
- Manage conversation memory
Drop older exchanges four at a time after the model saves anything lasting from them; when exchanges are more than half an hour apart, tell Peeqo how long it has been.
- Keep facts on the local machine
Send the facts to the model with each message through OpenRouter, but store them only on this machine; without the dev server, they remain in the browser.
- Configure GIF search caching
Cache GIF searches on disk and set an hourly budget of 90 to stay under the key's limit of 100.
- Serve media from the dev server
Serve media from the dev server so the face can draw it.
- Connect the model on the robot
Have the same `Brain` on the robot use the keys from its own `.env` to call OpenRouter and Klipy directly.
- Enable the robot wake word
Use the same wake word detector to listen to the robot's microphone.
- Set up the Peeqo character
Implement `Character` in `packages/character` and use it to drive the head, face, ring, and voice.
- Implement character states
Implement idle, listening, thinking, speaking, and sleeping states; each sets the resting face, gaze, LED ring, and head liveliness, with a small greeting gesture on entry.
- Implement character expressions
Implement 23 expressions: happy, excited, laugh, love, sad, grumpy, surprised, scared, sleepy, curious, confused, thinking, yes, no, hello, bye, shy, wink, celebrate, alert, oops, sigh, wonder.
- Synchronize expression motion
Build each expression from timed steps that move the head, eyes, ring, and voice together; when it ends, restore the current state's settings.
- Implement idle life behavior
While idle, let Peeqo occasionally look curiously or wonder; when left alone longer, it sighs and then yawns, and after five quiet minutes it sleeps until anything involving it wakes it with a start.
- Protect active conversation states
Ensure idle life behavior never interrupts the listening, thinking, or speaking states.
- Synthesize character sounds
Synthesize short chirps, coos, and bloops in plain TypeScript in `sounds.ts`; the sim plays them through Web Audio, and the robot can play the same samples.
- Connect the head animation driver
Use HeadAnimator in packages/core to turn gestures into smooth governor targets at 100 updates per second; the same code will drive the robot.
- Define sixteen head gestures
Define nod, shake, tilt, look-up, look-down, droop, perk-up, bounce, wiggle, think, listen, doze, sigh, startle, groove, and hello in headAnimations.ts. Join each gesture’s keyframes with curves that ease through every turn without overshooting; small opposite moves before large moves provide anticipation.
- Add spring follow-through
Pass all motion through a slightly underdamped spring so moves settle with a little weight. Vary each gesture playback by a few percent so no gesture repeats exactly.
- Build the alive motion layer
Add breathing, a slow wander, and occasional glances or curious tilts. A 0–1 energy level controls the layer’s size and pace; it shrinks during gestures and can be switched off.
- Implement sixteen facial emotions
Implement neutral, happy, excited, love, sad, angry, surprised, scared, sleepy, curious, confused, thinking, listening, shy, wink, and skeptical in ExpressiveFace within packages/face, retaining the 2019 black eyes on white in the same positions.
- Shape eyes and blend emotions
Shape each eye with its size, openness, a curved and slanted upper lid, a smiling lower lid, and catch-lights; use a beating heart for love. Blend emotions with springs so changes pop and settle.
- Add autonomous facial motion
Add varied blinks that are sometimes doubled and often occur during a large glance, plus saccades with micro-saccades between them. The gaze follows the current emotion and can also be told where to look.
Calibrate and test
- Prepare and start calibration
Calibration is done once from the panel, with the cloth cover off so the three servo arms are visible. It takes about 10 minutes.
- Identify each arm and direction
For each plug on the servo board, tap ▲ (about 1° a tap) until you see an arm move, then say which arm it was and whether it went up or down. The arms are short, so it takes a few taps to see.
- Level each arm
Nudge each arm until it points level. An arm only moves a little on its own: the arms are linked through the head, so one arm alone tilts it.
- Measure the overall range
The whole head moves up and down, staying level. Each ▲/▼ moves all three arms by 0.5°.
- Mark the lowest position
Lower it until something is just about to touch, then mark it.
- Mark the highest position
Raise it until it's as high as it should go, just short of binding, then mark it. It must leave room for Peeqo's normal height.
- Level with a level app
Peeqo goes to its normal height, arms level (1500 µs). Put your phone flat on its head with a level app open and tap until it reads 0° (optional).
- Check and correct the scale
Let Peeqo tilt back 3°. Type what the level reads; this corrects the scale (optional).
- Check the servo travel limits
Calibration has none of its own limits, only the servos' travel (500–2500 µs). Every move is a small, slow step you ask for, so stop before anything touches. It starts from 1500 µs, where the 2019 software always left the servos.
- Configure microphone and speaker
Use the board's WM8960 sound chip; after the first installation, enable `dtoverlay=wm8960-soundcard` and restart the robot. The installer uses `/etc/asound.conf` at 48 kHz in shared mode so playback and recording operate together, and sets the levels once with `system/sound-levels.sh`.
- Use the HDMI CEC remote
The display has no mouse pointer, so the HDMI port's CEC remote serves as one. A udev rule in `system/hdmi-cec.rules` makes libinput ignore that remote.
- Check screen resolution and rotation
Check the screen resolution and rotation on the real robot.
- Check speaker, microphone, and wake word
Check the speaker and microphone levels and the wake word by ear.
- Locate LED 0 on the ring
Check where LED 0 sits on the ring.
- Test setup network and captive portal
Check the setup network and captive portal on real phones.
- Perform the calibration check
Perform and check the calibration on the real robot.
- Start the simulator
Start the simulator and open http://localhost:5173 in a browser.
- Run the fake-hardware service
Run the robot service with fake hardware and open http://localhost:8080 in a browser.
- Verify the built simulator
Run the verification command, which drives the built simulator in Chrome.
- Route All Poses Through MotionGovernor
Every head pose from sliders, animations, the brain, or anything later must pass through MotionGovernor.
- Refuse Poses With Unsafe Clearance
Refuse poses that bring two parts within 0.5 mm. Use exact mesh distances precomputed from the Fusion assembly and independently re-measure with `npm run check:clearance -w @peeqo/sim`.
- Refuse Other Unsafe Poses
Also refuse poses with a horn and leg nearly in line, or a rod end tilted past 18°.
- Apply Motion Speed Limits
Apply caps on speed, acceleration, and servo speed.
- Plan Safe Straight-Line Paths
Moves follow straight lines. When a straight path is blocked, the robot goes round by the neutral pose.
- Preserve Neck Movement Space
Every gesture must leave at least 30% of the neck's movement room unused.
- Test Gestures Through Real Governor
During tests, play every gesture and expression through the real MotionGovernor.
- Begin Guided Panel Calibration
Remove the cloth, then begin guided calibration from the panel.
- Calibrate Arm Channels and Level
Find each arm's channel, direction, and level by eye.
- Measure Each Arm's Safe Range
Move the whole head together while keeping it level because the arms are linked. The lowest and highest safe points determine each servo's range.
- Level Head and Check 3° Tilt
Level the head with a phone level and check the scale with a 3° tilt. The servos stay limp until this is done.
- Set Measured Ranges as Hard Limits
The measured ranges become hard limits: the governor plans 1.5° inside them and the driver never goes outside them. On the robot they are the only limits on arm movement, with the real arms moving freely about 85° either way.
- Complete Remaining Hardware Checks
Check the screen's resolution and rotation, speaker and microphone levels, the location of LED 0, which button is which, and backlash and play in the rod ends. The sound chip is set up, but the wake word still needs testing.
- Use the default offline brain
The offline brain is the default and provides scripted written answers in Peeqo's voice. It needs no key or network, but it cannot understand speech.
- Check the development proxy
The development server proxies calls through `apps/sim/server/api.ts`, so the keys never reach the page. The proxy answers only the simulator page and refuses other sites.
- Confirm model restrictions
Confirm that the proxy forwards only Claude and Gemini models and caps replies at 1,000 tokens.
- Test wake word and speech stopping
Tick **Wake word** and say "hey jarvis" to use the ready-made openWakeWord model; "hey Peeqo" needs training. The page streams the microphone to `/api/voice` on the development server, where the detector judges when speech stops.
- Verify microphone fallback
When the wake-word setup is absent, **Mic** still works and uses loudness to determine when you have stopped talking.
- Run a real-model live check
Run the live-check script from the terminal with "hello" to talk to the real model.
- Speak live-check output
On macOS, use `--speak` to send each line as speech.
- Test expression safety limits
Play every expression from several states through the real governor and verify that it never has to hold the head back.
Use it
- Use the motion governor
After calibration, the motion governor drives the servos. Peeqo stands with its arms level, and head moves are sized to the room your marks leave, keeping a tenth of the room spare. The governor plans 1.5° in from each mark and keeps to the neck's geometry, a box on tilts, and its speed caps.
- Inspect Peeqo's data files
Open `~/.peeqo` to inspect `config.json`, `memory.md`, `conversation.json`, `alarms.json`, and `sessions.json`. `config.json` contains keys, the hashed PIN, and calibration, and only Peeqo's user can read it.
- Check the Peeqo services
Confirm that the `peeqo` service runs on port 80. Confirm that `peeqo-face` runs Chromium full screen on the display and shows `/face`.
- Watch the service log
Watch the `peeqo` service log in real time with `journalctl -u peeqo -f`.
- Observe real-board performance
Observe display performance on the real 3 B+ 1 GB board; the face draws at 30 frames per second and Chromium uses low-memory mode. The service used about 130 MB on a Mac, while its motion loop used under 3% of one Pi core.
- Check the Wi-Fi watchdog
Keep Wi-Fi power saving off because it makes the Pi drop off the network. If the router stops answering for 2 minutes, Peeqo turns its Wi-Fi off and on again.
- Read the previous-boot log
Logs are kept across restarts and capped at 64 MB. Use `journalctl -u peeqo -b -1` to show the previous boot's log.
- Monitor temperature and power
View the Pi's temperature on the panel and check its throttling state with `vcgencmd get_throttled`. The log reports when the robot slows down to stay cool or when the power supply dips too low.
- Shut down Peeqo safely
After a shutdown request, wait 30 seconds; if the system still has not stopped Peeqo, force it to stop. Even if that fails, the face says it is safe to unplug.
- Operate the robot hardware
The hardware helper `python/hardware.py` drives the PCA9685 servo board on I²C bus 1 at address 0x40, a ring of 12 APA102 LEDs on SPI 0.0 at 4 MHz, and four buttons. The buttons read high when pressed: GPIO 17 front left, 4 front right, 23 rear right, and 16 rear left.
- Launch browser simulator
Run npm run sim, then open the printed URL, http://localhost:5173. The browser simulator includes the neck mechanism, face, LED ring, and head motion, all driven through the same safety governor the robot will use.
- Talk to Peeqo
Use the **Talk to Peeqo** box in the simulator, or speak to Peeqo out loud.
- Complete one brain turn
Peeqo thinks and then returns one or two expressions, a reaction GIF, and a caption of at most six words from one `respond` call.
- View the face-screen feedback
Peeqo first shows how it feels, then plays the GIF on its face screen with the caption over it in meme style. Without a GIF, the caption appears above its eyes.
- Enable spoken replies
Turn on **Speak aloud** to replace browser text replies with spoken replies and occasional GIFs. Its state moves from listening to thinking to idle, where idle means speaking with the voice enabled.
- Use the microphone input
Select **Mic** and the browser records continuously until you stop talking.
- Use time and reminder tools
The model can check the time and set, list, and cancel timers and reminders. Timers and reminders are kept in the page and survive a reload.
- Receive due reminders
When a timer or reminder is due, Peeqo announces it with a GIF.
- Look up the weather
Weather data comes from Open-Meteo, which is free and needs no key. Ask without naming a place and Peeqo uses where you live if it remembers.
- Manage Peeqo's memory
Peeqo stores lasting information such as your name, where you live, the people in your life, your preferences, and important dates in `apps/sim/.data/memory.md`. You can read and edit this list.
- Forget saved information
Ask Peeqo to forget something, or use **Forget everything** in the panel. The model uses its remember and forget tools to decide what to keep and skips small talk.
- Select the classic eye design
Select Peeqo’s 2019 classic eyes from the panel, or use `?face=classic` to choose that design.
- Use the LED animation modes
Use LedAnimator in packages/core to drive the 12 DotStar LEDs. Looping modes include glow, breathe, heartbeat, spin, listen, speak, and rainbow; Sparkle produces random twinkles that peak at white, while success, error, and wake are one-shots that return to the previous looping animation.
- Enable the legacy 2019 animations
The 2019 animations remain available. When several animations are available, the one started last drives the ring.
Common problems
Parts
- Raspberry Pi: the dev kit has a Raspberry Pi 3 B+ (1 GB), and the next-generation software also runs on later models
- Three servos in a Stewart-style head platform, driven by a PCA9685 servo board (I²C 0x40)
- A head screen (HDMI, with full-screen Chromium drawing the face), a 12-LED APA102 ring (SPI), 4 buttons
- Audio: the dev kit uses a WM8960 sound chip; the 2017 design has a Knowles mic board, and its prints include a Sabrent USB sound card cover and a speaker clamp
- 2017 prints: head and head cap, LED ring, base ring and feet, Stewart base and top, 3 servo holders and slide clamps, speaker clamp, camera mount, power-inlet holder and more
- A 12 V DC adapter and a cloth cover (wiki assembly steps)
Tools
- For a 2017-style build: a 3D printer, plus PCB fabrication from the Eagle files and soldering tools
- A computer and microSD card for flashing the system
- A phone level app to level the head during calibration (next-generation software docs)
Skills
- Raspberry Pi OS Lite, SSH and npm deployment; the first install takes about 15 minutes
- Guided servo calibration: finding each arm's channel and direction and marking the limits (about 10 minutes)
- JavaScript / TypeScript: custom commands and servo animations (wiki tutorial)
Software
- 2019 Electron app: offline snowboy wake word, Dialogflow intents, Giphy / Vlipsy GIF and video replies, timers, weather, Spotify
- Next-generation TypeScript workspace (next branch): a browser simulator, a motion governor bound by CAD collision tables, expressive eyes with 16 emotions, LED ring patterns and synthesized sounds
- An OpenRouter brain with Klipy GIFs, memory, timers and reminders, Open‑Meteo weather, a microWakeWord wake word, a web panel and phone Wi‑Fi setup