FCI v10 and FCI v5 on the wire

The crate speaks two versions of the Franka Control Interface. This page is the byte-level comparison and the negotiation between them. What the difference means for a program on a Franka Emika Robot is on FER / Panda specifics; the rate-limit envelopes are on Rate limiting and filtering.

Supported robots

Both versions share the framing: a TCP command channel on port 1337 with a 12-byte CommandHeader (command, command id, total size) and u8 status bytes, and a UDP channel on which the robot sends one RobotState per millisecond and receives one RobotCommand per state while a motion runs. The Franka Hand has its own protocol on port 1338 (10-byte header, u16 statuses), version 3 and byte-identical on both robots.

Version negotiation

Robot::new connects announcing library version 10. An FR3 accepts. An FER answers kIncompatibleLibraryVersion and reports version 5; the client then closes both sockets, opens a fresh TCP+UDP session and connects again as version 5. robot.fci_version() says which one you got:

extern crate franka;
use franka::{FciVersion, RealtimeConfig, Robot};

fn main() -> franka::FrankaResult<()> {
let robot = Robot::new("172.16.0.2", RealtimeConfig::Enforce)?;   // FR3 or FER
match robot.fci_version() {
    FciVersion::V10 => println!("FR3"),
    FciVersion::V5 => println!("FER"),
}
Ok(()) }

Auto-detection costs an FER one full connect, a rejected handshake and a disconnect, i.e. two FCI client slots in sequence. A supervisor that reconnects in a loop, or any program that knows its arm, pins the version with VersionPolicy::Exact:

extern crate franka;
use franka::{FciVersion, RealtimeConfig, Robot, RobotOptions, VersionPolicy};

fn main() -> franka::FrankaResult<()> {
let robot = Robot::with_options(
    "172.16.0.2",
    RobotOptions::new(RealtimeConfig::Enforce).with_version(VersionPolicy::Exact(FciVersion::V5)),
)?;
Ok(()) }

VersionPolicy::Exact(FciVersion::V10) against an FER never retries and fails with FrankaError::IncompatibleVersion { server_version: 5, library_version: 10 }, which is what a v10 libfranka reports when pointed at an FER. Any server version other than 5 or 10 is returned as the same error.

One deliberate divergence from libfranka, which only inspects the handshake’s status byte: a Connect reply of kSuccess that reports a version other than the one the client announced is refused with IncompatibleVersion. Everything after the handshake is decoded against the announced version, so such a session would fail on the first state with Protocol("libfranka: incorrect object size") instead of naming the problem. franka-sim’s FER build answers kSuccess with version 5 whatever the client announced, and this rule is what lets auto-detection recognise it.

After the handshake, an FCI v10 session fetches the URDF (GetRobotModel) and derives the position-dependent joint velocity limits from it, as libfranka 0.21.2 does; a v5 session stops after the first state, as 0.9.2 does.

What differs on the wire

The status enums other than Move::Status are shorter on v5 in the same way (no safety-function values); the crate maps every v5 byte onto the v10 name set by name, and a byte that is not valid for the negotiated version is FrankaError::Protocol("libfranka: Unexpected response while handling <name> command!").

Commands a version does not have

Calling one fails client-side, before a byte is sent, with libfranka’s own text:

FrankaError::InvalidOperation("libfranka: Get Robot Model is not available on FCI version 5.")
FrankaError::InvalidOperation("libfranka: Set Filters is not available on FCI version 10.")

Two public items carry the version: CommandName::command(version) -> Option<u32> is the wire id of a command under a version (None where it does not exist), and the FER’s rate-limit constants live only at franka::rate_limiting::fer::*, with the FR3’s at the crate root.

Two IP fragments per state

The v5 state datagram, 2373 bytes, exceeds the 1500-byte Ethernet MTU, so every FER state arrives as exactly two IP fragments: 2000 packets per second for the host to service instead of 1000. The FER hardware campaign saw no reassembly failures or drops (ReasmFails, ReasmTimeout, Udp.InErrors and NIC drops all zero); the doubled packet rate is the most plausible reason the FER lost occasional cycles where the FR3 lost none, as a load effect. See Benchmarks.

How the layout is pinned

Every wire struct is #[repr(C, packed)], and its size and every field offset are asserted against the declarations in libfranka’s service_types.h, rbk_types.h and the gripper’s types.h: crates/franka-rs/tests/wire_sizes.rs for FCI v10 (libfranka 0.21.2, including the 23-byte gripper state) and tests/wire_sizes_v5.rs for FCI v5 (libfranka 0.9.2, including the command numbering and the status tables). Both run offline, in CI’s check job. The mock-FCI unit tests under robot/mock_tests additionally pin the v5 Move payload, the torque-only datagrams and the LoadModelLibrary request byte for byte.

Wire parsing, the state demultiplexer, the rate limiter, the trajectory generator and the control loops are safe Rust; the crate’s unsafe is confined to the libc scheduler-priority calls in realtime.rs, the libc socket calls in network/udp.rs and network/tcp.rs, and the opt-in dlopen model loader (model/model_library.rs, model/so_backend/).