Palmimo DevKit

What is Palmimo DevKit about?

Palmimo DevKit supplies the software stack for the Palmimo tabletop robot: a pure‑Python SDK, an MCP server that exposes robot capabilities as tools, and ready‑to‑run agent examples. It abstracts low‑level Dynamixel servo control, face‑display handling, and optional TTS/audio capture, letting developers focus on high‑level AI behavior.

How to use Palmimo DevKit?

1. Clone the repository on a Raspberry Pi 5 (or any Linux host). git clone https://github.com/Jizai-inc/palmimo-devkit.git
2. Install dependencies with the recommended package manager uv. From the repo root run uv sync (or uv add palmimo-sdk in another project).
3. Run the MCP server (see the docs for the exact entry‑point) or import the SDK in your own Python script.
4. Control the robot via the high‑level API, e.g.:

   from palmimo_sdk import Palmimo
   robot = Palmimo()
   robot.wave()
   robot.look(pitch=10, yaw=-20)
   

   If no hardware is attached the SDK operates in dry‑run mode, returning simulated servo ticks.
5. Integrate with LLM agents using palmimo_sdk.agent or by calling the MCP server from Claude Code, OpenClaw, etc.

Key Features

• AI‑agent ready: LLM tool calls are mapped to robot actions (walk, wave, speak, capture frame).
• MCP server: Exposes the same tool set over the Model Context Protocol for any MCP‑compatible client.
• Compact motion engine: Pure gait & inverse‑kinematics computation, dry‑run capable.
• 18 built‑in motions: Walking, turning, gestures, poses, and choreography sequencing.
• Expressive face display: Parametric emoji‑style emotions rendered over USB‑CDC.
• Optional voice: Integrated piper-plus TTS and microphone capture with noise reduction.
• Raspberry Pi 5 host: Pre‑imaged image, USB‑bus servo control, camera, mic array, and speakers.
• Open‑source: Apache‑2.0 licensed SDK, drivers, agents, and documentation.

Use Cases

• Embodied AI research: Test LLM‑driven embodied agents in a safe, low‑cost hardware platform.
• Prototype human‑robot interaction: Build voice‑enabled companions that gesture and display emotions.
• Robotics education: Students can explore gait generation, inverse kinematics, and sensor integration without deep hardware expertise.
• Custom automation: Deploy agent‑driven assistants that physically interact with a desk environment (e.g., fetch objects, signal status).

FAQ

Q: Do I need the physical robot to develop? A: No. The SDK runs in dry‑run mode, returning simulated servo positions so you can develop and test logic without hardware.

Q: Which Python version is required? A: Python 3.12 or newer.

Q: How do I install the SDK in an existing project? A: Use uv add palmimo-sdk (or pip install palmimo-sdk). Extras such as hardware, face, speech, agent, vision, and mcp can be added as needed.

Q: What safety precautions are needed when running on the real robot? A: Test motions in the air first, keep hands away from moving parts, monitor servo temperature, and always unplug power if the controlling process crashes.

Q: Can I extend the motion library? A: Yes. Follow the motion‑development guide in doc/guides/motion-development-guide.md to add new gait or gesture definitions.

Q: How do I expose the robot to an external MCP client? A: Run the MCP server (python -m palmimo_sdk.mcp or the documented entry point) and connect your client using the provided tool definitions.

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 · 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 Examples) build on it as front-ends.
• Dry-run first — every motion computes without hardware, so you can explore the motion API with no robot attached. Most calls that need a servo bus, face display, or speaker are no-ops without one; the API reference names the ones that raise.

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.

1. Get the code — git clone https://github.com/Jizai-inc/palmimo-devkit.git on the Pi.
2. Install — uv sync from the repository root; the installation guide covers extras, voice models, and what to do when an import fails.
3. 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

Page	What it covers
Raspberry Pi setup	Preparing the control host, headless
Installation	Dependencies, voice models, troubleshooting

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

Page	What it covers
Python API reference	Every public class, method, and tuning knob
Motions and gait parameters	The 18 motions and what you can tune
App manifest	palmimo.toml — the fields, params, and validation rules a host reads
User scripts	diagnose_servos.py — every subcommand and its safety notes; record_keyframes.py — pose by hand, save keyframes

Understanding how it works

Page	What it covers
System architecture	The layering, and why the engine has no I/O
How Palmimo moves	The kinematic chain and the tripod gait

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.