EtherDOG is an EtherCAT master service. It runs one or more EtherCAT masters from a JSON bus configuration and exchanges process data with a client program over local sockets. The process image travels as one datagram in each direction per bus cycle, and a line-based JSON control channel handles configuration, discovery and status.
Built on SOEM.
- Several masters, each on its own interface, with a dedicated SCHED_FIFO bus thread and absolute-deadline timing.
- Topology validation, SDO configuration, PDO mapping, optional distributed clocks and per-slave watchdogs.
- Slave AL states read in every bus cycle, and background monitoring with automatic slave recovery. The bus thread never waits for the monitor.
- Bus scan and slave test for discovery.
- A published process-data layout per master: every PDO entry with its bit offset.
- A per-cycle data exchange over AF_UNIX or loopback UDP, with session ids, sequence checks and an output watchdog (outputs go to zero when the client goes quiet).
- Status and diagnostics with cycle, period and wake-up latency statistics.
- Logs on stderr, in an in-memory ring (the
logscommand), and optionally streamed as JSON lines to a log socket. - Linux, and Windows through MSYS2 (Npcap required).
git clone --recurse-submodules https://github.com/Autonomy-Logic/EtherDOG
cmake -S EtherDOG -B EtherDOG/build -DCMAKE_BUILD_TYPE=Release
cmake --build EtherDOG/build -jThis needs CMake 3.28 or newer (for SOEM). Add -DETHERDOG_BUILD_TESTS=ON and run ctest --test-dir EtherDOG/build for the unit tests.
sudo ./build/etherdog --config examples/ek1818_busconfig.json --start| Option | Default |
|---|---|
--control <spec> |
unix:/run/etherdog/etherdog.socket |
--allow-uid <uid> |
none. Unix socket clients must run as EtherDOG's user, root, or one of these. |
--token-stdin |
off. Reads a token from stdin (or $ETHERDOG_TOKEN); clients must send it. Required for tcp:. |
--state-dir <dir> |
/run/etherdog |
--config <file> |
none |
--start |
start the bus after loading --config |
--log-level <level> |
info |
--log-socket <spec> |
none |
Raw Ethernet access and real-time scheduling need root, or CAP_NET_RAW and CAP_SYS_NICE. CAP_NET_ADMIN is optional: without it the NIC tuning (ethtool coalescing and offloads) is skipped. Promiscuous mode is requested per socket and needs no extra capability.
On Linux the build applies the patches in patches/soem/ to a copy of the SOEM sources in the build directory; the libs/soem submodule is not modified. Configuration fails if a patch no longer applies to the pinned SOEM commit.
- docs/PROTOCOL.md: the control commands and the data frames.
- docs/BUSCONFIG.md: the bus configuration format.
- tools/etherdog_client.py: a reference client in plain Python.
python3 tools/etherdog_client.py status
python3 tools/etherdog_client.py layout
python3 tools/etherdog_client.py io --seconds 5 --set 1:0x7000:1=blinkGPL-3.0-or-later. See LICENSE. include/etherdog_protocol.h and tools/etherdog_client.py are MIT.