Piper Beginner Guide 👶

This guide is based on my experience getting started with the AgileX Robotics Piper arm.
It aims to help others quickly understand and start using the robot without the usual setup difficulties.

Suggestions and contributions are always welcome!

Repository Structure

piper_beginner_guide/
├── piper_kinematics/       # Standalone FK/IK library (no ROS required)
└── piper_ros_control/      # Custom ROS 2 Humble package for robot control

Piper Kinematics

Kinematics visualization tool

You can visualize the Piper arm’s kinematic chain in 3D using the standalone visualizer (no ROS required):

This tool helps with:

• Visualizing the robot’s kinematic structure
• Verifying forward and inverse kinematics behavior

python3 ./piper_kinematics/piper_kinematics_visualizer.py

Piper ROS Control

Set up

Build the package and source the install file. This may be done only once.
⚠️ I highly recommend placing the piper_ros2-humble package in this workspace. The examples below are all written assuming this.

conda deactivate
colcon build

Create a conda environment to actually use the piper controller. This may be also done only once.

conda create -n piper_beginner_guide python=3.10
conda activate piper_beginner_guide
conda install pinocchio=3.6.0 casadi -c conda-forge
conda deactivate

Launching the robot arm

On a bash terminal, activate the CAN interface first (requires the piper_ros driver):

source scripts/launch_piper_arm.bash

Keyboard control demo

This demo allows you to control the robot arm using keyboard inputs.
It is useful for understanding how the PiperController node works in practice.

Currently uses an IK solver for position command due to issues caused by recent firmware updates.
⚠️ PLEASE NOTICE THAT THE DEFAULT ERROR THRESHOLD FOR IK IS QUITE HIGH (Position: 0.01m, Orientation: 0.15rad/8.6deg). KEEP IN MIND THAT THIS MAY CAUSE SOME PRECISION ERRORS.

source scripts/demo_piper_arm.bash