# shkwon98/epos4-soem architecture

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

- Interactive diagram: https://gitdiagram.com/shkwon98/epos4-soem
- Repository: https://github.com/shkwon98/epos4-soem

## Overview

##### Project Type and Purpose
- The application is a real-time EtherCAT master used to control EtherCAT slave devices (such as epos4 and elmo). It runs on a Raspberry Pi 4 with a Preempt-rt Linux kernel and integrates with external GUIs on a remote PC.
- The README and file tree indicate that this is a full-fledged, real-time control system with distinct modules managing real-time scheduling, EtherCAT communication (via the SOEM dependency), control logic, and socket communication.

##### Analyzing the File Structure
- Top-Level Modules:
- ansur_control: Contains files like CControlThread.cpp and tcpCommand.cpp, which likely implement the control loops and TCP-based commands used for system control.
- ansur_ethercat: Implements the EtherCAT-related functionality with modules such as CPdoMapping.cpp and SOEM.cpp. This module is responsible for interacting with the EtherCAT slaves.
- ansur_socket: Handles networking, incorporating both TCP and UDP packet implementations. This module is key for interfacing with external components, for example when a remote GUI is used.
- ansur_thread: Contains functionality for thread looping and scheduling. In a real-time environment, proper thread management is crucial.
- Supporting Files:
- main.cpp serves as the entry point which likely initializes and coordinates these modules.
- Multiple CMakeLists.txt files indicate that each component is somewhat independent, hinting at a modular architecture.

##### Diagramming the System – Main Components and Relationships
a. Main Components:
- Real-Time Control Engine (ansur_control): Implements control threads and command handling.
- EtherCAT Communication Module (ansur_ethercat): Manages EtherCAT communications with slave devices via SOEM.
- Socket Communication Module (ansur_socket): Facilitates network communication (TCP/UDP) for external interfacing.
- Thread Management and Scheduling Module (ansur_thread): Ensures real-time task scheduling and looping.
- Main Application (main.cpp): Acts as the orchestrator integrating all these components.
- External Interfaces:
- EtherCAT Slave Devices: The physical devices controlled over the EtherCAT bus.
- Remote GUI (epos4-soem-gui): Running on a remote PC for visualization and interaction.
- Underlying RTOS & Hardware: Raspberry Pi with Preempt-rt Linux ensuring deterministic behavior.

b. Relationships and Interactions:
- The Main Application initializes and coordinates the overall system.
- The Control Engine interacts with the EtherCAT Communication Module to send commands and receive status from the EtherCAT slaves.
- It also uses the Socket Communication Module to exchange data with remote systems (like the GUI).
- The Thread Management module underpins both control and communication modules to ensure that real-time scheduling is enforced.
- Data flows from the main control loops (in ansur_control) to update the EtherCAT states (via ansur_ethercat) and to package/send/receive network data (via ansur_socket).

c. Architectural Patterns and Design Principles:
- Modularity: The project is divided into clear, cohesive modules (control, EtherCAT, socket, thread management).
- Real-Time Systems Design: Special emphasis on thread scheduling and deterministic data flows, given the use of Preempt-rt.
- Separation of Concerns: Each module focuses on a specific functionality (e.g., control logic vs. EtherCAT communication).
- Integration via a central coordinating point (main.cpp) ensuring that these modules interact correctly.

d. Relevant Technologies, Frameworks, or Libraries:
- SOEM (Simple Open EtherCAT Master) is a key dependency used in the EtherCAT module.
- CMake is used as the build system, suggesting that modules can be built and maintained independently.
- Standard C++ libraries and possibly custom threading constructs for real-time scheduling are involved.
- Networking libraries for TCP/UDP communication in the socket module.
- Real-Time Linux (Preempt-rt patched kernel) on Raspberry Pi, which influences the design of thread scheduling and control loops.

##### Final Checklist
- Main Application (main.cpp)
- Control Engine (ansur_control)
- EtherCAT Communication (ansur_ethercat)
- Socket Communication (ansur_socket)
- Thread Management (ansur_thread)
- External Interfaces (EtherCAT Slaves, Remote GUI, RTOS/Hardware)
- Initialization/control flows from main.cpp to other modules.
- Data flows from the control engine to the EtherCAT module and to the socket module.
- External communications between the system and remote devices.
- Detail the architectural patterns like modularity, real-time scheduling, and separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Nodes
    MainApp("Main Application (main.cpp)"):::module

    subgraph "Real-Time Control Engine (ansur_control)"
        CControlThread("CControlThread"):::internal
        tcpCommand("tcpCommand"):::internal
    end

    subgraph "EtherCAT Communication (ansur_ethercat)"
        SOEM("SOEM"):::internal
        CPdoMapping("CPdoMapping"):::internal
    end

    subgraph "Socket Communication (ansur_socket)"
        CTcpPacket("CTcpPacket"):::internal
        CUdpPacket("CUdpPacket"):::internal
    end

    subgraph "Thread Management (ansur_thread)"
        CLoopingThread("CLoopingThread"):::internal
        scheduling("scheduling"):::internal
    end

    %% External Interfaces
    EthercatSlaves("EtherCAT Slaves"):::external
    RemoteGUI("Remote GUI (epos4-soem-gui)"):::external
    RTOS("RTOS/Hardware (Raspberry Pi with Preempt-rt)"):::external

    %% Connections from Main Application to modules
    MainApp -->|"init"| CControlThread
    MainApp -->|"init"| SOEM
    MainApp -->|"init"| CTcpPacket
    MainApp -->|"init"| CLoopingThread

    %% Internal Module Interactions
    CControlThread -->|"control_status"| SOEM
    tcpCommand -->|"TCP_cmd"| CTcpPacket

    %% Thread Management supports control and communication
    CLoopingThread -->|"scheduling"| CControlThread
    CLoopingThread -->|"scheduling"| tcpCommand
    CLoopingThread -->|"scheduling"| SOEM
    CLoopingThread -->|"scheduling"| CTcpPacket

    %% External Interactions
    SOEM -->|"EtherCAT_Data"| EthercatSlaves
    CPdoMapping -->|"mapping_info"| SOEM
    CTcpPacket -->|"TCP_Packets"| RemoteGUI
    CUdpPacket -->|"UDP_Packets"| RemoteGUI

    %% Underlying RTOS underpins the system
    RTOS -->|"runs_on"| MainApp
    RTOS -->|"supports"| CLoopingThread

    %% Styles for clarity
    classDef module fill:#A3BE8C,stroke:#2E3440,stroke-width:2px,color:#2E3440;
    classDef internal fill:#EBCB8B,stroke:#2E3440,stroke-width:2px,color:#2E3440;
    classDef external fill:#BF616A,stroke:#2E3440,stroke-width:2px,color:#2E3440;

    %% Click Events for Component Mapping
    click MainApp "https://github.com/shkwon98/epos4-soem/blob/main/main.cpp"
    click CControlThread "https://github.com/shkwon98/epos4-soem/blob/main/ansur_control/src/CControlThread.cpp"
    click tcpCommand "https://github.com/shkwon98/epos4-soem/blob/main/ansur_control/src/tcpCommand.cpp"
    click SOEM "https://github.com/shkwon98/epos4-soem/blob/main/ansur_ethercat/src/SOEM.cpp"
    click CPdoMapping "https://github.com/shkwon98/epos4-soem/blob/main/ansur_ethercat/src/CPdoMapping.cpp"
    click CTcpPacket "https://github.com/shkwon98/epos4-soem/blob/main/ansur_socket/src/CTcpPacket.cpp"
    click CUdpPacket "https://github.com/shkwon98/epos4-soem/blob/main/ansur_socket/src/CUdpPacket.cpp"
    click CLoopingThread "https://github.com/shkwon98/epos4-soem/blob/main/ansur_thread/src/CLoopingThread.cpp"
    click scheduling "https://github.com/shkwon98/epos4-soem/blob/main/ansur_thread/src/scheduling.cpp"
```
