# frankarobotics/franka_ros2 architecture

> Architecture diagram of the GitHub repository frankarobotics/franka_ros2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frankarobotics/franka_ros2
- Repository: https://github.com/frankarobotics/franka_ros2

## Overview

##### Project type and purpose
- This is a multi‐package ROS 2 integration repository (“franka_ros2”) providing hardware drivers, controllers, message definitions, simulation glue, and MoveIt! configuration for the Franka Research robotic arm.
- Its goal is to expose libfranka functionality as ROS 2 nodes, services, actions, and topics, support both real and simulated robots (Gazebo and Ignition), and enable motion planning via MoveIt!.

##### High-level file-structure analysis
- Top-level build orchestration:
- Dockerfile, docker‐compose.yml, .devcontainer/ → containerized dev/build environment.
- Jenkinsfile, .github/workflows/ci.yml → CI pipeline.
- ROS 2 packages:
- franka_msgs → custom ROS 2 message/service/action definitions.
- franka_hardware → ROS 2 Control hardware interface and action server.
- franka_gripper → gripper action server and fake state publisher.
- franka_robot_state_broadcaster → state‐publisher node for robot_state.
- franka_semantic_components → C++ semantic interfaces (Cartesian pose, velocity, state).
- franka_example_controllers → sample controllers (joint/cartesian) as ROS 2 Control plugins.
- franka_bringup → launch files and configurations to start the robot.
- franka_fr3_moveit_config → MoveIt! config & planners.
- franka_gazebo & franka_gazebo/franka_ign_ros2_control → simulation‐specific launch files, Ignition/Gazebo control plugins.
- integration_launch_testing → end‐to‐end launch tests in Python.

a. Container/host environment
- Docker/DevContainer encapsulating ROS 2 Humble, colcon build, libfranka, dependencies.
b. ROS 2 DDS communication mesh
- Nodes communicate over topics, actions, and services.
c. Hardware abstraction layer
- franka_hardware (implements ros2_control HardwareInterface)
- Action servers exposing real‐time commands to arm & gripper.
d. Semantic & state layers
- franka_robot_state_broadcaster publishes sensor_state → topics
- franka_semantic_components subscribe to state and offer high‐level interfaces.
e. Controllers
- franka_example_controllers loaded via ros2_control → subscribe to state, publish commands.
f. Motion planning
- franka_fr3_moveit_config (MoveGroup node → planning pipelines → execution via ros2_control).
g. Simulation
- franka_gazebo / ign plugin replacing hardware with Gazebo/IGN System plugin.
h. Integration tests
- launch_testing harness invoking brings‐up, controllers, services, verifying end‐to‐end behavior.

##### Relationships & data-flow
- User/API layer (ros2 launch CLI or RViz) → Launch files in franka_bringup and MoveIt! → brings up nodes
- franka_hardware ↔ libfranka (UDP/TCP driver) → robotic arm hardware
- franka_gripper → Franka gripper driver or fake publisher
- ros2_control controller manager loads example controllers → command interfaces → hardware interface
- franka_robot_state_broadcaster subscribes to hardware interface topics → republishes on standard /joint_states or custom topics
- franka_semantic_components subscribe to state topics → provide semantic messages to application code
- MoveGroup node → planning requests → action to execute trajectory → publishes commands to controller_manager
- In simulation mode, hardware interface is replaced by franka_gazebo/franka_ign_ros2_control plugin
- All inter‐node comms use ROS 2 topics/services/actions over DDS

##### Architectural patterns & principles
- Modular ROS 2 node‐per‐responsibility pattern (separation of concerns)
- Plugin architecture via ros2_control for runtime‐loadable controllers
- Message‐driven, decoupled via DDS (topic/action/service)
- DevOps via containerization (Docker/DevContainer) and CI pipelines
- Test‐driven integration via launch_testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External entities
    User["User (ROS2 CLI / RViz)"]:::external
    CI["CI Pipeline"]:::external

    click User "https://github.com/frankarobotics/franka_ros2/tree/humble/N/A"
    click CI "https://github.com/frankarobotics/franka_ros2/tree/humble/Jenkinsfile"

    %% Container boundary
    subgraph "Docker / DevContainer\n(ROS 2 Humble + libfranka)" 
        direction TB

        %% Message Definitions
        FR_MSGS[("franka_msgs\n(cylinder)")]:::cylinder
        click FR_MSGS "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_msgs/CMakeLists.txt"
        click FR_MSGS "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_msgs/action/*.action"
        click FR_MSGS "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_msgs/msg/*.msg"
        click FR_MSGS "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_msgs/srv/*.srv"

        %% Hardware & Drivers
        subgraph "Hardware & Drivers" 
            direction TB
            FR_HARDWARE["franka_hardware\n(HW Interface)"]:::blue
            FR_GRIPPER["franka_gripper\n(Gripper Driver)"]:::blue
            click FR_HARDWARE "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_hardware/CMakeLists.txt"
            click FR_HARDWARE "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_hardware/include/franka_hardware/franka_hardware_interface.hpp"
            click FR_HARDWARE "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_hardware/src/franka_hardware_interface.cpp"
            click FR_HARDWARE "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_hardware/src/franka_action_server.cpp"
            click FR_HARDWARE "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_hardware/src/franka_executor.cpp"
            click FR_HARDWARE "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_hardware/src/franka_param_service_server.cpp"
            click FR_GRIPPER "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gripper/CMakeLists.txt"
            click FR_GRIPPER "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gripper/include/franka_gripper/gripper_action_server.hpp"
            click FR_GRIPPER "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gripper/src/gripper_action_server.cpp"
            click FR_GRIPPER "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gripper/scripts/fake_gripper_state_publisher.py"
            click FR_GRIPPER "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gripper/launch/gripper.launch.py"
        end

        %% State & Semantics
        subgraph "State & Semantics"
            direction TB
            STATE_BROAD["franka_robot_state_broadcaster"]:::orange
            SEM_COMP["franka_semantic_components"]:::orange
            click STATE_BROAD "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_robot_state_broadcaster/CMakeLists.txt"
            click STATE_BROAD "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_robot_state_broadcaster/include/franka_robot_state_broadcaster/franka_robot_state_broadcaster.hpp"
            click STATE_BROAD "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_robot_state_broadcaster/src/franka_robot_state_broadcaster.cpp"
            click STATE_BROAD "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_robot_state_broadcaster/src/franka_robot_state_broadcaster_parameters.yaml"
            click SEM_COMP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_semantic_components/CMakeLists.txt"
            click SEM_COMP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_semantic_components/include/franka_semantic_components/franka_cartesian_pose_interface.hpp"
            click SEM_COMP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_semantic_components/include/franka_semantic_components/franka_semantic_component_interface.hpp"
            click SEM_COMP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_semantic_components/src/franka_cartesian_pose_interface.cpp"
            click SEM_COMP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_semantic_components/src/franka_semantic_component_interface.cpp"
        end

        %% Controllers
        subgraph "Controllers"
            direction TB
            CTRL_MGR["controller_manager\n(ros2_control)"]:::green
            EX_CONT["franka_example_controllers"]:::green
            click EX_CONT "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_example_controllers/CMakeLists.txt"
            click EX_CONT "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_example_controllers/include/franka_example_controllers/*.hpp"
            click EX_CONT "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_example_controllers/src/*.cpp"
            click EX_CONT "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_example_controllers/franka_example_controllers.xml"
        end

        %% Motion Planning
        subgraph "Motion Planning"
            direction TB
            MOVE_GROUP["MoveGroup\n(MoveIt!)"]:::purple
            click MOVE_GROUP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_fr3_moveit_config/launch/move_group.launch.py"
            click MOVE_GROUP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_fr3_moveit_config/launch/moveit.launch.py"
            click MOVE_GROUP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_fr3_moveit_config/config/ompl_planning.yaml"
            click MOVE_GROUP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_fr3_moveit_config/config/fr3_ros_controllers.yaml"
        end

        %% Simulation Plugin
        subgraph "Simulation Plugin"
            direction TB
            GAZEBO["Gazebo Plugin\n(franka_gazebo)"]:::gray
            IGN["Ignition Plugin\n(ign_ros2_control)"]:::gray
            click GAZEBO "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gazebo/franka_gazebo_bringup/launch/gazebo_joint_impedance_controller_example.launch.py"
            click GAZEBO "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gazebo/franka_gazebo_bringup/config/franka_gazebo_controllers.yaml"
            click IGN "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gazebo/franka_ign_ros2_control/CMakeLists.txt"
            click IGN "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gazebo/franka_ign_ros2_control/ign_hardware_plugins.xml"
            click IGN "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gazebo/franka_ign_ros2_control/include/ign_ros2_control/ign_system.hpp"
            click IGN "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_gazebo/franka_ign_ros2_control/src/ign_ros2_control_plugin.cpp"
        end

        %% Launch & Test Harness
        subgraph "Launch & Test Harness"
            direction TB
            BRINGUP["franka_bringup\n(launch files)"]:::launch
            MOVEIT_LAUNCH["MoveIt! Launch"]:::launch
            TESTS["Integration Tests"]:::launch
            click BRINGUP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_bringup/launch/franka.launch.py"
            click BRINGUP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_bringup/launch/example.launch.py"
            click BRINGUP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_bringup/config/controllers.yaml"
            click BRINGUP "https://github.com/frankarobotics/franka_ros2/blob/humble/franka_bringup/config/franka.config.yaml"
            click TESTS "https://github.com/frankarobotics/franka_ros2/blob/humble/integration_launch_testing/CMakeLists.txt"
            click TESTS "https://github.com/frankarobotics/franka_ros2/blob/humble/integration_launch_testing/test/test_franka_gripper_position.py"
            click TESTS "https://github.com/frankarobotics/franka_ros2/blob/humble/integration_launch_testing/test/test_move_to_start_example_controller.py"
        end

    end

    %% CI arrow
    CI -->|"triggers build/test"| BRINGUP

    %% User arrows
    User -->|"launch bringup"| BRINGUP
    User -->|"launch MoveIt!"| MOVEIT_LAUNCH
    TESTS -->|"invoke launches"| BRINGUP
    TESTS -->|"invoke launches"| MOVEIT_LAUNCH

    %% Data flows
    FR_HARDWARE -->|"libfranka"| STATE_BROAD
    FR_GRIPPER -->|"gripper state"| STATE_BROAD
    STATE_BROAD -->|"joint_states"| EX_CONT
    STATE_BROAD -->|"state msgs"| SEM_COMP
    EX_CONT -->|"commands"| FR_HARDWARE
    CTRL_MGR -->|"loads plugin"| EX_CONT
    MOVE_GROUP -->|"execute via"| CTRL_MGR
    MOVE_GROUP -->|"planning requests"| SEM_COMP

    %% Simulation replacement
    GAZEBO -.->|replaces| FR_HARDWARE
    IGN -.->|replaces| FR_HARDWARE

    %% Message definitions usage
    FR_MSGS -.->|DDS topics/services/actions| FR_HARDWARE
    FR_MSGS -.->|DDS topics/services/actions| FR_GRIPPER
    FR_MSGS -.->|DDS topics/services/actions| STATE_BROAD
    FR_MSGS -.->|DDS topics/services/actions| SEM_COMP
    FR_MSGS -.->|DDS topics/services/actions| EX_CONT
    FR_MSGS -.->|DDS topics/services/actions| MOVE_GROUP

    %% Styles
    classDef external fill:#ffffff,stroke:#000,stroke-width:1px
    classDef cylinder fill:#f9f,stroke:#933,stroke-width:2px,shape:cylinder
    classDef blue fill:#e0f7fa,stroke:#006064,stroke-width:1px
    classDef green fill:#e8f5e9,stroke:#1b5e20,stroke-width:1px
    classDef orange fill:#fff3e0,stroke:#e65100,stroke-width:1px
    classDef purple fill:#f3e5f5,stroke:#4a148c,stroke-width:1px
    classDef gray fill:#eceff1,stroke:#37474f,stroke-width:1px
    classDef launch fill:#fffde7,stroke:#f9a825,stroke-width:2px,shape:parallelogram
```
