arx-x5-sdk 0.1.7

ARX X5 Robot Arm Python SDK

ARX X5 SDK

Python bindings for the ARX X5 robot arm. Control ARX X5 arms via CAN interface.

Why This Package?

• Easy Installation: pip install arx-x5-sdk (no complex build steps for users)
• Minimal System Dependencies: Only needs liborocos-kdl and liburdfdom - no full ROS installation required
• Clean API: Modular, better-documented Python interface
• Production Ready: Proper package structure with comprehensive documentation

Installation

Prerequisites

# Runtime dependencies (required even when installing from PyPI)
sudo apt install liborocos-kdl-dev liburdfdom-dev

# CAN interface tools (for USB-CAN adapters)
sudo apt install can-utils

Note: The KDL URDF parser (libkdl_parser.so) is bundled in the wheel, but its dependencies (liborocos-kdl, liburdfdom) must be installed system-wide. No full ROS installation is needed.

Install from PyPI

pip install arx-x5-sdk

Install from Source

# Additional build dependencies
sudo apt install build-essential cmake python3-dev patchelf

git clone https://github.com/uma-robots/arx-x5-sdk.git
cd arx-x5-sdk
pip install .

Note: Due to CMake build requirements, editable mode (pip install -e .) is not recommended. Reinstall after changes with pip install --force-reinstall .

Quick Start

from arx_x5_sdk import ArxInterface, ArmType

# Connect to arm
arm = ArxInterface("can0", ArmType.X5_2025)

See examples/ for complete tutorials (joint control, Cartesian control, gripper, teleoperation)

Available Arm Types

ArmType.FOLLOWER                  # Follower arm
ArmType.LEADER                    # Leader/master arm  
ArmType.X5_2025                   # X5 2025 model (default)
ArmType.X5_2025_LOWER_MASS_LINK6  # X5 2025 with corrected gravity compensation

Advanced Usage

Custom URDF

from arx_x5_sdk import C_ArxInterface, get_urdf_path

urdf_path = get_urdf_path("x5_2025_lower_mass_link6.urdf")
arm = C_ArxInterface(urdf_path, "can0", 2)

Get URDF Path

from arx_x5_sdk import get_urdf_path, get_urdf_path_by_type, ArmType

# By filename
path = get_urdf_path("x5_2025.urdf")

# By arm type
path = get_urdf_path_by_type(ArmType.LEADER)

Architecture Support

• Linux x86_64: Fully supported
• macOS (Apple Silicon): Works via Rosetta 2 translation
• ARM64 (Linux) / Windows: Not currently supported

Development & Publishing

This project uses GitHub Actions for CI/CD:

• .github/workflows/build.yml - CI testing on every push/PR
• .github/workflows/publish.yml - Publish releases to PyPI (triggered by version tags)
• .github/workflows/test-publish.yml - Test publishing to TestPyPI (manual)

See each workflow file for detailed documentation on triggers, usage, and requirements.

Documentation

• Examples: examples/README.md - Getting started tutorials
• URDF files: arx_x5_sdk/urdf/README.md - Gravity compensation fixes
• Pre-built libraries: lib/arx_x5_src/README.md - Binary details

Development

Pre-commit Hooks

This project uses pre-commit hooks to maintain code quality:

# Install with dev dependencies (use uv if available for faster installs)
pip install ".[dev]"

# Run on all files
pre-commit run --all-files

The hooks automatically:

• Whitespace: Remove trailing whitespace, fix line endings (LF), ensure newlines at EOF
• File validation: Check YAML/TOML/JSON syntax, prevent large files (>1MB), detect merge conflicts
• Python code quality: Lint and format with Ruff (fast, modern alternative to black/flake8/isort)
• Security: Detect accidentally committed private keys

Troubleshooting

CAN interface setup:

sudo bash scripts/setup_can.sh /dev/ttyACM0 can0

Gravity compensation issues: Use ArmType.X5_2025_LOWER_MASS_LINK6

Author

Remi Cadene - [e-mail] - UMA

Acknowledgments

Based on the official ARX X5 Python SDK. Special thanks to the ARX Robotics team!