Connecting to sources…

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

  • Dialogflow queries time out, leaving spoken requests unanswered #5 #3
  • Electron installation or startup fails on Debian #2 #1
  • Undefined Giphy response data crashes the image helper #4

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

Documents