# cherry-embedded/cherryecat architecture

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

- Interactive diagram: https://gitdiagram.com/cherry-embedded/cherryecat
- Repository: https://github.com/cherry-embedded/cherryecat

## Overview

CherryECAT is an MCU/RTOS EtherCAT master stack. An application configures and starts a master; it scans and configures slaves, then exchanges cyclic PDO datagrams while handling mailbox protocols and distributed-clock synchronization. Shell commands expose master operations, and the repository also provides ESI/ENI conversion tools. The graph combines README-documented capabilities with sampled source and SOURCE INDEX references; some subsystem links are documented rather than verified call paths.

Main entry points: [`src/ec_slave.c`](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_slave.c) (Slave Scan and Setup), [`src/ec_master.c`](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_master.c) (Master Runtime), [`src/ec_mailbox.c`](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_mailbox.c) (Mailbox Transfer), [`src/ec_datagram.c`](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_datagram.c) (Datagram Queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Master Control"]
  node_master["Master Runtime<br/>[ec_master.c]"]
  node_commands["Shell Commands<br/>[ec_cmd.c]"]
  node_clocks["Distributed Clocks<br/>[ec_slave.c]"]
end

subgraph group_protocol["Slave Protocol"]
  node_slave["Slave Scan and Setup<br/>[ec_slave.c]"]
  node_slave_table["Slave Information<br/>[ec_slave_table.c]"]
  node_sii["SII Access<br/>[ec_sii.c]"]
  node_mailbox["Mailbox Transfer<br/>[ec_mailbox.c]"]
  node_coe["CoE<br/>[ec_coe.c]"]
  node_foe["FoE<br/>[ec_foe.c]"]
  node_eoe["EoE<br/>[ec_eoe.c]"]
  node_pdo["PDO Cycles<br/>[ec_master.h]"]
end

subgraph group_transport["Ethernet Transport"]
  node_datagrams["Datagram Queue<br/>[ec_datagram.c]"]
  node_network["Network Interface<br/>[ec_netdev.c]"]
  node_boardport["Board Ethernet Ports"]
  node_phy["PHY Detection<br/>[chry_phy.c]"]
end

subgraph group_platform["RTOS Platform"]
  node_osal["RTOS Abstraction<br/>[ec_osal.h]"]
  node_rtos_ports["RTOS Adapters"]
end

subgraph group_tools["Configuration Tools"]
  node_esi_tool["ESI Parser<br/>[esi_parser.py]"]
  node_eni_tool["ENI Parser<br/>[eni_parser.py]"]
end

node_application(("RT Application"))
node_shell(("Shell User"))
node_bus(("EtherCAT Slaves"))
node_esi_input["ESI Description"]
node_eni_input["ENI Configuration"]

node_application -->|"configures"| node_master
node_shell -->|"invokes"| node_commands
node_commands -->|"controls"| node_master
node_master -->|"scans and configures"| node_slave
node_slave -->|"queues register access"| node_datagrams
node_master -->|"queues transfers"| node_datagrams
node_master -->|"runs cyclic exchange"| node_pdo
node_pdo -->|"transfers PDOs"| node_datagrams
node_datagrams -->|"sends and receives"| node_network
node_network -->|"uses driver"| node_boardport
node_boardport -->|"configures PHY"| node_phy
node_network -->|"communicates"| node_bus
node_slave -->|"updates topology"| node_slave_table
node_slave -->|"reads slave EEPROM"| node_sii
node_slave -->|"uses mailbox"| node_mailbox
node_mailbox -->|"carries CoE"| node_coe
node_mailbox -->|"carries FoE"| node_foe
node_mailbox -->|"carries EoE"| node_eoe
node_slave -->|"configures clock sync"| node_clocks
node_master -->|"uses RTOS services"| node_osal
node_osal -->|"implemented by"| node_rtos_ports
node_esi_input -->|"parses"| node_esi_tool
node_esi_tool -->|"generates EEPROM data"| node_sii
node_eni_input -->|"parses"| node_eni_tool
node_eni_tool -->|"generates sync config"| node_slave

click node_master "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_master.c"
click node_commands "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_cmd.c"
click node_datagrams "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_datagram.c"
click node_network "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_netdev.c"
click node_boardport "https://github.com/cherry-embedded/cherryecat/tree/master/port"
click node_phy "https://github.com/cherry-embedded/cherryecat/blob/master/src/phy/chry_phy.c"
click node_slave "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_slave.c"
click node_slave_table "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_slave_table.c"
click node_sii "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_sii.c"
click node_mailbox "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_mailbox.c"
click node_coe "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_coe.c"
click node_foe "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_foe.c"
click node_eoe "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_eoe.c"
click node_pdo "https://github.com/cherry-embedded/cherryecat/blob/master/include/ec_master.h"
click node_clocks "https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_slave.c"
click node_osal "https://github.com/cherry-embedded/cherryecat/blob/master/include/ec_osal.h"
click node_rtos_ports "https://github.com/cherry-embedded/cherryecat/tree/master/osal"
click node_esi_tool "https://github.com/cherry-embedded/cherryecat/blob/master/scripts/esi_parser.py"
click node_eni_tool "https://github.com/cherry-embedded/cherryecat/blob/master/scripts/eni_parser.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_master,node_commands,node_clocks,node_shell toneBlue
class node_slave,node_slave_table,node_sii,node_mailbox,node_coe,node_foe,node_eoe,node_pdo toneAmber
class node_datagrams,node_network,node_boardport,node_phy toneMint
class node_osal,node_rtos_ports toneRose
class node_esi_tool,node_eni_tool,node_application,node_bus,node_esi_input,node_eni_input toneIndigo
```

## Components

### Master Control

- [Master Runtime](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_master.c): `src/ec_master.c`
- [Shell Commands](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_cmd.c): `src/ec_cmd.c`
- [Distributed Clocks](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_slave.c): `src/ec_slave.c`

### Slave Protocol

- [Slave Scan and Setup](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_slave.c): `src/ec_slave.c`
- [Slave Information](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_slave_table.c): `src/ec_slave_table.c`
- [SII Access](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_sii.c): `src/ec_sii.c`
- [Mailbox Transfer](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_mailbox.c): `src/ec_mailbox.c`
- [CoE](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_coe.c): `src/ec_coe.c`
- [FoE](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_foe.c): `src/ec_foe.c`
- [EoE](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_eoe.c): `src/ec_eoe.c`
- [PDO Cycles](https://github.com/cherry-embedded/cherryecat/blob/master/include/ec_master.h): `include/ec_master.h`

### Ethernet Transport

- [Datagram Queue](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_datagram.c): `src/ec_datagram.c`
- [Network Interface](https://github.com/cherry-embedded/cherryecat/blob/master/src/ec_netdev.c): `src/ec_netdev.c`
- [Board Ethernet Ports](https://github.com/cherry-embedded/cherryecat/tree/master/port): `port`
- [PHY Detection](https://github.com/cherry-embedded/cherryecat/blob/master/src/phy/chry_phy.c): `src/phy/chry_phy.c`

### RTOS Platform

- [RTOS Abstraction](https://github.com/cherry-embedded/cherryecat/blob/master/include/ec_osal.h): `include/ec_osal.h`
- [RTOS Adapters](https://github.com/cherry-embedded/cherryecat/tree/master/osal): `osal`

### Configuration Tools

- [ESI Parser](https://github.com/cherry-embedded/cherryecat/blob/master/scripts/esi_parser.py): `scripts/esi_parser.py`
- [ENI Parser](https://github.com/cherry-embedded/cherryecat/blob/master/scripts/eni_parser.py): `scripts/eni_parser.py`

### Other components

- **RT Application**
- **Shell User**
- **EtherCAT Slaves**
- **ESI Description**
- **ENI Configuration**

## Connections

- RT Application → Master Runtime: configures (evidence: `README.md`)
- Shell User → Shell Commands: invokes (evidence: `README.md`)
- Shell Commands → Master Runtime: controls (evidence: `src/ec_cmd.c`)
- Master Runtime → Slave Scan and Setup: scans and configures (evidence: `README.md`)
- Slave Scan and Setup → Datagram Queue: queues register access (evidence: `src/ec_slave.c`)
- Master Runtime → Datagram Queue: queues transfers (evidence: `README.md`)
- Master Runtime → PDO Cycles: runs cyclic exchange (evidence: `README.md`)
- PDO Cycles → Datagram Queue: transfers PDOs (evidence: `README.md`)
- Datagram Queue → Network Interface: sends and receives (evidence: `src/ec_datagram.c`)
- Network Interface → Board Ethernet Ports: uses driver (evidence: `port/netdev_stm32h7.c`)
- Board Ethernet Ports → PHY Detection: configures PHY (evidence: `port/netdev_stm32h7.c`)
- Network Interface → EtherCAT Slaves: communicates (evidence: `README.md`)
- Slave Scan and Setup → Slave Information: updates topology (evidence: `README.md`)
- Slave Scan and Setup → SII Access: reads slave EEPROM (evidence: `README.md`)
- Slave Scan and Setup → Mailbox Transfer: uses mailbox (evidence: `README.md`)
- Mailbox Transfer → CoE: carries CoE (evidence: `README.md`)
- Mailbox Transfer → FoE: carries FoE (evidence: `README.md`)
- Mailbox Transfer → EoE: carries EoE (evidence: `README.md`)
- Slave Scan and Setup → Distributed Clocks: configures clock sync (evidence: `src/ec_slave.c`)
- Master Runtime → RTOS Abstraction: uses RTOS services
- RTOS Abstraction → RTOS Adapters: implemented by (evidence: `osal/ec_osal_threadx.c`)
- ESI Description → ESI Parser: parses (evidence: `README.md`)
- ESI Parser → SII Access: generates EEPROM data (evidence: `README.md`)
- ENI Configuration → ENI Parser: parses (evidence: `README.md`)
- ENI Parser → Slave Scan and Setup: generates sync config (evidence: `README.md`)