# open-rmf/free_fleet architecture

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

- Interactive diagram: https://gitdiagram.com/open-rmf/free_fleet
- Repository: https://github.com/open-rmf/free_fleet

## Overview

##### Project Type and Purpose
- The Free Fleet project is an implementation of the Open-RMF Fleet Adapter. Its main aim is to bridge communication between robot navigation stacks (using ROS 1 and ROS 2) and RMF (Robot Management Framework) core systems using zenoh as the messaging layer.
- The system supports different simulation setups (single/multi-robot) and uses docker containers for integration tests and simulations. The README explains multiple simulation examples (Nav1, Nav2) and required bridging between robot namespaces and the fleet adapter.

##### File Structure
- Top-level directories include:
- .github: Contains GitHub actions, workflows, and docker configurations for continuous integration and integration testing.
- free_fleet: Contains the core python implementation (conversion utilities, ROS type helpers, adapter utilities, and tests).
- free_fleet_adapter: Contains ROS adapter-specific modules (robot adapters for nav1, nav2, fleet adapter logic) along with launch files, tests, and a CMakeLists.txt. This layer bridges between the ROS navigation stacks and the Free Fleet core.
- free_fleet_examples: Provides sample configurations, launch simulations, maps, and example scripts to drive navigation commands – illustrating how the fleet adapter might be used in real-life scenarios.
- The presence of Dockerfiles and docker-compose files indicates that testing, integration, and different environments (ROS 1/ROS 2, minimal bridges, etc.) are part of the architectural design.

##### README for Additional Insights
- The README confirms the project uses zenoh bridges (one for ROS2 and one for ROS1) along with a dedicated zenoh router, emphasizing the separation of concerns:
- The robots run a non-namespaced navigation stack.
- Zenoh bridges, configured with each robot’s name as a namespace, route messages.
- The free_fleet_adapter then uses these messages to interface with RMF.
- Different simulation examples illustrate complexity like multiple robot fleets and varying integration scenarios (e.g., nav2 single vs. nav2 multiple robots, and nav1 setups).
- The README also provides detailed instructions for setting up dependencies and communicating with external services like rmf-web for task dispatching.

a. Main Components to Include:
- Robots/Navigation Stacks: Indicate both ROS1 (Nav1) and ROS2 (Nav2) stacked robots.
- Zenoh Bridges: Two bridges (zenoh-bridge-ros2dds for ROS2 and zenoh-bridge-ros1 for ROS1) that encapsulate the communication between robots and the adapter.
- Zenoh Router: Centralized message broker for routing zenoh messages.
- Free Fleet Adapter: The adapter logic (free_fleet_adapter) that receives messages from the various bridges and communicates with the RMF core.
- Free Fleet Core Library: The “free_fleet” python package, handling data conversion and utility functions.
- RMF Core / External Services: The RMF core system (or rmf-web API server) that dispatches tasks and controls fleet behavior.
- Simulation/Example Environment: Containers or simulation launch environments detailed under free_fleet_examples and the Dockerfiles.

b. Relationships and Data Flow:
- That the zenoh bridges publish their messages to the zenoh router.
- That the free_fleet_adapter fetches messages from the zenoh router.
- Interaction between RMF core (or rmf-web) and the free_fleet_adapter for task dispatching and fleet command exchanges.

c. Architectural Patterns and Design Principles:
- Decoupling between the robotics middleware (ROS 1/ROS 2 navigation stacks) and the fleet management system by using the zenoh communication layer.
- Modularity by separating the free_fleet core (utilities and converters) from the free_fleet_adapter (integration layer handling robot specific logic).
- Use of containerization (Docker) for integration tests and deployment setups, which is critical for ensuring consistent development and deployment environments.

d. Technologies, Frameworks, and Libraries:
- ROS 2 Jazzy and ROS 1 Noetic as supported middleware.
- Use of zenoh (including zenoh-bridge-ros2dds and zenoh-bridge-ros1) in the communication layer.
- Mention integration with rmf-core components and ancillary tools such as rmf-web, rmw-cyclonedds, and colcon for build orchestration.
- Dependencies like Python, CMake (for free_fleet_adapter), and Docker for simulations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Robot Navigation Layers"
        ROS1["ROS1 Navigation Stack"]:::navigation
        ROS2["ROS2 Navigation Stack"]:::navigation
    end

    subgraph "Communication Layer"
        ZB1["Zenoh Bridge (ROS1)"]:::zenohBridge
        ZB2["Zenoh Bridge (ROS2DDS)"]:::zenohBridge
        ZR["Zenoh Router"]:::router
    end

    subgraph "Adapter Layer"
        FAA["Free Fleet Adapter"]:::adapter
        FFC["Free Fleet Core Library"]:::core
    end

    subgraph "External Services"
        RMF["RMF Core / rmf-web API"]:::external
    end

    subgraph "Simulation Environment"
        SIM["Simulation/Example Environment"]:::simulation
    end

    %% Data Flow Connections
    ROS1 -->|"ROS1_messages"| ZB1
    ROS2 -->|"ROS2_messages"| ZB2
    ZB1 -->|"publish"| ZR
    ZB2 -->|"publish"| ZR
    ZR -->|"route"| FAA
    FAA -->|"uses"| FFC
    FAA <-->|"commands"| RMF
    SIM -->|"simulation_cmds"| FAA

    %% Click Events for Component Mappings
    click ROS1 "https://github.com/open-rmf/free_fleet/blob/main/free_fleet_adapter/free_fleet_adapter/nav1_robot_adapter.py"
    click ROS2 "https://github.com/open-rmf/free_fleet/blob/main/free_fleet_adapter/free_fleet_adapter/nav2_robot_adapter.py"
    click ZB1 "https://github.com/open-rmf/free_fleet/tree/main/.github/docker/minimal-zenoh-bridge-ros1"
    click ZB2 "https://github.com/open-rmf/free_fleet/tree/main/.github/docker/minimal-zenoh-bridge-ros2dds"
    click FAA "https://github.com/open-rmf/free_fleet/tree/main/free_fleet_adapter"
    click FFC "https://github.com/open-rmf/free_fleet/tree/main/free_fleet/free_fleet"
    click SIM "https://github.com/open-rmf/free_fleet/tree/main/free_fleet_examples"

    %% Styles for different layers
    classDef navigation fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef zenohBridge fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef router fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef adapter fill:#FFA500,stroke:#FF8C00,stroke-width:2px;
    classDef core fill:#FFDEAD,stroke:#D2691E,stroke-width:2px;
    classDef external fill:#FF6347,stroke:#B22222,stroke-width:2px;
    classDef simulation fill:#AF7AC5,stroke:#6A5ACD,stroke-width:2px;
```
