EtherCAT¶

Status: Planned

This module is not yet implemented. The design below represents the target architecture.

Overview¶

EtherCAT (Ethernet for Control Automation Technology) is a high-performance industrial Ethernet protocol. A single Ethernet frame passes through all slaves in sequence each device extracts/inserts data on-the-fly with hardware-timestamped processing. Achieves sub-microsecond synchronization and deterministic cycle times.

Architecture¶

┌─────────────────────────────────────────────────────────────────────┐
│  EtherCAT "Processing on the Fly":                                   │
│                                                                      │
│  ┌────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐           │
│  │ Master │───►│ Slave 1 │───►│ Slave 2 │───►│ Slave N │──┐        │
│  │        │◄───│  (servo) │◄───│  (I/O)  │◄───│ (sensor)│  │        │
│  └────────┘    └─────────┘    └─────────┘    └─────────┘  │        │
│       ▲                                                     │        │
│       └─────────────────────────────────────────────────────┘        │
│                          (frame returns to master)                    │
│                                                                      │
│  Single frame traverses all slaves in < 100 µs (100+ nodes)          │
│  Each slave processes in hardware: read/write from frame in-flight   │
└─────────────────────────────────────────────────────────────────────┘

EtherCAT Frame Format¶

┌──────────────────────────────────────────────────────────────────────┐
│ Ethernet Header │ EtherCAT │    Datagram 1    │   Datagram 2  │ ... │
│  (14 bytes)     │  Header  │ (Cmd+Addr+Data+WKC)│              │     │
│ EtherType=0x88A4│  (2 B)   │                    │              │     │
└──────────────────────────────────────────────────────────────────────┘

EtherCAT Datagram:
┌──────────┬──────────┬────────┬──────────────────┬─────┐
│ Command  │ Address  │ Length │      Data        │ WKC │
│ (1 byte) │ (4 bytes)│(2 bytes)│  (variable)     │(2 B)│
└──────────┴──────────┴────────┴──────────────────┴─────┘

WKC (Working Counter): incremented by each slave that processes the datagram

Command Types¶

Command	Code	Description
NOP	0x00	No operation
APRD	0x01	Auto-increment physical read
APWR	0x02	Auto-increment physical write
APRW	0x03	Auto-increment physical read-write
FPRD	0x04	Fixed-address physical read
FPWR	0x05	Fixed-address physical write
BRD	0x07	Broadcast read
BWR	0x08	Broadcast write
LRD	0x0A	Logical read
LWR	0x0B	Logical write
LRW	0x0C	Logical read-write

Planned API¶

typedef struct {
    raw_socket_t raw;              /* Underlying raw socket */
    uint16_t     slave_count;      /* Discovered slaves */
    uint32_t     cycle_time_us;    /* Target cycle time */
    uint64_t     dc_offset_ns;     /* Distributed clock offset */
    uint64_t     frames_sent;
    uint64_t     wkc_errors;       /* Working counter mismatches */
} ecat_master_t;

typedef struct {
    uint16_t position;             /* Auto-increment position */
    uint16_t configured_addr;      /* Fixed station address */
    uint32_t vendor_id;
    uint32_t product_code;
    uint8_t  state;                /* INIT/PREOP/SAFEOP/OP */
} ecat_slave_info_t;

/* Master lifecycle */
int ecat_master_init(ecat_master_t *master, const char *if_name);
int ecat_scan_bus(ecat_master_t *master, ecat_slave_info_t *slaves, int max);
int ecat_master_close(ecat_master_t *master);

/* State machine transitions */
int ecat_set_state(ecat_master_t *master, uint16_t slave_addr, uint8_t state);

/* Cyclic PDO exchange */
int ecat_exchange(ecat_master_t *master, void *output_pdo, size_t out_len,
                  void *input_pdo, size_t in_len);

/* Distributed clocks */
int ecat_dc_sync(ecat_master_t *master, uint32_t cycle_time_ns);

Performance Targets¶

Metric	Target	Notes
Cycle time	50–250 µs	Depending on PDO size
Jitter	< 1 µs	With DC synchronization
Max slaves	65535	Per network segment
Frame processing	~1 µs per slave	On-the-fly hardware processing

Slave State Machine¶

stateDiagram-v2
    [*] --> INIT
    INIT --> PRE_OP : Mailbox configured
    PRE_OP --> SAFE_OP : PDO mapping configured
    SAFE_OP --> OP : Outputs valid
    OP --> SAFE_OP : Error / stop
    SAFE_OP --> PRE_OP : Reconfigure
    PRE_OP --> INIT : Reset

Implementation Roadmap¶

EtherCAT frame construction (EtherType 0x88A4)
Datagram command encoding (LRW, FPRD, FPWR)
Bus scan via auto-increment addressing
Slave state machine management
PDO (Process Data Object) cyclic exchange
Distributed Clocks (DC) synchronization
SDO (Service Data Object) mailbox protocol (CoE)
Working counter validation
Integration with epoll_reactor (timer-driven cycles)