physicalai-plugins

A monorepo of third-party robot plugins for PhysicalAI.

Every package provides concrete implementations of the Robot protocol (no inheritance or registration required) and registers a robot catalog with PhysicalAI Studio via an entry point. Packages are built and released independently with release-please.

Packages

Package	Description	Released
physicalai-lekiwi-plugin	LeKiwi mobile manipulator (6-DOF arm + 3-wheel holonomic base)	yes
physicalai-mujoco-so101-plugin	MuJoCo SO-101 simulation plugin for PhysicalAI Studio	not yet published

Requirements

• Python 3.12+
• uv (used for the workspace, locking, and tooling)
• Physical hardware per package (serial ports / CAN adapters), or the MuJoCo simulator

Repository layout

packages/
  physicalai-lekiwi-plugin/
  physicalai-mujoco-so101-plugin/
docs/                          # guides (e.g. creating a plugin)
scripts/smoke.py               # import + version smoke test used by CI releases
.github/                       # CI, release-please config

Installation

From the repo root, install the whole workspace (all plugins, dev tooling):

uv sync

To depend on a single package from another project:

uv add physicalai-lekiwi-plugin

Running examples with the PhysicalAI CLI

The PhysicalAI CLI ships a run subcommand that executes a RobotRuntime (read observation → ask an action source → send action → tick) from a YAML config. This replaces the hand-written control loops that used to live in examples/.

Run any of the bundled runtime configs from the repo root with:

uv run physicalai run --config <path-to-yaml>

Press Ctrl+C to stop. Optionally cap the run with --run.duration_s=60.

LeKiwi

Keyboard drive of the base (arm holds its position):

uv run physicalai run --config packages/physicalai-lekiwi-plugin/examples/runtime/drive-keyboard.yaml

Composite teleoperation — leader arm positions the arm, keyboard drives the base:

uv run physicalai run --config packages/physicalai-lekiwi-plugin/examples/runtime/teleop.yaml

MuJoCo SO-101

Self-relay of a running MuJoCo owner over Zenoh:

uv run python packages/physicalai-mujoco-so101-plugin/examples/run_mujoco_owner.py
uv run physicalai run --config packages/physicalai-mujoco-so101-plugin/examples/runtime/teleop.yaml

Sinusoidal motion and joint reading

uv run physicalai run --config packages/physicalai-lekiwi-plugin/examples/runtime/move-joints.yaml
uv run physicalai run --config packages/physicalai-lekiwi-plugin/examples/runtime/read-joints.yaml

The only remaining script is the MuJoCo owner process (run_mujoco_owner.py), which starts the simulation server rather than a control loop.

Teleop action sources

physicalai-lekiwi-plugin bundles reusable action sources that can be wired into any physicalai run config (or used directly from Python):

from physicalai_lekiwi_plugin.teleop import CompositeTeleop, KeyboardTeleop

Source	Purpose
KeyboardTeleop	WASD/QE base velocities; arm held at its observed pose
CompositeTeleop	Combine a leader arm with a base source into one action

Keyboard controls (single characters, case-insensitive):

Key	Action
w / s	forward / backward
a / d	rotate left / right
q / e	strafe left / right
space	stop (zero the base)

Development

uv sync                          # install workspace + dev tooling
uv run prek                      # lint, format, type check (ruff + pyrefly + hooks)
uv run pytest packages/*/tests/  # run all package test suites

Release process

See RELEASE.md — packages are versioned from git tags via hatch-vcs and published to PyPI by release-please.

License

Apache-2.0 — see LICENSE.