# ros2/rmw_zenoh architecture

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

- Interactive diagram: https://gitdiagram.com/ros2/rmw_zenoh
- Repository: https://github.com/ros2/rmw_zenoh

## Overview

##### Project type and purpose
- This is a ROS 2 “RMW” (ROS Middleware) plugin implementation named **rmw_zenoh**. Its purpose is to let ROS 2 nodes publish/subscribe and discover each other over the **Zenoh** network using C++ bindings. It also provides a Zenoh‐based “router” (a standalone process) and a security tools package to generate secure Zenoh configs.

##### File structure
Top-level modules:
- **.github/** – CI/workflow definitions.
- **docs/** – high-level design documentation.
- **rmw_zenoh_cpp/** – the core RMW plugin package: CMakeLists, ROS 2 package.xml, source (`src/detail` implements all `rmw_*` APIs), default Zenoh config files.
- **zenoh_cpp_vendor/** – vendored Zenoh C++ library build integration.
- **zenoh_security_tools/** – a small CLI app to generate secure Zenoh configurations for authentication, encryption, access control.

##### README for key architectural insights
- There is a two‐process model for discovery: a **Zenoh router** (`rmw_zenohd`) plus one or more **ROS 2 nodes** linked against the `rmw_zenoh_cpp` plugin.
- Environment variables and JSON5 config files configure session modes, discovery (gossip vs. multicast), security, logging, and network endpoints.

##### Main components and their relationships
A. **ROS 2 Application Layer**
- User nodes written with `rclcpp` (e.g., talker/listener).
- They link against the RMW interface (`rmw_zenoh_cpp`).
B. **rmw_zenoh_cpp Plugin**
- Implements standard RMW interfaces: publishers, subscriptions, services, clients, guard conditions, wait sets, graph cache, QoS translation, type support.
- Internally delegates serialization, discovery, pub/sub, and RPC to Zenoh C++.
C. **Zenoh C++ Vendor Library**
- Underlying transport and discovery mechanism (vendored via `zenoh_cpp_vendor` CMake).
D. **Zenoh Router Process** (`rmw_zenohd`)
- Acts as a gossip‐based discovery and message router when direct peer‐to-peer is disabled.
- Exchanges discovery information and forwards data between sessions.
E. **Zenoh Security Tools**
- CLI utility to generate config files enabling Zenoh access control, authentication, and encryption.

Interactions (data flows):
1. **Node ➔ RMW plugin:** `rclcpp` calls `rmw_create_publisher()`, `rmw_publish()`, etc.
2. **RMW plugin ➔ Zenoh session:** plugin creates a Zenoh session (client or peer) using JSON5 config and environment overrides, then advertises topics or connects to the router.
3. **Zenoh session ➔ Router or other sessions:** over TCP/multicast/gossip, handles discovery and data exchange.
4. **Router ➔ Router/Session:** gossip between multiple routers, session autoconnects as routers come online.
5. **Security Tools ➔ Config Files:** precompute security credentials to be consumed by plugin or router at startup.

##### Architectural patterns and design principles
- **Adapter pattern:** rmw_zenoh_cpp adapts ROS 2 RMW API to Zenoh’s API.
- **Layered architecture:** clear separation of application (rclcpp), middleware plugin (rmw_zenoh_cpp), transport layer (Zenoh C++), and external router.
- **Configuration‐driven behavior:** everything from discovery mode to security is parameterized via JSON5 files and environment variables.
- **Vendor encapsulation:** Zenoh C++ is vendored to ensure reproducible builds and subset of features.
- **Tooling separation:** security config generation is extracted into a separate CLI package to keep the core plugin lean.

##### Final advice
- Be as granular as needed: break the plugin into its major functional units (discovery, serialization, pub/sub, service).
- Don’t forget to show the flow of configuration (JSON5 files + env vars) as part of the system initialization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer" 
        direction TB
        App["ROS 2 Nodes (rclcpp) ×N"]:::app
    end

    %% Configuration Inputs
    subgraph "Configuration" 
        direction TB
        Env["Environment Variables"]:::config
        SessCfg["DEFAULT_RMW_ZENOH_SESSION_CONFIG.json5"]:::config
        RouterCfg["DEFAULT_RMW_ZENOH_ROUTER_CONFIG.json5"]:::config
    end

    %% RMW Interface Layer
    subgraph "RMW Interface Layer (rmw_zenoh_cpp)" 
        direction TB
        Entry["rmw_zenoh.cpp"]:::rmw
        Init["rmw_init.cpp"]:::rmw
        InitOpts["rmw_init_options.cpp"]:::rmw
        subgraph "Detail Modules"
            direction TB
            PubData["rmw_publisher_data.*"]:::rmw
            SubData["rmw_subscription_data.*"]:::rmw
            SrvData["rmw_service_data.*"]:::rmw
            ClientData["rmw_client_data.*"]:::rmw
            GraphCache["graph_cache.*"]:::rmw
            GuardCond["guard_condition.*"]:::rmw
            WaitSet["rmw_wait_set_data.hpp"]:::rmw
            QoS["qos.*"]:::rmw
            TypeSup["type_support.* / *_common.* / _type_support.*"]:::rmw
            CDR["cdr.*"]:::rmw
            ZenCfg["zenoh_config.*"]:::rmw
            ZenUtil["zenoh_utils.*"]:::rmw
            Logging["logging.* & logging_macros.hpp"]:::rmw
            Event["event.*"]:::rmw
            Liveliness["liveliness_utils.*"]:::rmw
            Identifier["identifier.*"]:::rmw
        end
    end

    %% Zenoh Vendor Layer
    subgraph "Zenoh C++ Vendor (zenoh_cpp_vendor)" 
        direction TB
        Vendor["Vendored Zenoh C++ Library"]:::vendor
    end

    %% Network & Router
    subgraph "Network & Router"
        direction TB
        Router["Zenoh Router (rmw_zenohd)"]:::router
        Cloud["Network (TCP/Multicast/Gossip)"]:::network
    end

    %% Security Tools
    subgraph "Zenoh Security Tools (CLI)" 
        direction TB
        SecMain["main.cpp"]:::sec
        SecGen["config_generator.*"]:::sec
    end

    %% Connections
    App -->|"rmw_create_publisher()/rmw_publish() etc."| Entry
    Env -->|applies to| Entry
    SessCfg -->|session config| Entry
    RouterCfg -->|router config| Router
    Entry -->|"zenoh::open() / Session APIs"| Vendor
    Vendor -->|connects over| Cloud
    Vendor -->|gossip/discovery| Router
    Router -->|forwards data| Cloud
    Cloud -->|delivery| Vendor
    SecGen -->|generates| SessCfg
    SecGen -->|generates| RouterCfg

    %% Click events
    click Entry "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/rmw_zenoh.cpp"
    click Init "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/rmw_init.cpp"
    click InitOpts "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/rmw_init_options.cpp"
    click PubData "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/rmw_publisher_data.cpp"
    click SubData "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/rmw_subscription_data.cpp"
    click SrvData "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/rmw_service_data.cpp"
    click ClientData "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/rmw_client_data.cpp"
    click GraphCache "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/graph_cache.cpp"
    click GuardCond "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/guard_condition.cpp"
    click WaitSet "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/rmw_wait_set_data.hpp"
    click QoS "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/qos.cpp"
    click TypeSup "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/type_support.cpp"
    click CDR "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/cdr.cpp"
    click ZenCfg "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/zenoh_config.cpp"
    click ZenUtil "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/zenoh_utils.cpp"
    click Logging "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/logging.cpp"
    click Event "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/event.cpp"
    click Liveliness "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/liveliness_utils.cpp"
    click Identifier "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/detail/identifier.cpp"
    click SessCfg "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/config/DEFAULT_RMW_ZENOH_SESSION_CONFIG.json5"
    click RouterCfg "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/config/DEFAULT_RMW_ZENOH_ROUTER_CONFIG.json5"
    click Router "https://github.com/ros2/rmw_zenoh/blob/rolling/rmw_zenoh_cpp/src/zenohd/main.cpp"
    click Vendor "https://github.com/ros2/rmw_zenoh/tree/rolling/zenoh_cpp_vendor/"
    click SecGen "https://github.com/ros2/rmw_zenoh/blob/rolling/zenoh_security_tools/src/config_generator.cpp"
    click SecMain "https://github.com/ros2/rmw_zenoh/blob/rolling/zenoh_security_tools/src/main.cpp"

    %% Styles
    classDef app fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef config fill:#E3F2FD,stroke:#64B5F6,color:#1E88E5,stroke-dasharray: 5 5;
    classDef rmw fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32;
    classDef vendor fill:#FFE0B2,stroke:#EF6C00,color:#E65100,stroke-dasharray: 5 5;
    classDef router fill:#E1BEE7,stroke:#6A1B9A,color:#4A148C;
    classDef network fill:#CFD8DC,stroke:#607D8B,color:#37474F,stroke-dasharray: 2 2;
    classDef sec fill:#F5F5F5,stroke:#9E9E9E,color:#616161;
```
