Metadata-Version: 2.4
Name: arx-x5-sdk
Version: 0.1.7
Summary: ARX X5 Robot Arm Python SDK
Author: Remi Cadene, UMA
Author-email: Remi Cadene <remi@uma.bot>, UMA <contact@uma.bot>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/uma-robots/arx-x5-sdk
Project-URL: Repository, https://github.com/uma-robots/arx-x5-sdk
Project-URL: Issues, https://github.com/uma-robots/arx-x5-sdk/issues
Keywords: robotics,arx,robot-arm,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pybind11>=2.10.0
Provides-Extra: dev
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.9; extra == "dev"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# 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)
- **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

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

```bash
pip install arx-x5-sdk
```

### Install from Source

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

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

- **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`](.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!
