Crate franka 

A pure-Rust client for the Franka Control Interface (FCI), the 1 kHz realtime protocol a Franka robot’s control box speaks over Ethernet.

Supported robots

• Franka Research 3 — FCI v10, mirroring libfranka 0.21.2.
• Franka Emika Robot (FER) — FCI v5, mirroring libfranka 0.9.2.

The version is negotiated during the Connect handshake (VersionPolicy): Robot probes v10 first and falls back to v5 when the control box rejects it and reports version 5, so the same binary drives either arm. Every byte-level difference is funnelled through wire::robot::codec; nothing above it names a protocol version.

Four ways to control the robot

1. Callbacks — Robot::control_joint_positions and its siblings run libfranka’s ControlLoop: your closure is called once per millisecond and returns the next setpoint (see the robot module).
2. ActiveControl — Robot::start_torque_control and its siblings hand back a ActiveTorqueControl / ActiveMotionGenerator handle you drive yourself with read_once / write_once (see robot::active_control).
3. Target control — Robot::start_cartesian_target_control and Robot::start_joint_target_control run the loop on a thread of their own and hand back a CartesianTargetControl / JointTargetControl whose set_position / set_joints any low-rate commander can call at any time; the loop turns the steps into a smooth, limit-respecting command (see robot::target_control).
4. Read-only — Robot::read_once and Robot::read stream RobotState without commanding anything.

Model and gripper

Model answers forward kinematics, both Jacobians, the mass matrix, Coriolis and gravity. It runs on a native URDF-based backend by default and can also load the robot’s own libfcimodels shared object (Robot::load_model_from_robot). Gripper is the separate Franka Hand client, on its own TCP/UDP session.

Realtime requirements

A control loop must complete within 1 ms. RealtimeConfig::Enforce (libfranka’s default) raises the calling thread to the highest SCHED_FIFO priority and fails when it cannot; run on a PREEMPT_RT kernel with the process allowed to set realtime priorities. RealtimeConfig::Ignore skips both checks, which is what the simulator tests and the examples use.

Example

use franka::{ControllerMode, JointPositions, RealtimeConfig, Robot, DEFAULT_CUTOFF_FREQUENCY};

let robot = Robot::new("192.168.0.1", RealtimeConfig::Enforce)?;
let initial = robot.read_once()?.q_d;
let mut time = 0.0;
robot.control_joint_positions(
    |_state, period| {
        time += period.as_secs_f64();
        let mut q = initial;
        q[3] += std::f64::consts::PI / 8.0 * (1.0 - (std::f64::consts::PI / 2.5 * time).cos());
        let mut output = JointPositions::new(q);
        output.motion_finished = time >= 5.0;
        output
    },
    ControllerMode::JointImpedance,
    true,
    DEFAULT_CUTOFF_FREQUENCY,
)?;

Credit

This crate is an independent implementation whose API shape was informed by marcbone’s libfranka-rs (no code shared); libfranka itself is the reference every type, constant, error text and wire layout here is checked against; the doc comments name the C++ counterpart wherever there is one.

Module layout

Following libfranka: wire (packed protocol structs), network (the TCP command channel with command-id demultiplexing and the UDP state/command channel), robot (the public Robot API, control loops and ActiveControl), rate_limiting, model, gripper.

Re-exports

pub use control_types::motion_finished;

pub use control_types::CartesianPose;

pub use control_types::CartesianVelocities;

pub use control_types::ControllerMode;

pub use control_types::Finishable;

pub use control_types::JointPositions;

pub use control_types::JointVelocities;

pub use control_types::MotionGenerator;

pub use control_types::MotionGeneratorKind;

pub use control_types::Torques;

pub use duration::Duration;

pub use error::ControlException;

pub use error::FrankaError;

pub use error::FrankaResult;

pub use error::MoveStatus;

pub use error::Record;

pub use error::RobotCommandLog;

pub use errors::Errors;

pub use errors::ERROR_NAMES;

pub use gripper::Gripper;

pub use gripper::GripperState;

pub use joint_velocity_limits::JointVelocityLimitsConfig;

pub use lowpass_filter::cartesian_low_pass_filter;

pub use lowpass_filter::low_pass_filter;

pub use lowpass_filter::DEFAULT_CUTOFF_FREQUENCY;

pub use lowpass_filter::MAX_CUTOFF_FREQUENCY;

pub use model::Frame;

pub use model::Model;

pub use otg::CartesianOtg;

pub use otg::MultiOtg;

pub use otg::Otg;

pub use otg::OtgLimits;

pub use rate_limiting::compute_lower_limits_joint_velocity;

pub use rate_limiting::compute_upper_limits_joint_velocity;

pub use rate_limiting::limit_rate_cartesian_pose;

pub use rate_limiting::limit_rate_cartesian_velocity;

pub use rate_limiting::limit_rate_joint_position;

pub use rate_limiting::limit_rate_joint_positions;

pub use rate_limiting::limit_rate_joint_velocities;

pub use rate_limiting::limit_rate_joint_velocity;

pub use rate_limiting::limit_rate_torques;

pub use rate_limiting::DELTA_T;

pub use rate_limiting::FACTOR_CARTESIAN_ROTATION_POSE_INTERFACE;

pub use rate_limiting::JOINT_VELOCITY_LIMITS_TOLERANCE;

pub use rate_limiting::LIMIT_EPS;

pub use rate_limiting::MAX_ELBOW_ACCELERATION;

pub use rate_limiting::MAX_ELBOW_JERK;

pub use rate_limiting::MAX_ELBOW_VELOCITY;

pub use rate_limiting::MAX_JOINT_ACCELERATION;

pub use rate_limiting::MAX_JOINT_JERK;

pub use rate_limiting::MAX_ROTATIONAL_ACCELERATION;

pub use rate_limiting::MAX_ROTATIONAL_JERK;

pub use rate_limiting::MAX_ROTATIONAL_VELOCITY;

pub use rate_limiting::MAX_TORQUE_RATE;

pub use rate_limiting::MAX_TRANSLATIONAL_ACCELERATION;

pub use rate_limiting::MAX_TRANSLATIONAL_JERK;

pub use rate_limiting::MAX_TRANSLATIONAL_VELOCITY;

pub use rate_limiting::MIN_ELBOW_VELOCITY;

pub use rate_limiting::NORM_EPS;

pub use rate_limiting::TOL_NUMBER_PACKETS_LOST;

pub use realtime::RealtimeConfig;

pub use robot::impedance_torques;

pub use robot::ActiveMotionGenerator;

pub use robot::ActiveMotionInput;

pub use robot::ActiveTorqueControl;

pub use robot::Backend;

pub use robot::CartesianSent;

pub use robot::CartesianTargetControl;

pub use robot::IkOptions;

pub use robot::ImpedanceGains;

pub use robot::ImpedanceOptions;

pub use robot::JointSent;

pub use robot::JointTargetControl;

pub use robot::JointTargetControlOptions;

pub use robot::Leash;

pub use robot::Robot;

pub use robot::RobotOptions;

pub use robot::Settle;

pub use robot::TargetControlOptions;

pub use robot::VersionPolicy;

pub use robot::VirtualWallCuboid;

pub use robot_state::RobotMode;

pub use robot_state::RobotState;

pub use wire::robot::codec::FciVersion;

pub use wire::robot::MoveControllerMode;

Modules

control_types

Command types returned from control callbacks.

duration

Millisecond duration used for robot time stamps (mirrors franka::Duration).

error

Error types (mirror libfranka’s exception hierarchy).

errors

The 41 robot error flags, in the order of libfranka’s research_interface::robot::Error.

gripper

Franka Hand gripper client.

joint_velocity_limits

Position-dependent joint velocity limits read from the robot’s URDF.

lowpass_filter

First-order low-pass filters for control signals.

model

Kinematics and dynamics of the arm, mirroring libfranka’s franka::Model.

network

The two sockets of an FCI session and the Connect handshake.

otg

Online trajectory generation: a smooth 1 kHz command from a stream of stepped targets.

rate_limiting

Rate limiting for torques, joint positions/velocities and Cartesian poses/velocities.

realtime

Realtime scheduling helpers — a port of src/control_tools.cpp (libfranka 0.21.2).

robot

The public Robot API.

robot_state

Public robot state (mirrors franka::RobotState, all values f64).

wire

Packed, little-endian wire structs of the Franka Control Interface.