libfrankapy

libfrankapy is a Python binding project for the libfranka library, designed to provide high-level Python interfaces for Franka robotic arms while maintaining the performance advantages of low-level C++ real-time control.

✨ Features

• 🚀 Real-time Performance Guarantee: C++ control loop maintains 1kHz real-time performance, Python does not participate in real-time loops
• 🐍 Python Friendly: Provides intuitive Python API with complete type hints
• ⚡ Efficient Communication: Uses shared memory and atomic operations for Python-C++ data exchange
• 🛡️ Safety Control: Complete safety limits, error handling, and emergency stop functionality

📋 System Requirements

Hardware Requirements:

• Franka Robotics robotic arm (with FCI functionality)
• Computer with PREEMPT_RT real-time kernel

Software Requirements:

• Operating System: Ubuntu 22.04+ with PREEMPT_RT real-time kernel
• Python: 3.9+
• C++ Compiler: GCC 7+ or Clang 6+
• CMake: 3.16+

🚀 Installation

Before installing libfrankapy, make sure you have installed libfranka following the libfranka repository.

Install from source

First, clone the repository:

git clone https://github.com/han-xudong/libfrankapy.git
cd libfrankapy

It's recommended to create a virtual environment (venv or conda):

python -m venv venv
source venv/bin/activate

Next, build and install the package:

pip install -e .

Install from PyPI

pip install libfrankapy

🎯 Quick Start

Here is a brief example to get you started:

import libfrankapy as fp
import numpy as np

# Connect to robot
robot = fp.FrankaRobot("192.168.1.100")  # Replace with your robot IP
robot.connect()
robot.start_control()

try:
    # Get current state
    state = robot.get_robot_state()
    print(f"Current joint positions: {state.joint_state.positions}")
    print(f"Current end-effector pose: {state.cartesian_pose.position}")

    # Joint space motion
    target_joints = [0.0, -0.785, 0.0, -2.356, 0.0, 1.571, 0.785]
    robot.move_to_joint(target_joints, speed_factor=0.1)

    # Cartesian space motion
    target_pose = [0.5, 0.0, 0.5, 0.0, 0.0, 0.0, 1.0]  # [x, y, z, qx, qy, qz, qw]
    robot.move_to_pose(target_pose, speed_factor=0.1)

finally:
    # Disconnect
    robot.disconnect()

See the examples/ directory for more usage examples:

• basic_control.py - Basic control example
• trajectory_control.py - Trajectory control example
• state_monitoring.py - Real-time state monitoring example

Note: When using this library to control robotic arms, please ensure you follow all safety protocols and test in a controlled environment.

🏗️ Architecture Design

libfrankapy adopts a hybrid architecture of C++ real-time environment + Python high-level interface:

graph TD
    A[Python Application Layer] --> B[libfrankapy Python API]
    B --> C[Pybind11 Binding Layer]
    C --> D[C++ Control Manager]
    D --> E[Shared Memory Communication]
    E --> F[Real-time Control Thread]
    F --> G[LibFranka C++ Library]
    G --> H[Franka Robotic Arm Hardware]
    E --> I[Shared Memory Reader]
    I --> B
    J[RealtimeConfig] --> D

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8
    style E fill:#fff9c4
    style F fill:#ffebee
    style G fill:#f1f8e9
    style H fill:#fce4ec
    style I fill:#e8eaf6
    style J fill:#f3e5f5

🤝 Contributing

We welcome community contributions! Please see CONTRIBUTING.md for details on how to participate in project development.

Development Environment Setup

# Clone repository
git clone https://github.com/han-xudong/libfrankapy.git
cd libfrankapy

# Create development environment
python3 -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

📄 License

This project is licensed under the Apache License 2.0.

🙏 Acknowledgments

• Franka Robotics for providing excellent robotic arm hardware and the libfranka library
• pybind11 for providing excellent Python-C++ binding tools
• All developers who have contributed to this project

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🔗 Related Links

• libfranka Official Documentation
• Franka Control Interface (FCI) Documentation
• Real-time Kernel Installation Guide