Palmimo DevKit
Give AI agents a body. Palmimo DevKit is a six-legged tabletop AI robot you drive
with your own Python — open-source SDK, MCP server, and agent examples by
Jizai Inc.
Website · Documentation · Get a DevKit
English | Japanese
Palmimo is a customizable, general-purpose AI robot: a tabletop companion that meets
your eyes, answers your voice, and speaks through expressions and gestures.
Palmimo DevKit is its development kit — the robot arrives assembled and tested,
and this repository is the software that runs it: a Python SDK, an MCP server and
agent examples that turn LLM tool calls into robot actions, and the docs.
Under the hood, 18 leg servos walk it on a tripod gait, a servo neck aims a round
face display, and a small expression engine gives it a face — all reachable from a
few lines of Python, with no robotics background required.
The core idea: a single motion engine (pure gait + inverse kinematics, no I/O)
drives the robot through interchangeable front-ends — the palmimo_sdk Python
API and example agent apps — and every motion computes in dry-run, with no
hardware attached, before it ever reaches a servo.
Palmimo.forward() → step() → MotionEngine computes → {servo_name: tick} → ServoDriver → hardware
(or compute-only in dry-run)
✨ Features
- AI-agent ready —
palmimo_sdk.agent turns LLM tool calls into robot actions
(walk, wave, look, set a face, speak, capture a frame), and the model behind it is
swappable. palmimo_sdk.mcp serves the same tools over MCP to Claude Code,
OpenClaw, or any MCP client, and the example apps ship a wake-word agent and an
always-on companion agent — see Examples and
Serving over MCP.
- A few lines of Python —
robot.wave(), robot.look(...), robot.forward().
- 18 built-in motions — walking and turning (
forward, strafe_left/right,
rotate_left/right, creep), gestures (wave, bow, clap, ...), and
poses (stretch, dance, pushup, ...), driven by an anti-phase
tripod gait; see the full list in the
motion list.
- Pitch/yaw neck — aimed with
look(pitch, yaw) independently of, and
simultaneously with, walking. The neck carries a third joint the motion engine
leaves at neutral; see Controlling motions.
- Choreography — sequence
(motion, seconds) steps via Palmimo.play_realtime().
- Expressive face — a parametric (math-drawn, no image assets) expression
vocabulary (HAPPY, ANGRY, SAD, EXCITED, THINKING, SLEEPY, …) rendered on the
face-display board over USB-CDC; the host decides the emotion, the board just draws it.
- Voice (optional) —
piper-plus TTS and shared mic-stream capture with
GTCRN noise removal (palmimo_sdk.audio), used by the example agent apps.
- Python API core —
palmimo_sdk.Palmimo drives one MotionEngine; example
agent apps (see ) build on it as front-ends.
robot.bow() and robot.wave(), on the hardware.
🦾 Hardware
Palmimo DevKit ships with 21 serial-bus servos
(18 leg + 3 neck), a round face display, a 5 MP camera, a mic array and stereo
speakers, and a Raspberry Pi 5 as the control host. What the software
talks to, and over what, is in
System architecture.
Hardware design files are not part of this repository (see
CONTRIBUTING → Scope); full
specifications are on palmimo.dev.
🔓 What's open, and what ships
- Open now (Apache-2.0): the
palmimo_sdk Python SDK and drivers, the agent
layer and MCP server, the example agents and the OpenClaw connection kit, the
LeRobot plugins, the diagnostics, and these docs.
- Opening progressively: more of the development stack beyond the SDK, starting
with the robot model for simulation and environments for robot learning. Watch
Discussions → Announcements
for what lands next.
- Not published: the manufacturing design of the hardware. See
CONTRIBUTING → Scope for where
hardware-side requests go.
🍓 Control host: Raspberry Pi
Palmimo's control host is a Raspberry Pi 5, wired to the servo bus
over USB, and it ships already imaged. The
Raspberry Pi setup guide writes a card from
scratch — Wi-Fi, SSH, and the runtime the Quickstart assumes — whether you are
re-imaging the shipped card or preparing a Pi of your own.
No robot yet? Every motion computes without hardware — skip to
Try the Python API.
🚀 Quickstart
On the Raspberry Pi, over SSH. Prerequisites: Python 3.12+ and
uv — the setup guide above installs them on a
card it writes.
- Get the code —
git clone https://github.com/Jizai-inc/palmimo-devkit.git
on the Pi.
- Install —
uv sync from the repository root; the
installation guide covers extras, voice models,
and what to do when an import fails.
- Check the servos —
uv run python scripts/diagnose_servos.py scan confirms
every servo answers before the first run. See
user diagnostics for the other subcommands.
Commands auto-detect the servo bus; explicit ports are covered where detection
is ambiguous.
⚠️ Test motions in the air before placing the robot on a surface — read
Safety first.
Try the Python API (no hardware needed)
Save this as walk.py in the repository root and run it with
uv run python walk.py:
from palmimo_sdk import Palmimo
robot = Palmimo()
robot.forward()
for _ in range(100):
pos = robot.step() # dict like {"leg_1_yaw": 2048, ...}
Palmimo() with no driver attached is compute-only, so this runs with no robot
connected.
Using palmimo_sdk from another project, without cloning this repository?
uv add palmimo-sdk (extras: hardware, face, speech, voice, agent,
vision, mcp — see
packages/palmimo_sdk/README.md).
🚨 Safety
This kit drives real, geared servos that can pinch, and runs on mains-derived
power. Before powering the robot:
- Test every motion in the air first — abrupt jumps damage gears; new motions
must transition smoothly to/from the neutral stance.
- Servo targets are clamped to a safe range (200–3900 ticks); avoid the
mechanical limits at 0 / 4095.
- Watch servo temperature during sustained motion — geared servos overheat under
load (treat > 70 °C as a warning sign, > 85 °C as stop-now).
- Keep fingers clear of the legs and neck while torque is enabled.
- Closing the controlling program does not guarantee the servos are released.
A clean exit parks the robot and disables torque, but a program that is killed,
crashes, or is stopped part-way through a motion may not reach that point, and
the servos then keep holding position — and keep heating — with no process
left running. Unplugging the AC adapter is the only certain way to make the
robot safe to handle. Do not read "the program is closed" as "the robot is
off".
The software is provided “as is”, without warranty of any kind; you operate the
hardware at your own risk.
📖 Documentation
The same pages, rendered: docs.palmimo.dev.
Getting it running
Doing something specific
| Page | What it covers |
|---|
| Controlling motions | Driving the robot from your own Python |
| Serving over MCP | Exposing the robot's tools to an MCP client |
| Adding a new motion | The full checklist, engine to tests |
| Examples | The agent apps that ship in this workspace |
| LeRobot integration | Robot and teleoperator plugins. A separate uv workspace on purpose: they depend on lerobot, and this tree's own resolution deliberately does not |
| Releasing | Tagging a release and publishing the draft |
Looking something up
Understanding how it works
Contributors: see CONTRIBUTING.md for the checks CI runs and
AGENTS.md for the coding and documentation rules.
📄 License
Licensed under the Apache License 2.0, except the robot model
docs-site/public/models/palmimo.glb, which is a display-only asset under
its own notice.
Hardware design files are not included at this time; any future hardware
release will carry its own license.
📚 Citation
If you use Palmimo DevKit in academic work, please cite this repository — see
CITATION.cff, or use GitHub's "Cite this repository" button.
🙏 Acknowledgements
Built on the ROBOTIS Dynamixel SDK.
The face-display firmware carries its own third-party attributions — the
Waveshare RP2350-Touch-LCD demo and
Noto Color Emoji (SIL OFL / Apache-2.0) —
mirrored in NOTICE.
