# kubabuda/ecat_servo architecture

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

- Interactive diagram: https://gitdiagram.com/kubabuda/ecat_servo
- Repository: https://github.com/kubabuda/ecat_servo

## Overview

##### Project type and purpose
- This is an embedded‐focused, open‐source servo‐drive device implementation for the EtherCAT CoE CiA402 standard, targeting STM32 (F1/F4) and Arduino platforms.
- The core is the “cia402device” library, which implements the CiA402 state machine and PDO interfaces. The rest of the repo contains documentation and multiple PlatformIO example projects (SOES‐based, EasyCAT‐based, Arduino) showing how to hook the core into different EtherCAT slave stacks and hardware.

##### File structure
– Root: LICENSE, README.md, high‐level docs/ and examples/ folders.
– cia402device/
- / – public headers for the CiA402 API
- lib/cia402device – the implementation (cia402device.c/h)
- src/main.c – a minimal demo/main stub
- test/ – unit tests of the core library
- platformio.ini – build config for the core device library
– docs/ – markdown and generated HTML docs explaining hardware boards, software tools, design decisions
– examples/ – sub-folders, each a complete PlatformIO project that layers:
- / – app headers
- lib/ – BSP (STM32 or Arduino HAL), EtherCAT slave stack (SOES or EasyCAT), plus cia402device pulled in
- src/ – application entry (main.c/.cpp + control‐loop integration)
- test/ – any example‐specific tests
- platformio.ini – build & upload instructions

##### README for additional insights
- The README clarifies that EtherCAT frames come in over SPI from either a LAN9252 or AX58100 ESC chip, processed by a slave stack (SOES or EasyCAT), then fed into the CiA402 state machine in the core library.
- Example projects show how to wire up: ESC chip → STM32 HAL/BSP → SOES/EasyCAT → cia402device → your motion control logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Physical Layer" 
        direction TB
        Master["EtherCAT Master (PC/PLC)"]:::hw
        Ethernet["Ethernet Network"]:::hw
        ESC["ESC Chip (LAN9252/AX58100)"]:::hw
        MotorHW["Motor & Drive Electronics"]:::hw
    end

    %% MCU Layer
    subgraph "MCU Firmware (STM32/Arduino)" 
        direction TB
        SPI["SPI HAL/BSP"]:::hw
        subgraph "EtherCAT Slave Stack" 
            direction TB
            SOES["SOES or EasyCAT Stack"]:::protocol
        end
        subgraph "CiA402 Device Core" 
            direction TB
            CiA402_API["Public API Headers"]:::core
            CiA402_Impl["Implementation (cia402device.c/.h)"]:::core
            Core_Demo["Demo Stub (main.c)"]:::core
        end
        subgraph "Application Layer" 
            direction TB
            App["Motor Control App"]:::app
        end
    end

    %% Auxiliary
    subgraph "Documentation & Tests" 
        direction TB
        Docs_MD["Docs (markdown)"]:::aux
        Docs_HTML["Docs (generated HTML)"]:::aux
        Core_Tests["Core Unit Tests"]:::aux
        Core_Build["Core Build Config"]:::aux
        Ex_Builds["Examples Build Configs"]:::aux
        Ex_Tests["Example Tests"]:::aux
    end

    %% Example Projects
    subgraph "Example Projects" 
        direction TB
        subgraph "EasyCAT SPL Example" 
            direction TB
            EasyCAT_BSP["BSP (STM32 HAL)"]:::example
            EasyCAT_LIB["EasyCAT Stack"]:::example
            EasyCAT_AppMain["src/main.c"]:::example
            EasyCAT_ECATApp["src/ECAT_App.c"]:::example
            EasyCAT_ESI["ESI PDO Definitions"]:::example
        end
        subgraph "SOES + AX58100 Example" 
            direction TB
            SOES_AX58100_BSP["BSP & HAL"]:::example
            SOES_AX58100_SOES["SOES Stack"]:::example
            SOES_AX58100_CIA["cia402device Integration"]:::example
            SOES_AX58100_AppMain["src/main.c"]:::example
            SOES_AX58100_EcatApp["src/ecatapp.c"]:::example
        end
        subgraph "SOES + LAN9252 Example" 
            direction TB
            SOES_LAN9252_BSP["BSP & HAL"]:::example
            SOES_LAN9252_SOES["SOES Stack"]:::example
            SOES_LAN9252_App["src/main.c"]:::example
        end
        subgraph "EasyCAT Arduino Example" 
            direction TB
            EasyCAT_Arduino_LIB["EasyCAT Library"]:::example
            EasyCAT_Arduino_App["src/main.cpp"]:::example
        end
        subgraph "Arduino SOES Example" 
            direction TB
            Arduino_SOES_HAL["HAL (arduino-lan9252)"]:::example
            Arduino_SOES_App["src/main.cpp"]:::example
        end
        subgraph "Arduino AVR SOES Example" 
            direction TB
            ArduinoAVR_SOES_HAL["HAL (arduino-lan9252)"]:::example
            ArduinoAVR_SOES_App["src/main.cpp"]:::example
        end
    end

    %% Connections
    Master -->|"EtherCAT frames"| Ethernet
    Ethernet --> ESC
    ESC -->|"SPI bus"| SPI
    SPI --> SOES
    SOES -->|"PDO unpack"| CiA402_Impl
    CiA402_Impl -->|"State Machine"| CiA402_Impl
    CiA402_Impl -->|"Flags & Status"| App
    App -->|"PWM & Brake Control"| MotorHW
    App --> SOES
    SOES --> ESC
    ESC --> Ethernet
    Ethernet --> Master

    %% Aux connections
    Docs_MD -.-> CiA402_API
    Docs_HTML -.-> CiA402_API
    Core_Tests -.-> CiA402_Impl
    Core_Build -.-> CiA402_Impl
    Ex_Builds -.-> EasyCAT_BSP
    Ex_Tests -.-> EasyCAT_BSP

    %% Click Events
    click CiA402_API "https://github.com/kubabuda/ecat_servo/tree/main/cia402device/include"
    click CiA402_Impl "https://github.com/kubabuda/ecat_servo/blob/main/cia402device/lib/cia402device/cia402device.c"
    click Core_Demo "https://github.com/kubabuda/ecat_servo/blob/main/cia402device/src/main.c"
    click Core_Tests "https://github.com/kubabuda/ecat_servo/blob/main/cia402device/test/test_lib/test_cia402device.c"
    click Core_Build "https://github.com/kubabuda/ecat_servo/blob/main/cia402device/platformio.ini"
    click Docs_MD "https://github.com/kubabuda/ecat_servo/blob/main/docs/*.md"
    click Docs_HTML "https://github.com/kubabuda/ecat_servo/tree/main/docs/html/"
    click EasyCAT_BSP "https://github.com/kubabuda/ecat_servo/tree/main/examples/EasyCAT_SPL/lib/BSP"
    click EasyCAT_LIB "https://github.com/kubabuda/ecat_servo/tree/main/examples/EasyCAT_SPL/lib/EasyCAT"
    click EasyCAT_AppMain "https://github.com/kubabuda/ecat_servo/blob/main/examples/EasyCAT_SPL/src/main.c"
    click EasyCAT_ECATApp "https://github.com/kubabuda/ecat_servo/blob/main/examples/EasyCAT_SPL/src/ECAT_App.c"
    click EasyCAT_ESI "https://github.com/kubabuda/ecat_servo/tree/main/examples/EasyCAT_SPL/esi/DS402_PDOs_EasyCatProject/"
    click EasyCAT_Arduino_LIB "https://github.com/kubabuda/ecat_servo/tree/main/examples/EasyCAT_arduino/lib/EasyCAT/"
    click EasyCAT_Arduino_App "https://github.com/kubabuda/ecat_servo/blob/main/examples/EasyCAT_arduino/src/main.cpp"
    click SOES_AX58100_BSP "https://github.com/kubabuda/ecat_servo/tree/main/examples/SOES_CIA402_AX58100/lib/bsp"
    click SOES_AX58100_SOES "https://github.com/kubabuda/ecat_servo/tree/main/examples/SOES_CIA402_AX58100/lib/soes"
    click SOES_AX58100_CIA "https://github.com/kubabuda/ecat_servo/blob/main/examples/SOES_CIA402_AX58100/lib/cia402device/cia402device.c"
    click SOES_AX58100_AppMain "https://github.com/kubabuda/ecat_servo/blob/main/examples/SOES_CIA402_AX58100/src/main.c"
    click SOES_AX58100_EcatApp "https://github.com/kubabuda/ecat_servo/blob/main/examples/SOES_CIA402_AX58100/src/ecatapp.c"
    click SOES_LAN9252_BSP "https://github.com/kubabuda/ecat_servo/tree/main/examples/SOES_LAN9252/lib/bsp"
    click SOES_LAN9252_SOES "https://github.com/kubabuda/ecat_servo/tree/main/examples/SOES_LAN9252/lib/soes"
    click SOES_LAN9252_App "https://github.com/kubabuda/ecat_servo/blob/main/examples/SOES_LAN9252/src/main.c"
    click Arduino_SOES_HAL "https://github.com/kubabuda/ecat_servo/tree/main/examples/SOES_arduino/lib/soes/hal/arduino-lan9252"
    click Arduino_SOES_App "https://github.com/kubabuda/ecat_servo/blob/main/examples/SOES_arduino/src/main.cpp"
    click ArduinoAVR_SOES_HAL "https://github.com/kubabuda/ecat_servo/tree/main/examples/SOES_arduino_avr/lib/soes/hal/arduino-lan9252"
    click ArduinoAVR_SOES_App "https://github.com/kubabuda/ecat_servo/blob/main/examples/SOES_arduino_avr/src/main.cpp"

    %% Styles
    classDef hw fill:#cce5ff,stroke:#004085,color:#004085;
    classDef protocol fill:#d4edda,stroke:#155724,color:#155724;
    classDef core fill:#fff3cd,stroke:#856404,color:#856404;
    classDef app fill:#ffe5b4,stroke:#cc7a00,color:#cc7a00;
    classDef aux fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef example fill:#f0f0f0,stroke:#999,color:#333;
```
