A lightweight, efficient EtherCAT master/slave stack for embedded and real-time systems

Overview

KickCAT is a thin EtherCAT stack designed to be embedded in larger software with efficiency in mind. It provides both master and slave implementations in one codebase and runs on Linux (including RT-PREEMPT), Windows, PikeOS, and NuttX.

CoE (CANopen over EtherCAT) is fully supported on both sides. Beyond the stack itself, KickCAT ships a complete software ESC and network emulator, GUIs, and CLI tooling, so a bus can be developed, configured, and tested without physical hardware.

For exactly what is and isn't supported, see the feature support matrix.

Capabilities

Master stack

• Full EtherCAT State Machine (INIT, PRE-OP, SAFE-OP, OP)
• Process data (PDO) read/write
• CoE: SDO read/write (expedited, normal, segmented), SDO Information, Emergency
• Bus diagnostics with error counters
• Cable redundancy
• Consecutive writes (up to 255 datagrams in flight)
• Mailbox gateway (ETG.8200)
• Distributed Clock (experimental)
• AF_XDP socket backend on Linux (opt-in, lower latency)
• Python bindings

Slave stack

• Full EtherCAT State Machine
• Process data read/write
• CoE: Object Dictionary, SDO (including segmented and SDO Information)
• ESC support: LAN9252 (SPI), XMC4800
• EEPROM provisioning tooling
• Conformance Test Tool (CTT) validated (WDC_FOOT)

Mailbox protocols

CoE is fully supported on master and slave. FoE is experimental on master and slave (file transfer, including firmware update in the Bootstrap state). EoE is planned. SoE, AoE, and VoE are not currently on the roadmap (no maintainer hardware to test against) -- contributions are welcome. See the feature support matrix for the full breakdown.

Tooling and GUIs

• KickUI -- ImGui bus dashboard: topology view, SDO/PDO/FoE panels, DS402 motor bench
• EEPROM editor -- ImGui structured SII/EEPROM editor
• eeprom -- CLI to read/write slave EEPROM
• foe -- CLI to read/write a file on a slave over FoE
• scan_topology -- enumerate slaves and per-port link status
• check_network_stability -- monitor packet loss/corruption over time (Linux)
• od_generator -- generate CoE Object Dictionary code from ESI files
• ethercat_gui -- PySide6 bus monitoring application

See docs/TOOLS.md for usage.

Simulation and emulation

KickCAT includes a software EtherCAT Slave Controller (EmulatedESC: registers, SyncManagers, FMMUs, DC clock, EEPROM) and a network fabric (EmulatedNetwork: topology routing, redundancy, runtime wire break/heal). Run a master against it either in-process (the simulated_bus example) or as a separate process (network_simulator over a shared-memory TAP socket).

See docs/SIMULATION.md.

Getting started

Build the stack and tools (Linux):

./scripts/configure.sh build --with=unit_tests
./scripts/setup_build.sh build
cd build && make -j

Then run a master against an emulated slave -- no hardware, single process:

./build/examples/master/simulated_bus/simulated_bus \
    -f examples/slave/lan9252/freedom-k64f/nuttx/freedom-k64f.xml -t Board

Point -f at any vendor ESI XML and -t at the device <Type> to emulate a different slave. Beckhoff publish ESI files for their devices at https://download.beckhoff.com/download/configuration-files/io/ethercat/xml-device-description.

Where to go next:

• Build, install, Python bindings, Windows/PikeOS -- docs/BUILDING.md
• Real hardware: slave firmware, flashing, end-to-end walkthrough -- docs/HARDWARE.md
• Simulator and emulator -- docs/SIMULATION.md
• Tools and GUIs -- docs/TOOLS.md
• Real-time performance tuning -- docs/PERFORMANCE.md

Platform support

The master runs as a host OS process; the slave runs the stack on an RTOS against an EtherCAT Slave Controller (ESC).

Master (host OS):

Slave (NuttX RTOS + ESC):

Reference boards: NXP Freedom K64F (LAN9252), Arduino Due with EasyCAT shield (LAN9252), Infineon XMC4800 Relax Kit (XMC4800). See the hardware guide.

Documentation

• Feature support matrix
• Building and installing
• Hardware guide
• Simulation and emulation
• Tools and GUIs
• Real-time performance tuning
• Architecture overview
• Release procedure

EtherCAT references

• ETG official documentation
• Beckhoff EtherCAT documentation
• Beckhoff ESI (XML device description) files
• ESC datasheets
• EtherCAT Device Protocol Poster
• ESC comparison

Contributing

Contributions are welcome. See CONTRIBUTING.md for code-style and PR conventions, and docs/BUILDING.md for the development build (unit tests and coverage).

KickCAT follows Semantic Versioning. The release workflow is documented in release/RELEASE_PROCEDURE.md.

License

CeCILL-C

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Conan package: conan-center-index

Status: actively maintained and used in production systems. See Releases for the latest stable version.