# frankaemika/franka_ros architecture

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

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

## Overview

##### Main Components
- Franka Control: (located in the franka_control directory) This package contains the core control nodes, configurations (YAML files), and launch files that initialize and run the real-time controllers.
- Franka Hardware Abstraction: (located in franka_hw) This provides the interfacing layer between the actual robot (or simulation) and the ROS control infrastructure.
- Robot Description: (in franka_description) Provides URDF/XACRO files and associated meshes (collision/visual models) to describe the robot physically to the ROS ecosystem.
- Example Controllers: (franka_example_controllers) These offer sample implementations of various control strategies (impedance, position, velocity, etc.) and include interactive markers, scripts, and custom messages.
- Simulation Environment: (franka_gazebo) Contains configurations, simulation plugins, models, launch files, and tests to simulate the robot environment within Gazebo.
- Gripper Control: (franka_gripper) Consists of specialized actions, nodes, and configurations to operate the gripper mechanism.
- Messaging: (franka_msgs) Defines the custom ROS messages, actions, and services that are used across the system for communication and control.
- ROS Integration Core: (franka_ros) Ties the above packages together ensuring they work nicely within the ROS ecosystem.

##### Relationships and Interactions
- ROS Nodes & Communication: Each package represents a ROS node or set of nodes interconnected via ROS topics, services, actions, and parameters.
- Data Flow:
- Robot control nodes (in franka_control and franka_example_controllers) use sensor data and feedback via franka_msgs.
- The control nodes interface with the hardware abstraction layer (franka_hw) to send commands to the physical or simulated robot.
- The description package (franka_description) delivers the robot model for visualization and simulation, which is then used by franka_visualization and franka_gazebo.
- Simulation nodes in franka_gazebo simulate the physics and robot behavior, thus input to control nodes and visualization.
- Gripper-specific actions and messages are handled separately in franka_gripper, but integrated with overall robot control.

##### Architectural Patterns and Design Principles
- Modular ROS Package Architecture: Each functional component (control, hardware, simulation, description, messaging, etc.) is segmented into its own ROS package for loose coupling, modular testing, and clear separation of concerns.
- Plugin-Based Extensibility: Several packages (e.g., franka_control, franka_hw, franka_gazebo) employ plugins (XML definitions provided in the file tree) to support extensibility and replaceable components.
- Configuration-Driven: YAML configuration files in various packages indicate a design that separates runtime parameters from code, aiding in flexibility and reusability.
- CI/CD Integration: Presence of GitHub workflows, Jenkinsfile, and CI scripts indicate that the system also follows best practices in continuous integration and testing.

##### Relevant Technologies and Frameworks
- ROS (Robot Operating System): The ecosystem throughout the repository – nodes, topics, services, actions – is built on ROS.
- Gazebo: Used for simulation within franka_gazebo.
- CMake: For building packages and managing interdependencies.
- Docker CI files: Found under .ci and GitHub workflows – ensure consistent build environments and resource isolation.
- Other Tools: Clang tools (clang-format, clang-tidy) for code quality, and various CI configuration scripts.

##### Elements
- From control nodes to hardware abstraction (command & feedback).
- From simulation (franka_gazebo) to control and visualization.
- From description providing URDF/meshes to simulation and visualization.
- From messaging definitions (franka_msgs) to all nodes that publish/subscribe.
- Annotations: Brief notes on the interaction types (topics, services, actions) and configurations (YAML launch parameters) between nodes.
- External services: Indicate integration with the ROS Master/parameter server, continuous integration pipelines (CI/CD), and any external simulation environments (Gazebo).

## Diagram (Mermaid)

```mermaid
graph TB

%% Subgraphs

subgraph "ROS Integration Core"
    ros("franka_ros"):::core
end

subgraph "Messaging"
    msgs("franka_msgs"):::messaging
end

subgraph "Control Layer"
    control("franka_control"):::control
    example("franka_example_controllers"):::control
end

subgraph "Hardware Abstraction"
    hw("franka_hw"):::hardware
end

subgraph "Robot Model & Description"
    description("franka_description"):::description
end

subgraph "Simulation & Testing"
    gazebo("franka_gazebo"):::simulation
end

subgraph "Gripper Mechanics"
    gripper("franka_gripper"):::gripper
end

subgraph "Visualization"
    viz("franka_visualization"):::visualization
end

%% Integration links from ROS Integration Core to all layers
ros -->|"sync"| control
ros -->|"sync"| example
ros -->|"sync"| hw
ros -->|"sync"| description
ros -->|"sync"| gazebo
ros -->|"sync"| gripper
ros -->|"sync"| viz
ros -->|"sync"| msgs

%% Messaging interactions with all components
control -->|"ROS_topics"| msgs
example -->|"ROS_topics"| msgs
hw -->|"feedback"| msgs
gazebo -->|"ROS_topics"| msgs
gripper -->|"ROS_topics"| msgs
viz -->|"ROS_topics"| msgs
description -->|"ROS_topics"| msgs

%% Interactions between layers
control -->|"control_cmd"| hw
gazebo -->|"simulated_data"| control
gazebo -->|"simulated_data"| viz
description -->|"robot_model"| gazebo
description -->|"robot_model"| viz
gripper -->|"gripper_control"| control

%% Styles
classDef core fill:#d3d3d3,stroke:#333,stroke-width:2px,color:#000;
classDef messaging fill:#ffeead,stroke:#f39c12,stroke-width:2px,color:#000;
classDef control fill:#add8e6,stroke:#0a74da,stroke-width:2px,color:#000;
classDef hardware fill:#ffb347,stroke:#ff8c00,stroke-width:2px,color:#000;
classDef description fill:#98fb98,stroke:#2e8b57,stroke-width:2px,color:#000;
classDef simulation fill:#e0bbff,stroke:#9932cc,stroke-width:2px,color:#000;
classDef gripper fill:#ffb6c1,stroke:#ff69b4,stroke-width:2px,color:#000;
classDef visualization fill:#afeeee,stroke:#40e0d0,stroke-width:2px,color:#000;

%% Click Events
click control "https://github.com/frankaemika/franka_ros/tree/develop/franka_control"
click hw "https://github.com/frankaemika/franka_ros/tree/develop/franka_hw"
click description "https://github.com/frankaemika/franka_ros/tree/develop/franka_description"
click example "https://github.com/frankaemika/franka_ros/tree/develop/franka_example_controllers"
click gazebo "https://github.com/frankaemika/franka_ros/tree/develop/franka_gazebo"
click gripper "https://github.com/frankaemika/franka_ros/tree/develop/franka_gripper"
click msgs "https://github.com/frankaemika/franka_ros/tree/develop/franka_msgs"
click viz "https://github.com/frankaemika/franka_ros/tree/develop/franka_visualization"
click ros "https://github.com/frankaemika/franka_ros/tree/develop/franka_ros"
```
