# ARX R5 SDK for Python
Python SDK for controlling ARX R5 robot arms via CAN interface on Linux systems.
## System Requirements
- **Operating System**: Ubuntu 22.04 LTS or Ubuntu 24.04 LTS
- **Python**: 3.10, 3.11, or 3.12
- **Hardware**: ARX R5 robot arm with CAN interface
- **Architecture**: x86_64 or ARM64/aarch64
## Prerequisites
### 1. System Dependencies
All users must install these system dependencies before installing the package:
```bash
# Update package list
sudo apt update
# Install CAN utilities (required for robot communication)
sudo apt install can-utils net-tools
# Install build tools (required for pip installation)
sudo apt install cmake build-essential
```
### 2. Install pybind11 globally
The package requires pybind11 to be installed globally via CMake:
```bash
# Clone and install pybind11
git clone https://github.com/pybind/pybind11.git
cd pybind11
mkdir build && cd build
cmake .. -DPYBIND11_TEST=OFF
make -j4
sudo make install
cd ../..
rm -rf pybind11 # Clean up
```
## Installation
### Install from PyPI
**Note**: This package is distributed as source only. The installation will compile C++ extensions on your system.
```bash
# Install Python dependencies
pip install numpy
# Install the package (this will compile during installation)
pip install vassar-arx-r5-sdk
```
The installation process will:
- Download the source package
- Compile the C++ Python bindings
- Install the package with pre-built ARM libraries
### Install from Source
```bash
git clone https://github.com/vassar-robotics/arx-r5-sdk.git
cd arx-r5-sdk
pip install .
```
## Usage
### Basic Example - Single Arm Control
```python
from vassar_arx_r5_sdk.bimanual import SingleArm
import numpy as np
# Configure the robot arm
arm_config = {
"can_port": "can0", # or "can1" depending on your setup
"type": 0, # 0 for X5liteaa0, other values for R5_master
"num_joints": 7, # Number of joints (default: 7)
"dt": 0.05 # Control time step in seconds (default: 0.05)
}
# Initialize the arm
arm = SingleArm(arm_config)
# Move to home position
arm.go_home()
# Control via joint positions
positions = [0.0, 0.5, -0.5, 0.0, 0.0, 0.0] # 6 joint angles
arm.set_joint_positions(positions)
# Control via end-effector pose
position = np.array([0.3, 0.0, 0.2]) # x, y, z in meters
quaternion = np.array([1.0, 0.0, 0.0, 0.0]) # w, x, y, z
arm.set_ee_pose(pos=position, quat=quaternion)
# Get current state
joint_positions = arm.get_joint_positions()
joint_velocities = arm.get_joint_velocities()
ee_pose = arm.get_ee_pose() # Returns [x, y, z, w, x, y, z]
# Enable gravity compensation mode
arm.gravity_compensation()
```
### Dual Arm Control
```python
from vassar_arx_r5_sdk.bimanual import BimanualArm
# Configure both arms
left_arm_config = {
"can_port": "can0",
"type": 0
}
right_arm_config = {
"can_port": "can1",
"type": 0
}
# Initialize bimanual system
bimanual = BimanualArm(left_arm_config, right_arm_config)
# Move both arms to home
bimanual.go_home()
# Control both arms
positions = {
"left": [0.0, 0.5, -0.5, 0.0, 0.0, 0.0],
"right": [0.0, -0.5, 0.5, 0.0, 0.0, 0.0]
}
bimanual.set_joint_positions(positions)
```
### Keyboard Control Example
See the examples directory for a complete keyboard control implementation.
## Important Notes
### Safety
1. **Always use Ctrl+C to stop the program** - Never close the terminal directly
2. Avoid controlling the robot at workspace boundaries to prevent singularities
3. The robot will stop automatically when joint limits are exceeded
### CAN Setup
Before running, ensure your CAN interface is properly configured:
```bash
sudo ip link set can0 up type can bitrate 1000000
```
### Installation Troubleshooting
| Issue | Solution |
|-------|----------|
| CMake not found error | Install with `sudo apt install cmake` |
| pybind11 not found | Follow the pybind11 installation steps in Prerequisites |
| Python.h not found | Install python3-dev package (e.g., `sudo apt install python3.10-dev`) |
| Build fails during pip install | Ensure all prerequisites are installed, check gcc/g++ version |
| Permission denied errors | Use `sudo` for system-wide installation or use virtual environment |
### Runtime Troubleshooting
| Issue | Solution |
|-------|----------|
| Robot arm falls or unresponsive | Check for "safe mode" message, power cycle if needed |
| CAN port won't open | Check connections, replug USB, re-enable CAN interface |
| Motor connection failed | Reconnect base connector |
| Program stuck at initialization | Ensure sufficient USB bandwidth, avoid sharing with WiFi dongles |
## Why Source Distribution Only?
This package is distributed as source code (sdist) rather than pre-built wheels because:
1. **Hardware-specific libraries**: The package includes pre-compiled ARM control libraries (`.so` files) that are specific to the robot hardware
2. **Platform compatibility**: PyPI only accepts manylinux wheels for Linux, not platform-specific wheels (like `linux_x86_64`)
3. **Build customization**: Compiling from source ensures compatibility with your specific system configuration
This means pip will compile the C++ extensions during installation, which is why the build dependencies are required.
## Examples
Complete example scripts are included in the package:
- `test_single_arm.py` - Basic single arm control
- `test_dual_arm.py` - Dual arm coordination
- `test_keyboard.py` - Interactive keyboard control
- `test_kinematic_solver.py` - Kinematic solver usage
## License
This package is distributed under the BSD-3-Clause License. See LICENSE file for details.
## Credits
Original SDK by [ARXrobotics](https://github.com/ARXroboticsX/R5)
Packaged for PyPI by Vassar
Raw data
{
"_id": null,
"home_page": "https://github.com/ARXroboticsX/R5",
"name": "vassar-arx-r5-sdk",
"maintainer": "Vassar",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "robotics, robot arm, ARX, R5, control",
"author": "ARXrobotics",
"author_email": "ARXrobotics <contact@arx-x.com>",
"download_url": "https://files.pythonhosted.org/packages/c1/87/48673023bcdf661d1e74aa1ac57b9b1826d112b12b8e12fd9dbfbd1f9fa0/vassar-arx-r5-sdk-0.2.2.tar.gz",
"platform": null,
"description": "# ARX R5 SDK for Python\n\nPython SDK for controlling ARX R5 robot arms via CAN interface on Linux systems.\n\n## System Requirements\n\n- **Operating System**: Ubuntu 22.04 LTS or Ubuntu 24.04 LTS\n- **Python**: 3.10, 3.11, or 3.12\n- **Hardware**: ARX R5 robot arm with CAN interface\n- **Architecture**: x86_64 or ARM64/aarch64\n\n## Prerequisites\n\n### 1. System Dependencies\n\nAll users must install these system dependencies before installing the package:\n\n```bash\n# Update package list\nsudo apt update\n\n# Install CAN utilities (required for robot communication)\nsudo apt install can-utils net-tools\n\n# Install build tools (required for pip installation)\nsudo apt install cmake build-essential\n```\n\n### 2. Install pybind11 globally\n\nThe package requires pybind11 to be installed globally via CMake:\n\n```bash\n# Clone and install pybind11\ngit clone https://github.com/pybind/pybind11.git\ncd pybind11\nmkdir build && cd build\ncmake .. -DPYBIND11_TEST=OFF\nmake -j4\nsudo make install\ncd ../..\nrm -rf pybind11 # Clean up\n```\n\n## Installation\n\n### Install from PyPI\n\n**Note**: This package is distributed as source only. The installation will compile C++ extensions on your system.\n\n```bash\n# Install Python dependencies\npip install numpy\n\n# Install the package (this will compile during installation)\npip install vassar-arx-r5-sdk\n```\n\nThe installation process will:\n- Download the source package\n- Compile the C++ Python bindings\n- Install the package with pre-built ARM libraries\n\n### Install from Source\n\n```bash\ngit clone https://github.com/vassar-robotics/arx-r5-sdk.git\ncd arx-r5-sdk\npip install .\n```\n\n## Usage\n\n### Basic Example - Single Arm Control\n\n```python\nfrom vassar_arx_r5_sdk.bimanual import SingleArm\nimport numpy as np\n\n# Configure the robot arm\narm_config = {\n \"can_port\": \"can0\", # or \"can1\" depending on your setup\n \"type\": 0, # 0 for X5liteaa0, other values for R5_master\n \"num_joints\": 7, # Number of joints (default: 7)\n \"dt\": 0.05 # Control time step in seconds (default: 0.05)\n}\n\n# Initialize the arm\narm = SingleArm(arm_config)\n\n# Move to home position\narm.go_home()\n\n# Control via joint positions\npositions = [0.0, 0.5, -0.5, 0.0, 0.0, 0.0] # 6 joint angles\narm.set_joint_positions(positions)\n\n# Control via end-effector pose\nposition = np.array([0.3, 0.0, 0.2]) # x, y, z in meters\nquaternion = np.array([1.0, 0.0, 0.0, 0.0]) # w, x, y, z\narm.set_ee_pose(pos=position, quat=quaternion)\n\n# Get current state\njoint_positions = arm.get_joint_positions()\njoint_velocities = arm.get_joint_velocities()\nee_pose = arm.get_ee_pose() # Returns [x, y, z, w, x, y, z]\n\n# Enable gravity compensation mode\narm.gravity_compensation()\n```\n\n### Dual Arm Control\n\n```python\nfrom vassar_arx_r5_sdk.bimanual import BimanualArm\n\n# Configure both arms\nleft_arm_config = {\n \"can_port\": \"can0\",\n \"type\": 0\n}\n\nright_arm_config = {\n \"can_port\": \"can1\",\n \"type\": 0\n}\n\n# Initialize bimanual system\nbimanual = BimanualArm(left_arm_config, right_arm_config)\n\n# Move both arms to home\nbimanual.go_home()\n\n# Control both arms\npositions = {\n \"left\": [0.0, 0.5, -0.5, 0.0, 0.0, 0.0],\n \"right\": [0.0, -0.5, 0.5, 0.0, 0.0, 0.0]\n}\nbimanual.set_joint_positions(positions)\n```\n\n### Keyboard Control Example\n\nSee the examples directory for a complete keyboard control implementation.\n\n## Important Notes\n\n### Safety\n\n1. **Always use Ctrl+C to stop the program** - Never close the terminal directly\n2. Avoid controlling the robot at workspace boundaries to prevent singularities\n3. The robot will stop automatically when joint limits are exceeded\n\n### CAN Setup\n\nBefore running, ensure your CAN interface is properly configured:\n```bash\nsudo ip link set can0 up type can bitrate 1000000\n```\n\n### Installation Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| CMake not found error | Install with `sudo apt install cmake` |\n| pybind11 not found | Follow the pybind11 installation steps in Prerequisites |\n| Python.h not found | Install python3-dev package (e.g., `sudo apt install python3.10-dev`) |\n| Build fails during pip install | Ensure all prerequisites are installed, check gcc/g++ version |\n| Permission denied errors | Use `sudo` for system-wide installation or use virtual environment |\n\n### Runtime Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Robot arm falls or unresponsive | Check for \"safe mode\" message, power cycle if needed |\n| CAN port won't open | Check connections, replug USB, re-enable CAN interface |\n| Motor connection failed | Reconnect base connector |\n| Program stuck at initialization | Ensure sufficient USB bandwidth, avoid sharing with WiFi dongles |\n\n## Why Source Distribution Only?\n\nThis package is distributed as source code (sdist) rather than pre-built wheels because:\n\n1. **Hardware-specific libraries**: The package includes pre-compiled ARM control libraries (`.so` files) that are specific to the robot hardware\n2. **Platform compatibility**: PyPI only accepts manylinux wheels for Linux, not platform-specific wheels (like `linux_x86_64`)\n3. **Build customization**: Compiling from source ensures compatibility with your specific system configuration\n\nThis means pip will compile the C++ extensions during installation, which is why the build dependencies are required.\n\n## Examples\n\nComplete example scripts are included in the package:\n- `test_single_arm.py` - Basic single arm control\n- `test_dual_arm.py` - Dual arm coordination\n- `test_keyboard.py` - Interactive keyboard control\n- `test_kinematic_solver.py` - Kinematic solver usage\n\n## License\n\nThis package is distributed under the BSD-3-Clause License. See LICENSE file for details.\n\n## Credits\n\nOriginal SDK by [ARXrobotics](https://github.com/ARXroboticsX/R5)\n\nPackaged for PyPI by Vassar\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Python SDK for ARX R5 Robot Arm Control",
"version": "0.2.2",
"project_urls": {
"Bug Reports": "https://github.com/ARXroboticsX/R5/issues",
"Homepage": "https://github.com/ARXroboticsX/R5",
"Source": "https://github.com/ARXroboticsX/R5"
},
"split_keywords": [
"robotics",
" robot arm",
" arx",
" r5",
" control"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c18748673023bcdf661d1e74aa1ac57b9b1826d112b12b8e12fd9dbfbd1f9fa0",
"md5": "73bf666d9c0d0c471422948436e87254",
"sha256": "54e7a8778e73c39daad4603434bdea372ad7808b6d526a37a3d8e0220f826e79"
},
"downloads": -1,
"filename": "vassar-arx-r5-sdk-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "73bf666d9c0d0c471422948436e87254",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10877961,
"upload_time": "2025-08-07T00:28:52",
"upload_time_iso_8601": "2025-08-07T00:28:52.681823Z",
"url": "https://files.pythonhosted.org/packages/c1/87/48673023bcdf661d1e74aa1ac57b9b1826d112b12b8e12fd9dbfbd1f9fa0/vassar-arx-r5-sdk-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 00:28:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ARXroboticsX",
"github_project": "R5",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "vassar-arx-r5-sdk"
}
JSON
