arx-x5-sdk 0.1.6
ARX X5 Robot Arm Python SDK
Requires Python: >=3.10
Keywords: robotics, arx, robot-arm, sdk

# ARX X5 SDK

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

[![PyPI](https://img.shields.io/pypi/v/arx-x5-sdk)](https://pypi.org/project/arx-x5-sdk/)
[![Build](https://github.com/uma-robots/arx-x5-sdk/actions/workflows/build.yml/badge.svg)](https://github.com/uma-robots/arx-x5-sdk/actions/workflows/build.yml)
[![Python](https://img.shields.io/pypi/pyversions/arx-x5-sdk)](https://pypi.org/project/arx-x5-sdk/)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
[![UMA](https://img.shields.io/badge/🤖-UMA-purple)](https://uma.bot)

## Why This Package?

- **Easy Installation**: `pip install arx-x5-sdk` (no complex build steps for users)
- **Bundled Dependencies**: Includes necessary libraries - no ROS installation required
- **Clean API**: Modular, better-documented Python interface
- **Production Ready**: Proper package structure with comprehensive documentation

## Installation

### Prerequisites

```bash
# Build and runtime dependencies
sudo apt install build-essential cmake python3-dev patchelf liborocos-kdl-dev liburdfdom-dev

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

> **Note**: KDL URDF parser is bundled - no ROS installation needed!

### Install from Source

```bash
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

```python
from arx_x5_sdk import ArxInterface, ArmType

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

**See [`examples/`](examples/) for complete tutorials** (joint control, Cartesian control, gripper, teleoperation)

### Available Arm Types

```python
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

```python
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

```python
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

- **x86_64**: Fully supported
- **ARM64**: Supported (may have verbose output)

## Development & Publishing

This project uses GitHub Actions for CI/CD:

- **[`.github/workflows/build.yml`](.github/workflows/build.yml)** - CI testing on every push/PR
- **[`.github/workflows/publish.yml`](.github/workflows/publish.yml)** - Publish releases to PyPI (triggered by version tags)
- **[`.github/workflows/test-publish.yml`](.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`](examples/README.md) - Getting started tutorials
- **URDF files**: [`arx_x5_sdk/urdf/README.md`](arx_x5_sdk/urdf/README.md) - Gravity compensation fixes
- **Pre-built libraries**: [`lib/arx_x5_src/README.md`](lib/arx_x5_src/README.md) - Binary details

## Development

### Pre-commit Hooks

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

```bash
# 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:**
```bash
sudo bash scripts/setup_can.sh /dev/ttyACM0 can0
```

**Gravity compensation issues:** Use `ArmType.X5_2025_LOWER_MASS_LINK6`

## Author

**Remi Cadene** - [remi@uma.bot](mailto:remi@uma.bot) - [UMA](https://uma.bot)

## Acknowledgments

Based on the [official ARX X5 Python SDK](https://github.com/ARXroboticsX/ARX_X5). Special thanks to the ARX Robotics team!