$ show OpenEtherCATsociety/SOEM
Simple Open EtherCAT Master (SOEM) is a lightweight, portable C library that implements the EtherCAT master protocol stack. It provides full support for CoE (CANopen over EtherCAT), FoE (File over EtherCAT), SoE (Servo over EtherCAT), EoE (Ethernet over EtherCAT), Distributed Clocks (DC), SII (Slave Information Interface), and network redundancy (dual NIC). The architecture is modular: an OS abstraction layer (osal) encapsulates platform-specific threading, timing, and memory operations, while a hardware abstraction layer (oshw) handles raw network access via sockets (Linux, Windows, RTEMS, VxWorks, etc.). The core library functions (ecx_*) operate on a context structure, enabling multiple master instances. Key implementation patterns include an indexed buffer management system for out-of-order frame handling, a thread-safe mailbox pool and queue, and a circular error ring buffer. The library is not a standalone application; it is designed to be embedded into industrial real-time control systems. Sample applications demonstrate cyclic process data exchange, SDO access, EEPROM manipulation, and firmware updates. The codebase is mature (2005–2025) and under active development, with a dual GPLv3/commercial license. Some technical drift exists due to bundled third-party WinPcap headers and several platform-specific contributor directories that may lag behind core updates. Overall, the library demonstrates strong engineering with clear separation of concerns and portability, making it a solid foundation for EtherCAT master development.
The LLM identified 3 files worth highlighting for reuse:
The OS abstraction layer (osal) provides a platform-independent API for threading, mutexes, timers, and memory allocation. Each platform (Linux, Windows, RTEMS, etc.) implements osal.c and osal_defs.h with the same interface. This pattern is highly reusable: any C project that needs to abstract OS primitives can extract this layer and add new platform backends without modifying core logic. The header osal.h defines clean, minimal functions (e.g., osal_thread_create, osal_usleep, osal_mutex_lock) and uses macros like OSAL_PACKED for cross-platform binary compatibility.
The NIC driver for Linux implements an indexed buffer management pattern for handling out-of-order EtherCAT frames. It uses a circular array of buffers (EC_MAXBUF) with a state machine (EC_BUF_EMPTY, EC_BUF_ALLOC, EC_BUF_TX, EC_BUF_RCVD, EC_BUF_COMPLETE) to track send/receive progress. This pattern enables automatic retransmission of lost frames and reordering of responses. The logic is isolated in ecx_outframe/ecx_inframe/ecx_srconfirm functions and can be extracted as a generic network buffer manager for any protocol that requires reliable, out-of-order frame delivery over a datagram socket.
The mailbox pool and queue implementation (ecx_getmbx, ecx_dropmbx, ecx_mbxaddqueue, ecx_mbxdropqueue) provides a thread-safe producer-consumer pattern for managing mailbox buffers. It stores free buffers in a pool and pending mailboxes in a queue, protected by a mutex. This pattern is reusable for any message-passing system where multiple threads need to allocate and enqueue fixed-size buffers without dynamic memory allocation. The code uses a simple ring buffer approach with clear ownership semantics.