pyAgxArm User Guide

August 26, 2026 · View on GitHub

pyAgxArm is a Python SDK for AgileX robotic arms and end effectors. It supports CAN communication, status reading, motion control, and end-effector control for Piper, Nero, AgxGripper, and Revo2.

Table of Contents

Environment

  • Ubuntu: 18.04 / 20.04 / 22.04 / 24.04
  • Windows: 10 / 11
  • macOS (Darwin)
  • Python: 3.6 and above (compatible up to 3.14)

Documentation

TopicLink
GitHub DiscussionsAll · Announcements · General · Q&A
ROSagx_arm_ros
Piper APIdocs/piper/piper_api.md
Nero APIdocs/nero/nero_api.md
AgxGripper APIdocs/effector/agx_gripper/agx_gripper_api.md
Revo2 APIdocs/effector/revo2/revo2_api.md
Revo2 Pro / Touch APIdocs/effector/revo2_pro_touch/revo2_pro_touch_api.md
CAN module manualdocs/can_user.md
Nero first-time CAN guidedocs/nero/first_time_user_guide_can.md
WSL2 USB-CAN guidedocs/wsl2_usb_can_guide.md
Ubuntu 24.04 pip guidedocs/ubuntu_24_04_pip_install.md
ChangelogCHANGELOG.md
DemospyAgxArm/demos

Install

pip3 install python-can

python-can should be newer than 3.3.4.

If you want to use this SDK on Windows, you must install the python-can-agx-cando plugin and use the agx_cando interface. The recommended way is:

pip3 install "git+https://github.com/agilexrobotics/python-can-agx-cando.git"

You can also clone the repository and install it locally:

git clone https://github.com/agilexrobotics/python-can-agx-cando.git
cd python-can-agx-cando
pip3 install .

Then install pyAgxArm. The recommended way is to install directly from GitHub:

pip3 install "git+https://github.com/agilexrobotics/pyAgxArm.git"

You can also clone the repository and install it locally:

git clone https://github.com/agilexrobotics/pyAgxArm.git
cd pyAgxArm
pip3 install .

Ubuntu 24.04 users can also refer to: docs/ubuntu_24_04_pip_install.md

Communication Setup

See: docs/can_user.md

Quick Start

Assume default channel values in this quick-start example:

  • Windows: interface="agx_cando", channel="0"
  • Linux: interface="socketcan", channel="can0"
  • macOS: interface="slcan", channel="/dev/ttyACM0"

Prerequisites before running:

  • Linux: activate CAN first (for example: sudo ip link set can0 up type can bitrate 1000000)
  • Linux: you can also use our shell scripts in CAN module manual - Activate a Single CAN Module
  • macOS: grant serial permission first (sudo chmod 777 /dev/ttyACM0)
import time
from platform import system
from pyAgxArm import create_agx_arm_config, AgxArmFactory, ArmModel, NeroFW

# Nero firmware: <= 1.10 → DEFAULT; 1.11 → V111; 1.12 → V112; 1.20 → V120; >= 1.21 → V121.
platform_system = system()
if platform_system == "Windows":
    interface = "agx_cando"
    channel = "0"
elif platform_system == "Linux":
    interface = "socketcan"
    channel = "can0"
elif platform_system == "Darwin":
    interface = "slcan"
    channel = "/dev/ttyACM0"
else:
    raise RuntimeError("pyAgxArm currently documents Linux `socketcan`, Windows `agx_cando`, and macOS `slcan`.")

cfg = create_agx_arm_config(
    robot=ArmModel.NERO,
    firmeware_version=NeroFW.DEFAULT,
    interface=interface,
    channel=channel,
)
robot = AgxArmFactory.create_arm(cfg)
robot.connect()

while True:
    ja = robot.get_joint_angles()
    if ja is not None:
        print(ja.msg)
        print(ja.hz, ja.timestamp)
    time.sleep(0.005)

Notes

  • Activate CAN first and configure the correct bitrate before reading or controlling the arm.
  • On Windows, interface="agx_cando" requires the separately installed python-can-agx-cando plugin.
  • On macOS (Darwin), grant serial-port permission before using interface="slcan".
  • MIT single-joint control is an advanced feature; improper use may damage the robot.

Contact

pyAgxArm 使用说明

pyAgxArm 是 AgileX 机械臂与末端执行器的 Python SDK，支持 CAN 通信、状态读取、运动控制，以及 Piper、Nero、AgxGripper、Revo2 等设备的接口调用。

目录

环境支持

  • Ubuntu：18.04 / 20.04 / 22.04 / 24.04
  • Windows：10 / 11
  • macOS (Darwin)
  • Python：3.6 及以上（目前适配至 3.14）

文档入口

说明文档
GitHub 讨论区全部 · 公告 · 综合 · 问答
ROSagx_arm_ros
Piper APIdocs/piper/piper_api.md
Nero APIdocs/nero/nero_api.md
AgxGripper APIdocs/effector/agx_gripper/agx_gripper_api.md
Revo2 APIdocs/effector/revo2/revo2_api.md
Revo2 Pro / Touch APIdocs/effector/revo2_pro_touch/revo2_pro_touch_api.md
CAN 模块手册docs/can_user.md
Nero 首次使用 CAN 指南docs/nero/first_time_user_guide_can.md
WSL2 USB-CAN 使用指南docs/wsl2_usb_can_guide.md
Ubuntu 24.04 pip 安装说明docs/ubuntu_24_04_pip_install.md
更新日志CHANGELOG.md
示例代码pyAgxArm/demos

安装方法

pip3 install python-can

python-can 版本应高于 3.3.4。

如果你想在 Windows 上使用本 SDK，必须先安装 python-can-agx-cando 插件，并使用 agx_cando 接口。推荐直接安装：

pip3 install "git+https://github.com/agilexrobotics/python-can-agx-cando.git"

也可以克隆源码后在本地安装：

git clone https://github.com/agilexrobotics/python-can-agx-cando.git
cd python-can-agx-cando
pip3 install .

然后再安装 pyAgxArm。推荐直接通过 GitHub 安装：

pip3 install "git+https://github.com/agilexrobotics/pyAgxArm.git"

也可以克隆源码后在本地安装：

git clone https://github.com/agilexrobotics/pyAgxArm.git
cd pyAgxArm
pip3 install .

Ubuntu 24.04 可参考： docs/ubuntu_24_04_pip_install.md

通信激活

详见： docs/can_user.md

快速开始

本节快速示例按“默认通道”假设：

  • Windows：interface="agx_cando"，channel="0"
  • Linux：interface="socketcan"，channel="can0"
  • macOS：interface="slcan"，channel="/dev/ttyACM0"

运行前前置条件：

  • Linux：先激活 CAN（例如：sudo ip link set can0 up type can bitrate 1000000）
  • Linux：也可使用我们提供的脚本，见 CAN 模块手册 - 激活单个 CAN 模块
  • macOS：先给串口权限（sudo chmod 777 /dev/ttyACM0）
import time
from platform import system
from pyAgxArm import create_agx_arm_config, AgxArmFactory, ArmModel, NeroFW

# Nero 固件：≤ 1.10 选 DEFAULT；1.11 选 V111；1.12 选 V112；1.20 选 V120；≥ 1.21 选 V121。
platform_system = system()
if platform_system == "Windows":
    interface = "agx_cando"
    channel = "0"
elif platform_system == "Linux":
    interface = "socketcan"
    channel = "can0"
elif platform_system == "Darwin":
    interface = "slcan"
    channel = "/dev/ttyACM0"
else:
    raise RuntimeError("pyAgxArm 当前公开说明包含 Linux `socketcan`、Windows `agx_cando` 与 macOS `slcan`。")

cfg = create_agx_arm_config(
    robot=ArmModel.NERO,
    firmeware_version=NeroFW.DEFAULT,
    interface=interface,
    channel=channel,
)
robot = AgxArmFactory.create_arm(cfg)
robot.connect()

while True:
    ja = robot.get_joint_angles()
    if ja is not None:
        print(ja.msg)
        print(ja.hz, ja.timestamp)
    time.sleep(0.005)

注意事项

  • 使用 CAN 协议时，需要先激活 CAN 设备并设置正确波特率。
  • Windows 下使用 interface="agx_cando" 前，需要先单独安装 python-can-agx-cando 插件。
  • macOS（Darwin）下使用 interface="slcan" 前，需要先给予串口权限。
  • MIT 单关节控制属于高级功能，使用不当可能损坏机械臂。

联系我们