# 松灵 Piper piper_sdk：CAN 使能与读关节角度入门

> 原文链接：https://robotics.hellobike.com/tutorials/agilex-piper-sdk-ros2-quickstart
> 频道：tutorials | 更新日期：2026-10-22 | 标签：Piper, piper_sdk, CAN, python-can, Linux
> 核心摘要：本教程按 piper_sdk 文档整理安装、CAN 工具准备、CAN 模块发现与激活、多 CAN 配置，以及读取关节角度前的接口选择要点，便于在 Linux 上逐步跑通。

# 松灵 Piper piper_sdk：CAN 使能与读关节角度入门

> 本文依据以下官方文档整理：[raw.githubusercontent.com/agilexrobotics/piper_sdk/master/RE](https://raw.githubusercontent.com/agilexrobotics/piper_sdk/master/README.MD)。命令与版本以文档当前版本为准。

## 前置条件

- Ubuntu-18.04、Ubuntu-20.04、Ubuntu-22.04
- Python-3.6、Python-3.8、Python-3.10
- python-can version should be above 3.3.4
- The CAN module here only supports the robot arm's built-in CAN module, and does not support other CAN modules.
- piper-can find 和 piper-can activate 只支持 Linux
- can-utils、ethtool；如出现 ip: command not found，需要 iproute2

## 1. 安装 python-can 与 piper_sdk

先安装依赖，再确认当前 pip3 是否在 conda environment 中。piper_sdk 提供三种安装方式，这里使用 pypi repository 方式；安装后用 show 查看详情。
```bash
pip3 install python-can
which pip3
pip3 install piper_sdk
pip3 show piper_sdk
```

## 2. 处理 piper-can 不在 PATH 的情况

若 pip 提示 piper-can installed in '/home/xxx/.local/bin' which is not on PATH，说明安装成功但脚本目录未加入 PATH。可先临时修复，再写入 ~/.bashrc，并验证帮助命令。
```bash
export PATH="$(python3 -m site --user-base)/bin:$PATH"
echo 'export PATH="$(python3 -m site --user-base)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
piper-can -h
piper-can find -h
piper-can activate -h
```

## 3. 安装 CAN 工具并发现 CAN 模块

CAN 配置需要 can-utils 与 ethtool。若执行 bash script 出现 ip: command not found，再安装 iproute2。随后运行 find；插入 CAN 模块并检测到时会输出 Interface can0 is connected to USB port 3-1.4:1.0 这类信息。
```bash
sudo apt update && sudo apt install can-utils ethtool
sudo apt-get install iproute2
piper-can find
```

## 4. 激活单个 CAN 模块

PC 只连接一个 USB-to-CAN module 时，直接激活即可。文档说明 can0 can be replaced with any name，1000000 是 baud rate，cannot be changed。激活后用 ifconfig 查看对应接口是否出现。
```bash
piper-can activate can0 1000000
```

## 5. 多模块场景下只激活机械臂 CAN

同时有 robot arm 和 chassis 时，先拔掉所有 CAN modules，只插入机械臂连接的模块并查找 USB port value，例如 3-1.4:1.0；再按该硬件 USB 端口重命名为 can_piper 并激活。
```bash
piper-can find
piper-can activate can_piper 1000000 --usb-port "3-1.4:1.0"
```

## 6. 同时激活多个 CAN 模块

在 can_muti_activate.sh 中，EXPECTED_CAN_COUNT 设置为要激活的数量。记录各 USB port 后，将 USB_PORTS 中的端口、接口名和 bitrate 改成目标值，再运行脚本。
```bash
piper-can find
USB_PORTS["3-1.4:1.0"]="can_left:1000000"
USB_PORTS["3-1.1:1.0"]="can_right:1000000"
bash can_muti_activate.sh
```

## 7. 选择读取关节角度的接口

文档的 Simple start 目标是 read the joint angle of the robot arm。使用 C_PiperInterface 的示例适用于 legacy/default interface；firmware version 1.8-8 and later 使用 C_PiperInterface_V3，例如 piper = C_PiperInterface_V3("can0")。

## 验证是否跑通

安装层面：执行 pip3 show piper_sdk 能看到 piper_sdk 信息；执行 piper-can -h、piper-can find -h、piper-can activate -h 能看到帮助。CAN 层面：piper-can find 输出 Both ethtool and can-utils are installed.，并在检测到模块时输出 Interface can0 is connected to USB port 3-1.4:1.0 这类信息。激活层面：运行 ifconfig，单模块看到 can0 或 can_piper；多模块看到 can_left 和 can_right。

## 文档里点名的注意事项

- python-can version should be above 3.3.4
- Check if you are in a conda environment
- The CAN module here only supports the robot arm's built-in CAN module, and does not support other CAN modules.
- piper-can find and piper-can activate are only supported on Linux because they rely on Linux shell scripts and CAN tools.
- If executing the bash script shows ip: command not found, install the ip command by running sudo apt-get install iproute2
- 1000000 is the baud rate, which cannot be changed.
- For firmware version 1.8-8 and later, use C_PiperInterface_V3 instead.
- 0.0.x supports SDKs for robot arm firmware versions before V1.5-2

## 相关 SDK 条目

- [piper_sdk](/sdks/agilexrobotics-piper-sdk)
- [piper_ros](/sdks/agilexrobotics-piper-ros)

## 原始参考来源 (Sources)

- [raw.githubusercontent.com/agilexrobotics/piper_sdk/master/README.MD](https://raw.githubusercontent.com/agilexrobotics/piper_sdk/master/README.MD)