Skip to content

PiPER Mate AgileX ROS2 Robotic Arm Driver Documentation

Overview

This document describes how to start the ROS2 driver nodes and complete PiPER Mate control of the AgileX Piper robotic arm by sending and receiving topics.

System Requirements

  • Ubuntu 22.04
  • ROS2 Humble

Node Description

1. piper_mate Node

This node reads the servo angle information from the PiPER Mate robotic arm and converts it into the joint-state format required by the Piper arm.

2. piper_ctrl_single Node

This node controls the Piper robotic arm. It receives joint-state commands and drives the motors on the CAN bus. This is the official Piper package. For details, see Piper ROS2-HUMBLE.

Tip

After this node starts, the Piper arm runs at the default speed and does not follow at full speed. If high-speed following is required, modify the code according to the official instructions.

Installation

1. Install Dependencies

sudo pip install pyserial
sudo pip install fashionstar-uart-sdk

sudo pip install python-can
sudo pip install scipy
sudo pip install piper_sdk
sudo apt update && sudo apt install can-utils ethtool

sudo apt install ros-$ROS_DISTRO-ros2-control
sudo apt install ros-$ROS_DISTRO-ros2-controllers
sudo apt install ros-$ROS_DISTRO-controller-manager

Startup Steps

Build:

cd ROS2_HUMBLE
colcon build
source install/setup.bash

Terminal 1: Start the piper_mate Node

source install/setup.bash
sudo chmod 777 /dev/ttyUSB*
# 启动piper_mate节点 禁用力矩
ros2 run piper_mate driver --ros-args -p port:=/dev/ttyUSB0 -p auto_enable:=false

Parameter description:

  • port:=/dev/ttyUSB0: Serial Port device connected to the robotic arm
  • auto_enable:=false: manually enable torque control (set to true to lock the arm at the current position)

Expected output:

[INFO] [piper_mate_node]: 初始化FashionStar机械臂，端口: /dev/ttyUSB0
[INFO] [piper_mate_node]: 机械臂连接成功
[INFO] [piper_mate_node]: 机械臂力矩已禁用
[INFO] [piper_mate_node]: FashionStar驱动节点初始化完成

Terminal 2: Configure and Start the CAN Interface

Single CAN Device Configuration

# 1. 查找所有CAN端口
bash find_all_can_port.sh
# 2. 激活can0接口（波特率1000000）
bash can_activate.sh can0 1000000

cd ROS2_HUMBLE
source install/setup.bash
ros2 run piper piper_single_ctrl --ros-args -p can_port:=can0 -p auto_enable:=true -p gripper_exist:=true -p gripper_val_mutiple:=2

Parameter description:

  • can_port:=can0: CAN interface name to use
  • auto_enable:=true: automatically enable the motor driver
  • gripper_exist:=true: enable gripper control
  • gripper_val_mutiple:=2: gripper value multiplier (control sensitivity)

Expected output:

Both ethtool and can-utils are installed.
Interface can0 is connected to USB port 3-9.4:1.0
-------------------START-----------------------
Both ethtool and can-utils are installed.
Expected to configure a single CAN module, detected interface can0 with corresponding USB address 3-9.4:1.0.
Interface can0 is already activated with a bitrate of 1000000.
The interface name is already can0.
-------------------OVER------------------------
[INFO] [piper_ctrl_single_node]: can_port is can0
[INFO] [piper_ctrl_single_node]: auto_enable is True
[INFO] [piper_ctrl_single_node]: gripper_exist is True
[INFO] [piper_ctrl_single_node]: gripper_val_mutiple is 2
[INFO] [piper_ctrl_single_node]: --------------------
[INFO] [piper_ctrl_single_node]: Enable status:False
[INFO] [piper_ctrl_single_node]: joint1: -0.005235987755982988
[INFO] [piper_ctrl_single_node]: --------------------
[INFO] [piper_ctrl_single_node]: joint2: 0.0
[INFO] [piper_ctrl_single_node]: joint3: 0.0
[INFO] [piper_ctrl_single_node]: joint4: -0.05235987755982989
[INFO] [piper_ctrl_single_node]: joint5: -0.041887902047863905
[INFO] [piper_ctrl_single_node]: joint6: 1.6074482410867774
[INFO] [piper_ctrl_single_node]: gripper: -0.0002666666666666667

Verify System Operation

After startup, use the following commands to verify the system status:

# 查看节点列表
ros2 node list

# 查看话题列表
ros2 topic list

# 查看关节状态
ros2 topic echo /joint_ctrl_single

# 查看机械臂状态
ros2 topic echo /arm_status

Troubleshooting

Common Issue 1: CAN Interface Cannot Connect

# 检查CAN接口状态
ip link show can0

# 如果接口未启动，手动激活
sudo ip link set can0 type can bitrate 1000000
sudo ip link set up can0

Common Issue 2: Robotic Arm Connection Failed

  • Check the USB cable connection.
  • Confirm whether the port number is correct (it may be /dev/ttyUSB1, etc.).
  • Check whether the robotic arm power is on and whether the driver-board switch is turned toward the power connector side.

Safety Notes

  1. Torque control: make sure there are no obstacles around the robotic arm when starting.
  2. Limit check: make sure the robotic arm moves within a safe range.
  3. Monitor operation: closely observe the robotic arm during the first run.
  • src/piper_mate/piper_mate/piper_mate.py: FashionStar robotic arm driver node
  • src/piper/piper/piper_ctrl_single_node.py: Piper robotic arm control node
  • find_all_can_port.sh: CAN port discovery script
  • can_activate.sh: CAN interface activation script

Technical Support

If you encounter problems, check:

  1. Whether the hardware connection is normal
  2. Whether permission settings are correct
  3. Error messages in the log output
  4. Whether system dependencies are fully installed