🚀 Quick Start
Environment Requirements
| Item | Requirement |
|---|---|
| Operating system | Ubuntu 22.04 |
| ROS version | ROS2 Humble |
| Hardware device | PiPER Mate robotic arm + Piper robotic arm |
| Driver | CH340 USB Driver |
Installation Steps
Method 1: Python SDK (recommended for beginners)
# 1. 安装依赖
sudo apt update && sudo apt install can-utils ethtool
sudo pip install serial fashionstar-uart-sdk piper-sdk python-can scipy
# 2. 配置CAN接口
cd piper-mate
bash find_all_can_port.sh
bash can_activate.sh can0 1000000
# 3. 运行程序
sudo chmod 777 /dev/ttyUSB*
python3 ./Python_SDK/piper_pipermate.py
Method 2: ROS2 HUMBLE
# 1. 安装ROS2依赖
cd ROS2_HUMBLE
colcon build
source install/setup.bash
# 2. 启动节点（需要两个终端）
# 终端1：启动PiPER Mate驱动
ros2 run piper-mate driver --ros-args -p port:=/dev/ttyUSB0 -p auto_enable:=false
# 终端2：启动Piper控制
bash can_activate.sh can0 1000000
ros2 run piper piper_single_ctrl --ros-args -p can_port:=can0 -p auto_enable:=true
Method 3: Lerobot Framework
# 参考Lerobot/README.md配置说明
📂 Project Structure
PiPER-Mate/
├── Python_SDK/ # Python SDK控制方式
│ ├── piper_pipermate.py # 主控制程序
│ └── README.md # 详细使用文档
├── ROS2_HUMBLE/ # ROS2控制方式
│ ├── src/piper/ # Piper驱动节点
│ ├── src/piper-mate/ # Piper_mate驱动节点
│ ├── src/piper_msgs/ # Piper消息定义
│ └── README.md # ROS2使用文档
├── Lerobot/ # Lerobot框架控制方式
│ ├── lerobot_robot_piper/ # Piper机器人配置
│ ├── lerobot_teleoperator_pipermate/ # 遥操作器
│ └── piper-star_en.md # Lerobot使用文档（英文）
│ └── piper-star.md # Lerobot使用文档
│ └── README.md # 使用步骤
├── can_activate.sh # CAN接口激活（根目录）
├── can_config.sh # CAN接口配置
└── README.md # 本文档
🎯 Control Method Comparison
| Feature | Python SDK | ROS2 HUMBLE | Lerobot |
|---|---|---|---|
| Difficulty | ⭐ Easy | ⭐⭐⭐ Medium | ⭐⭐⭐⭐⭐ Complex |
| Real-time performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| Extensibility | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Application scenarios | Quick testing and teaching | Robot system integration | AI training and research |
🔧 Hardware Connection
Connection Topology
┌─────────────────┐ USB ┌─────────────────┐
│ │◄────────────────────►│ │
│ PiPER Mate │ │ 计算机 │
│ 机械臂 │ │ (Ubuntu 22.04) │
└─────────────────┘ └────────┬────────┘
│
USB
│
┌─────────────────┐ CAN ┌────────┴────────┐
│ │◄────────────────────►│ │
│ Piper │ │ CAN转USB适配器 │
│ 机械臂 │ │ │
└─────────────────┘ └─────────────────┘
📊 Joint Mapping
The system automatically maps the 6 joints of PiPER Mate to the Piper robotic arm:
| Joint | PiPER Mate Angle | Piper Radian | Direction |
|---|---|---|---|
| Joint1 | -150° ~ 150° | -2.62 ~ 2.62 rad | Reversed |
| Joint2 | 0° ~ 180° | 0 ~ 3.14 rad | Forward |
| Joint3 | -170° ~ 0° | -2.97 ~ 0 rad | Forward |
| Joint4 | -100° ~ 100° | -1.75 ~ 1.75 rad | Reversed |
| Joint5 | -70° ~ 70° | -1.22 ~ 1.22 rad | Forward |
| Joint6 | -120° ~ 120° | -2.09 ~ 2.09 rad | Reversed |
⚠️ Safety Notes
- Pre-operation check: make sure there are no obstacles around the robotic arm and that the workspace is safe.
- Emergency stop control: press
Ctrl+Cwhile the program is running to stop immediately. - Joint limits: the system automatically sets safe angle limits to avoid out-of-range motion.
- Power management: make sure the robotic arm power supply is stable to avoid voltage fluctuations.
🐛 Troubleshooting
Common Issues
Q1: Cannot find the /dev/ttyUSB0 device?
# 检查USB设备
ls -l /dev/ttyUSB*
# 检查CH340驱动
lsusb | grep CH340
# 如果没有安装驱动，请从官网下载安装
Q2: CAN interface cannot be activated?
# 查找CAN端口
bash find_all_can_port.sh
# 手动激活CAN接口
sudo ip link set can0 type can bitrate 1000000
sudo ip link set up can0
# 检查CAN接口状态
ip link show can0
Q3: Robotic arm connection failed?
- Check whether the USB cable connection is loose.
- Confirm that the robotic arm power is on.
- Check the driver-board switch position. It should be turned toward the power connector side.
- Try another USB port.
Q4: The program does not terminate when the USB connection is disconnected?
Exception handling has been added. When the PiPER Mate USB is disconnected, the program automatically terminates and displays an error message:
❌ 致命错误：PiPER Mate USB连接断开！
📖 Detailed Documentation
Select the control method you need and view the detailed documentation:
- 📘 Python SDK Detailed Documentation - recommended, easiest to use
- 📗 ROS2 HUMBLE Detailed Documentation - suitable for robot system integration
- 📙 Lerobot Detailed Documentation - suitable for AI training and research
📄 License
This project is open source under the MIT License.
👥 Authors and Acknowledgements
- Project maintainer: Welt-liu
- Thanks to: the PiPER Mate and Piper teams for hardware support
🔗 Related Links
-
Project maintainer:
-
Thanks to: the PiPER Mate and Piper teams for hardware support
3. Specifications
3.1. Basic Parameters
| Parameter Item | Technical Specification |
|---|---|
| Operating Voltage | 9.0-12.6 V |
| Motor Type | Coreless Motor |
| Position Sensor | 12-bit Contactless Absolute Encoder |
| Resolution | 4096 steps / 360° (0.088°) |
| Effective Angle | ±180° (single-turn) / ±368,640° (multi-turn) |
| Processor | 32-bit MCU |
| Communication Type | UART / TTL Half-Duplex |
| Baud Rate | 9,600 bps-1 Mbps |
| ID Range | 0-254 |
| Reduction Ratio | 273:1 |
| Gear Material | All-Metal Stainless Steel Combination |
| Output Shaft Specification | Stainless Steel / Ø6 mm / 25T |
| Housing Material | Aluminum Alloy Middle Case / Engineering Plastic Upper and Lower Covers |
| Interface Type | PH2.0 - 3Pin |
| Dimensions and Weight | 40 x 20 x 40 mm / 73 g |
| Operating Temperature | -10-60 ℃ |
| Operating Modes | Single-Turn Angle | Multi-Turn Angle | Damping Mode |
3.2. Performance Parameters (@12V)
| Parameter Item | Specification |
|---|---|
| Maximum Static Torque (Stall) | 4.41 N·m (45 kg·cm) |
| Maximum Dynamic Torque | 1.67 N·m (17 kg·cm) |
| Rated Torque | 0.54 N·m (5.5 kg·cm) |
| Rated Speed | 64 rpm (0.156 s / 60°) |
| No-Load Speed | 90 rpm (0.110 s / 60°) |
| Peak Current | 6 A |
| No-Load Current | <300 mA |
| Static Current | <30 mA |
| Axial | 20 N |
| Radial | 40 N |
T-N Characteristic Curve
Mechanical Overload Curve