# frankaemika/franka_ros2 architecture

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

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

## Overview

##### Project type and purpose
- This is a ROS 2 integration monorepo for Franka Robotics research arms (“franka_ros2”).
- It provides wrappers around libfranka, hardware interfaces, controllers, simulation support (Gazebo/Ignition), MoveIt configuration, message/action definitions, and example nodes to drive the robot within ROS 2.
- The README confirms it targets ROS 2 Humble, supporting both real and simulated hardware via Docker or native install.

##### File structure
- Top‐level files: Dockerfile, docker‑compose.yml, Jenkinsfile, GitHub workflows → CI/CD and containerized environment.
- Multiple ROS 2 packages in parallel directories:
- franka_hardware: hardware_interface wrapping libfranka, exposes ROS2 control interfaces and action servers
- franka_gripper: gripper action server
- franka_msgs: custom ROS2 messages, actions, services
- franka_robot_state_broadcaster: state to TF/component broadcaster
- franka_semantic_components: high‐level semantic interfaces (Cartesian pose/velocity, robot model/state wrappers)
- franka_bringup: launch files and controller config for bringing up a real robot
- franka_example_controllers: sample controllers demonstrating how to use the interfaces
- franka_fr3_moveit_config: MoveIt2 planning configuration, SRDFs, launch files
- franka_gazebo: simulation packages for Gazebo and Ignition with hardware plugins and bringup
- integration_launch_testing: end‐to‐end smoke tests
- Each package follows the ROS 2 structure: package.xml, CMakeLists.txt, include/, src/, launch/, config/, test/.

##### Key insights from the README
- Architecture revolves around ROS 2 nodes, topics, actions, services, and lifecycle managed by launch files.
- Supports real and fake hardware via use_fake_hardware flag in MoveIt launch.
- Recommends Docker for reproducible builds; includes devcontainer support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build and CI/CD Environments
    subgraph "Build & CI/CD Environments"
        direction TB
        DevEnv["Docker / DevContainer"]:::env
        CICD["CI/CD Pipelines"]:::env
    end

    %% ROS2 Core Middleware
    subgraph "ROS2 Core (DDS)" 
        direction TB
        ROS2Core["ROS2 Core\n(DDS Middleware)"]:::middleware
        MsgBus["franka_msgs\n(Topics/Actions/Services)"]:::middleware
    end

    DevEnv -->|build & run| ROS2Core
    CICD -->|trigger builds/tests| DevEnv

    %% Planning Layer
    subgraph "Planning (MoveIt2)" 
        direction TB
        MoveIt["move_group\n(franka_fr3_moveit_config)"]:::planning
    end

    %% Controllers Layer
    subgraph "Controllers" 
        direction TB
        ExampleCtrls["Example Controllers\n(franka_example_controllers)"]:::controller
    end

    %% Hardware & Simulation Interfaces
    subgraph "Hardware / Simulation Interfaces"
        direction TB
        subgraph "Real Hardware Interface"
            direction TB
            FrankaHW["franka_hardware\n(hardware_interface + action server)"]:::hw
            FrankaHW -->|"libfranka SDK"| LibFranka["libfranka"]:::external
        end
        subgraph "Simulation Interface"
            direction TB
            GazeboBringup["Gazebo Bringup\n(franka_gazebo/franka_gazebo_bringup)"]:::hw
            IgnitionCtrl["Ignition ros2_control\n(franka_gazebo/franka_ign_ros2_control)"]:::hw
        end
        FrankaGripper["franka_gripper\n(gripper action server)"]:::hw
    end

    %% State Broadcasting & Semantic Components
    subgraph "State & Semantic Components"
        direction TB
        StateBroadcaster["franka_robot_state_broadcaster"]:::semantic
        SemanticComp["franka_semantic_components"]:::semantic
    end

    %% Integration Testing
    IntegrationTests["Integration Launch Testing"]:::external

    %% Data Flows
    MoveIt -->|"/joint_trajectory"| ExampleCtrls
    ExampleCtrls -->|"/joint_trajectory"| FrankaHW
    ExampleCtrls -->|"/gripper_command"| FrankaGripper
    FrankaHW -->|"/franka_states"| MsgBus
    FrankaGripper -->|"/gripper_feedback"| MsgBus
    GazeboBringup -->|"/joint_trajectory"| MsgBus
    IgnitionCtrl -->|"/franka_states"| MsgBus

    MsgBus -->|subscribe| StateBroadcaster
    StateBroadcaster -->|publish TF & states| MsgBus
    MsgBus -->|services/actions| SemanticComp
    MoveIt -->|planning service| MsgBus

    IntegrationTests -->|executes| MoveIt
    IntegrationTests -->|executes| ExampleCtrls
    IntegrationTests -->|executes| FrankaHW
    IntegrationTests -->|executes| GazeboBringup

    %% Click Events
    click DevEnv "https://github.com/frankaemika/franka_ros2/blob/humble/.devcontainer/devcontainer.json"
    click DevEnv "https://github.com/frankaemika/franka_ros2/tree/humble/Dockerfile"
    click DevEnv "https://github.com/frankaemika/franka_ros2/blob/humble/docker-compose.yml"
    click CICD "https://github.com/frankaemika/franka_ros2/blob/humble/.github/workflows/ci.yml"
    click CICD "https://github.com/frankaemika/franka_ros2/tree/humble/Jenkinsfile"
    click FrankaHW "https://github.com/frankaemika/franka_ros2/tree/humble/franka_hardware/"
    click FrankaGripper "https://github.com/frankaemika/franka_ros2/tree/humble/franka_gripper/"
    click StateBroadcaster "https://github.com/frankaemika/franka_ros2/tree/humble/franka_robot_state_broadcaster/"
    click SemanticComp "https://github.com/frankaemika/franka_ros2/tree/humble/franka_semantic_components/"
    click ExampleCtrls "https://github.com/frankaemika/franka_ros2/tree/humble/franka_example_controllers/"
    click MoveIt "https://github.com/frankaemika/franka_ros2/tree/humble/franka_fr3_moveit_config/"
    click GazeboBringup "https://github.com/frankaemika/franka_ros2/tree/humble/franka_gazebo/franka_gazebo_bringup/"
    click IgnitionCtrl "https://github.com/frankaemika/franka_ros2/tree/humble/franka_gazebo/franka_ign_ros2_control/"
    click MsgBus "https://github.com/frankaemika/franka_ros2/tree/humble/franka_msgs/"
    click IntegrationTests "https://github.com/frankaemika/franka_ros2/tree/humble/integration_launch_testing/"

    %% Styles
    classDef env fill:#fff3b0,stroke:#d4a017,color:#000
    classDef middleware fill:#d3d3d3,stroke:#808080,color:#000
    classDef planning fill:#ffd59e,stroke:#ff8c00,color:#000
    classDef controller fill:#b8e986,stroke:#4ca64c,color:#000
    classDef hw fill:#a2cffe,stroke:#1e90ff,color:#000
    classDef semantic fill:#c1f0c1,stroke:#2e8b57,color:#000
    classDef external fill:#f0f0f0,stroke:#999,color:#000
```
