# jensvanhooydonck/ethercat_driver_ros2 architecture

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

- Interactive diagram: https://gitdiagram.com/jensvanhooydonck/ethercat_driver_ros2
- Repository: https://github.com/jensvanhooydonck/ethercat_driver_ros2

## Overview

##### Project type and purpose
- This is an open-source ROS 2 driver stack (“ethercat_driver_ros2”) that provides a Hardware Interface for integrating EtherCAT modules with ros2_control.
- It builds on the IgH EtherCAT Master for Linux and exposes generic, plugin-based drivers (CIA402 drives, generic slaves) plus management layers and ROS 2 services (GetSdo/SetSdo).

##### File structure
- Top-level directories:
- .docker (Dockerfile + docs for containerized CI)
- .github (CI workflows)
- ethercat_driver (core C++ plugin layer)
- ethercat_driver_ros2 (the ROS 2 node/HW interface + docs)
- ethercat_generic_plugins (two subfolders for CIA402 drive & generic slave)
- ethercat_interface (abstraction over IgH EtherCAT Master)
- ethercat_manager (async manager + ROS 2 SDO service server)
- ethercat_msgs (ROS 2 service definitions for SDO)
- Each package uses standard CMakeLists.txt + package.xml → ROS 2 workspace layout.
- There are test folders under interface and generic_plugins, plus Doxygen & Sphinx docs in the ros2 package.

##### README for additional insights
- The driver plugs into ros2_control as a Hardware Interface.
- Plugins are parameterized by YAML/config files (in doc quickstart).
- Underlying comms rely on IgH EtherCAT Master → real-time bus.

a. Main components to include:
1) ros2_control Framework (controller manager + controllers)
2) ethercat_driver_ros2 Node (implements HardwareInterface)
3) ethercat_manager (async I/O & SDO service server)
4) ethercat_interface Library (wrapper over IgH EtherCAT Master API)
5) ethercat_driver Core Plugin Loader (loads XML plugin descriptors)
6) ethercat_generic_plugins (CIA402 Drive, Generic Slave modules)
7) IgH EtherCAT Master (user-space daemon / kernel module)
8) Physical EtherCAT Network + Slaves (motors, I/O modules)
9) ethercat_msgs (GetSdo/SetSdo service definitions)
10) Configuration files (YAML, plugin XML)
b. Relationships & interactions:
- ros2_control → calls HardwareInterface APIs in ethercat_driver_ros2
- ethercat_driver_ros2 → uses ethercat_manager for read/write cycles & SDO services
- ethercat_manager → uses ethercat_interface to interact with underlying IgH API
- ethercat_interface → issues PDO/SDO requests to IgH Master → bus → slaves
- At startup, ethercat_driver core reads plugin XML → instantiates generic_plugins
- Users can call ROS 2 services (GetSdo/SetSdo) provided by ethercat_manager
c. Architectural patterns / design principles:
- Layered abstraction (ros2_control → driver_ros2 → manager → interface → master)
- Plugin architecture (generic_plugins loaded via XML descriptors)
- Separation of concerns (I/O scheduling in manager vs. low-level access in interface)
- ROS 2 middleware for messaging & service orchestration
d. Key technologies/frameworks:
- C++, CMake, colcon build
- ROS 2 (rclcpp, ros2_control, custom messages/services)
- IgH EtherCAT Master
- Doxygen (C++ API docs) & Sphinx (user/developer guides)
- Docker (containerized CI) & GitHub Actions

##### Final advice
- Explicitly show plugin points and SDO service endpoints.
- Configuration & build artifacts (CMake, package.xml) in a corner to acknowledge the build/deploy layer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% ROS 2 Middleware Layer
    subgraph "ROS 2 Middleware"
        RC["ros2_control\nController Manager + Controllers"]:::ros2
        EDR["ethercat_driver_ros2\nHardwareInterface Node\n(SDO Services)"]:::ros2
        Msgs["ethercat_msgs\nGetSdo/SetSdo svc defs"]:::ros2
    end

    %% Driver Layer
    subgraph "Driver Layer"
        EDrv["ethercat_driver\nPlugin Loader (XML)"]:::plugin
        CIA["CIA402 Drive Plugin"]:::plugin
        Gen["Generic Slave Plugin"]:::plugin
    end

    %% Manager Layer
    subgraph "Manager Layer"
        EMgr["ethercat_manager\nAsync I/O & SDO Server"]:::ros2
    end

    %% Interface Layer
    subgraph "Interface Layer"
        EIf["ethercat_interface\nIgH EtherCAT Master API Wrapper"]:::master
    end

    %% Master Layer
    subgraph "EtherCAT Master"
        IDM["IgH EtherCAT Master\ndaemon/kernel module"]:::master
    end

    %% Physical Network
    subgraph "Physical Network"
        Slaves["EtherCAT Network\nPhysical Slaves (motors, I/O)"]:::physical
    end

    %% Configuration & CI
    subgraph "Configuration & CI"
        XmlLoader["Plugin XML\n(ethercat_driver_plugin.xml)"]:::config
        XmlCIA["CIA402 Plugins XML"]:::config
        XmlGen["Generic Slave Plugins XML"]:::config
        XmlConfDocs["Quickstart Config Docs"]:::config
        Docker["Containerized CI\nDocker & Docs"]:::config
        GH["GitHub Actions\nCI Workflows"]:::config
    end

    %% Data & Control Flow
    RC -->|"calls HardwareInterface APIs"| EDR
    EDR -->|"uses services definitions"| Msgs
    EDR -->|"I/O & SDO services"| EMgr
    EMgr -->|"raw I/O calls"| EIf
    EIf -->|"PDO/SDO requests"| IDM
    IDM -->|"bus communication"| Slaves
    Slaves -->|"feedback"| EIf
    EIf -->|"feedback"| EMgr
    EMgr -->|"feedback"| EDR

    %% Plugin Loading
    EDR -->|"loads plugins"| EDrv
    EDrv -->|"instantiates via XML"| CIA
    EDrv -->|"instantiates via XML"| Gen

    %% Config & CI Links
    XmlLoader --> EDrv
    XmlCIA --> CIA
    XmlGen --> Gen
    XmlConfDocs --> EDR
    Docker -->|"CI container"| EDR
    GH -->|"CI workflows"| EDR

    %% Click Events
    click EDR "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/ethercat_driver_ros2/"
    click EMgr "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/ethercat_manager/"
    click EIf "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/ethercat_interface/"
    click EDrv "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/ethercat_driver/"
    click CIA "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/ethercat_generic_plugins/ethercat_generic_cia402_drive/"
    click Gen "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/ethercat_generic_plugins/ethercat_generic_slave/"
    click Msgs "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/ethercat_msgs/"
    click XmlLoader "https://github.com/jensvanhooydonck/ethercat_driver_ros2/blob/main/ethercat_driver/ethercat_driver_plugin.xml"
    click XmlCIA "https://github.com/jensvanhooydonck/ethercat_driver_ros2/blob/main/ethercat_generic_plugins/ethercat_generic_cia402_drive/ethercat_plugins.xml"
    click XmlGen "https://github.com/jensvanhooydonck/ethercat_driver_ros2/blob/main/ethercat_generic_plugins/ethercat_generic_slave/ethercat_plugins.xml"
    click XmlConfDocs "https://github.com/jensvanhooydonck/ethercat_driver_ros2/blob/main/ethercat_driver_ros2/sphinx/quickstart/configuration.rst"
    click Docker "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/.docker/"
    click GH "https://github.com/jensvanhooydonck/ethercat_driver_ros2/tree/main/.github/workflows/"

    %% Styles
    classDef ros2 fill:#AED6F1,stroke:#1F618D,stroke-width:1px
    classDef master fill:#A9DFBF,stroke:#145A32,stroke-width:1px
    classDef plugin fill:#D2B4DE,stroke:#512E5F,stroke-width:1px
    classDef physical fill:#F5CBA7,stroke:#B9770E,stroke-width:1px
    classDef config fill:#E5E7E9,stroke:#566573,stroke-width:1px
```
