AndrejOrsula/pymoveit2

What it is

pymoveit2 is a thin Python wrapper that lets you control a robot that runs MoveIt 2 (the popular motion‑planning framework for ROS 2) directly from Python code. It talks to MoveIt 2 over ROS 2 actions and services, exposing a clean, high‑level API for common tasks such as:

Forward / inverse kinematics
Planning and executing joint‑space or Cartesian motions
Real‑time servoing
Gripper actions
Manipulating the planning scene (adding/removing collision objects, toggling collision checks)

The library is essentially a convenience layer: you still need a ROS 2 installation and a MoveIt 2 configuration for your robot, but once those are in place you can write short Python scripts instead of dealing with low‑level ROS messages.

How to get it

Method	Command	Notes
Binary ROS package (pre‑built for the standard ROS 2 distributions)	`sudo apt install ros-$ROS_DISTRO-pymoveit2`	Works on Humble, Jazzy, Lyrical, Rolling.
PyPI (pure‑Python wheel)	`pip install pymoveit2`	Useful if you prefer pip over apt.
Docker (ready‑to‑run image)	`docker pull andrejorsula/pymoveit2` then run the helper script as shown in the README.
From source	Clone the repo into a ROS 2 workspace and build with `colcon`.

Quick‑start example (Franka Emika Panda)

Install the MoveIt 2 configuration for the Panda robot:

sudo apt install ros-$ROS_DISTRO-moveit-resources-panda-moveit-config ros-$ROS_DISTRO-controller-manager

Launch the MoveIt 2 demo for the robot:

ros2 launch moveit_resources_panda_moveit_config demo.launch.py

Run a pymoveit2 demo script, e.g. move to a predefined joint configuration:
```
ros2 run pymoveit2 ex_joint_goal.py
```

If nothing moves, the repository provides a diagnostic script:

ros2 run pymoveit2 ex_doctor.py

Core Python API

`connect()` / `RobotSession`

from pymoveit2 import connect

with connect() as robot:
    robot.move_to_pose([0.4, 0.0, 0.4], [1.0, 0.0, 0.0, 0.0])
    robot.gripper.close()
    robot.move_to_configuration()

RobotSession bundles:

a ROS 2 node (robot.node)
an executor (robot.executor)
the robot description (robot.description)
a MoveIt2 interface for planning (robot.arm)
optional gripper and servo interfaces (robot.gripper, robot.servo).

Low‑level construction

If you need more control you can instantiate the pieces yourself:

from pymoveit2 import RobotDescription, MoveIt2, GripperInterface, MoveIt2Servo

node = ...  # your own rclpy.Node

desc = RobotDescription.from_node(node)
moveit = MoveIt2(node=node, **desc.moveit2_kwargs())
gripper = GripperInterface(node=node, **desc.moveit2_gripper_kwargs()) if desc.gripper_group_name else None
servo = MoveIt2Servo(node=node, frame_id=str(desc.moveit2_kwargs()["base_link_name"]))

What you can do with the examples

Category	Example script	What it shows
Kinematics	`ex_fk.py`, `ex_ik.py`	Forward and inverse kinematics calls
Motion planning	`ex_joint_goal.py`, `ex_pose_goal.py`	Move to a joint target or a Cartesian pose (optionally using Cartesian interpolation)
Constraints	`ex_orientation_path_constraint.py`	Enforce a fixed end‑effector orientation during motion
Real‑time control	`ex_servo.py`	Use MoveIt 2 Servo for low‑latency tele‑operation
Gripper	`ex_gripper.py`	Open/close/toggle a robot gripper via a ROS action
Planning scene	`ex_collision_primitive.py`, `ex_collision_mesh.py`, `ex_allow_collisions.py`, `ex_clear_planning_scene.py`	Add/remove primitive shapes or meshes, enable/disable collisions, clear the scene
Session workflow	`ex_session.py`	A compact end‑to‑end demo using the `RobotSession` context manager

Who might find this useful?

Robotics researchers who want to prototype algorithms in Python without writing ROS‑2 boilerplate.
Educators / students teaching motion planning, because the API is approachable and the demo scripts are ready‑to‑run.
Developers of higher‑level AI/ML pipelines (e.g., learning‑from‑demonstration, reinforcement learning) that need a simple way to send motion commands to a real or simulated robot.

Limitations / Things to keep in mind

It does not provide any learning or perception capabilities; it is purely a control interface for MoveIt 2.
You still need a functional ROS 2 + MoveIt 2 setup for your robot (URDF, SRDF, controller configs, etc.).
Real‑time performance depends on the underlying MoveIt 2 Servo node and your hardware; the Python layer adds minimal overhead but is not a hard‑real‑time solution.

Bottom line

pymoveit2 bridges the gap between Python and the powerful MoveIt 2 motion‑planning stack, letting you write concise, readable scripts to move robots, query kinematics, and manipulate the planning scene. It is a solid building block for anyone who wants to integrate Python‑based AI or higher‑level logic with ROS‑based robotic systems.