Merge branch 'feat/pylibfranka_async'

Author: BarisYazici

CHANGELOG.md

@@ -7,13 +7,19 @@ All notable changes to libfranka in this file.
 #### Changed
 - Hotfix to avoid torques discontinuity false positives due to robot state float precision change.
 
+### pylibfranka - Python
+#### Added
+- Async control python bindings
+- Async joint positions control example from C++.
+
 ## [0.19.0]
 ### libfranka - C++
 #### Changed
 - To support franka_ros2, we added an option for the async position control to base the `getFeedback` function on a robot state received via `franka_hardware` instead of querying the robot directly.
 - Format libfranka debian package to inlclude ubuntu code name and arch: libfranka_VERSION_CODENAME_ARCH.deb
 - Added build containers to support Ubuntu 22.04 and 24.04
 
+
 ## [0.18.2]
 Requires Franka Research 3 System Version >= 5.9.0
 

pylibfranka/CMakeLists.txt

@@ -20,6 +20,9 @@ find_package(pinocchio REQUIRED)
 # Create Python module
 pybind11_add_module(_pylibfranka
     src/pylibfranka.cpp
+    src/async_control.cpp
+    src/gripper.cpp
+    # add more source files as needed for next splits
 )
 
 # Include directories

pylibfranka/README.md

@@ -161,3 +161,14 @@ The gripper example:
 - Attempts to grasp an object with specified parameters
 - Verifies successful grasping
 - Releases the object
+
+### Async Joint Position Control Example
+
+You can also use the async API to control the robot in a low-rate fashion, e.g. 50Hz.
+This allows you to specify joint position setpoints without the need for a blocking loop.
+
+```bash
+cd examples
+python3 async_position_control.py --ip <robot_ip> 
+```
+

pylibfranka/__init__.py

@@ -28,6 +28,7 @@
     RobotMode,
     RobotState,
     Torques,
+    AsyncPositionControlHandler
 )
 from ._version import __version__
 
@@ -55,4 +56,5 @@
     "RobotMode",
     "RobotState",
     "Torques",
+    "AsyncPositionControlHandler"
 ]

pylibfranka/examples/async_position_control.py

@@ -0,0 +1,124 @@
+# Copyright (c) 2026 Franka Robotics GmbH
+# Apache-2.0
+
+# This example demonstrates asynchronous position control of a Franka robot using the
+# pylibfranka library. It connects to the robot, sets up an asynchronous position control
+# handler, and continuously updates joint position targets in a loop until interrupted, leveraging
+# the latest low-rate control API.
+
+import signal
+import sys
+import time
+import math
+import argparse
+import threading
+from datetime import timedelta
+
+import pylibfranka as franka
+from example_common import setDefaultBehaviour
+
+kDefaultMaximumVelocities = [0.655, 0.655, 0.655, 0.655, 1.315, 1.315, 1.315]
+kDefaultGoalTolerance = 10.0
+
+motion_finished = False
+
+
+def signal_handler(sig, frame):
+    global motion_finished
+    if sig == signal.SIGINT:
+        motion_finished = True
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--ip", type=str, default="localhost", help="Robot IP address")
+    args = parser.parse_args()
+
+    signal.signal(signal.SIGINT, signal_handler)
+
+    try:
+        robot = franka.Robot(args.ip, franka.RealtimeConfig.kIgnore)
+    except Exception as e:
+        print(f"Could not connect to robot: {e}")
+        sys.exit(-1)
+
+    setDefaultBehaviour(robot)
+
+    initial_position = [0,
+                        -math.pi / 4,
+                        0,
+                        -3 * math.pi / 4,
+                        0,
+                        math.pi / 2,
+                        math.pi / 4]
+
+    time_elapsed = 0.0
+    direction = 1.0
+    time_since_last_log = 0.0
+
+    def calculate_joint_position_target(period_sec):
+        nonlocal time_elapsed, direction, time_since_last_log
+
+        time_elapsed += period_sec
+
+        target_positions = [
+            initial_position[i] + direction * 0.25
+            for i in range(7)
+        ]
+
+        time_since_last_log += period_sec
+        if time_since_last_log >= 1.0:
+            direction *= -1.0
+            time_since_last_log = 0.0
+
+        return franka.AsyncPositionControlHandler.JointPositionTarget(
+            joint_positions=target_positions
+        )
+
+    joint_position_control_configuration = \
+        franka.AsyncPositionControlHandler.Configuration(
+            maximum_joint_velocities=kDefaultMaximumVelocities,
+            goal_tolerance=kDefaultGoalTolerance
+        )
+
+    result = franka.AsyncPositionControlHandler.configure(robot,
+                                                   joint_position_control_configuration)
+
+    if result.error_message is not None:
+        print(result.error_message)
+        sys.exit(-1)
+
+    position_control_handler = result.handler
+    target_feedback = position_control_handler.get_target_feedback()
+
+    time_step = 0.020  # 20 ms, 50 Hz
+
+    global motion_finished
+    while not motion_finished:
+        loop_start = time.monotonic()
+
+        target_feedback = position_control_handler.get_target_feedback()
+        if target_feedback.error_message is not None:
+            print(target_feedback.error_message)
+            sys.exit(-1)
+
+        next_target = calculate_joint_position_target(time_step)
+        command_result = position_control_handler.set_joint_position_target(next_target)
+
+        if command_result.error_message is not None:
+            print(command_result.error_message)
+            sys.exit(-1)
+
+        if time_elapsed > 10.0:
+            position_control_handler.stop_control()
+            motion_finished = True
+            print("Control finished")
+            break
+
+        sleep_time = time_step - (time.monotonic() - loop_start)
+        if sleep_time > 0:
+            time.sleep(sleep_time)
+
+
+if __name__ == "__main__":
+    main()

pylibfranka/include/pygripper.h

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Franka Robotics GmbH
+// Use of this source code is governed by the Apache-2.0 license, see LICENSE
+
+// Expose async position control handler python bindings
+
+#pragma once
+#include <pybind11/pybind11.h>
+
+namespace py = pybind11;
+
+namespace pylibfranka {
+
+void bind_async_control(py::module& m);
+
+}

pylibfranka/include/pylibfranka.h

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Franka Robotics GmbH
+// Use of this source code is governed by the Apache-2.0 license, see LICENSE
+
+// Expose gripper-related python bindings
+
+#pragma once
+#include <pybind11/pybind11.h>
+
+namespace py = pybind11;
+
+namespace pylibfranka {
+
+void bind_gripper(py::module& m);
+
+}