KickCAT

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="doc/kickCAT_logo_dark_mode.png"> <source media="(prefers-color-scheme: light)" srcset="doc/kickCAT_logo_light_mode.png"> <img alt="KickCAT" width="300"> </picture><br> </p> <p align="center"> <strong>A lightweight, efficient EtherCAT master/slave stack for embedded systems</strong> </p> <p align="center"> <em>Kick-start your slaves! ⚡</em> </p>

---

Overview

KickCAT is a thin EtherCAT stack designed to be embedded in complex software with efficiency in mind. It provides both master and slave implementations, supporting multiple operating systems and hardware platforms.

Key Features:

• Works with Linux (including RT-PREEMPT), Windows, and PikeOS
• Full state machine support (INIT → PRE-OP → SAFE-OP → OP)
• CoE (CANopen over EtherCAT) support with SDO read/write
• CoE: SDO Information
• Interface redundancy
• Bus diagnostics and error handling
• Master side python bindings
• Built-in ESC emulator for testing without hardware

---

Quick Start

Prerequisites

• Linux: gcc, cmake, conan (for dependencies)
• Python bindings: uv or pip
• Hardware: Network interface with raw socket access capabilities

Build and Install

Linux (Recommended)

# 1. Setup build environment
./scripts/setup_build.sh build

# 2. Configure and build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

# 3. Grant network capabilities (required for raw socket access)
sudo setcap 'cap_net_raw,cap_net_admin=+ep' ./tools/your_binary

Python Bindings

# Install with uv (recommended)
uv pip install .

# Or for development (faster rebuilds)
uv pip install --no-build-isolation -Cbuild-dir=/tmp/build -v .

Multi wheel (CI)

This project use cibuildwheel to generate multiples wheel to support all configurations. To use it locally, call:

uvx cibuildwheel

<details> <summary><b>Manual Build Setup</b></summary>

# 1. Create build directory
mkdir -p build

# 2. Install dependencies with conan
python3 -m venv kickcat_venv
source kickcat_venv/bin/activate
pip install conan

conan install conan/conanfile_linux.txt -of=build/ \
  -pr:h conan/your_profile_host.txt \
  -pr:b conan/your_profile_target.txt \
  --build=missing -s build_type=Release

# Or create the conan package directly
conan create conan/all --build=missing --version 2.5 -pr build/profile.txt

# 3. Configure and build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

</details> <details> <summary><b>Windows Build</b></summary>

Note: Windows is NOT suitable for real-time use but useful for tools and testing.

Requirements:

• Conan for Windows (tested with 2.9.1)
• gcc for Windows (tested with w64devkit 2.0.0)
• npcap (driver 1.80 + SDK 1.70)

Follow the manual setup instructions above, using appropriate Windows paths.

</details> <details> <summary><b>PikeOS Build</b></summary>

Tested on PikeOS 5.1 for native personality (p4ext).

Provide a CMake cross-toolchain file that defines the PIKEOS variable. Example process/thread configurations are in examples/PikeOS/p4ext_config.c.

</details>

---

Getting Started: Complete Walkthrough

This section provides a complete end-to-end example using the Freedom K64F board with LAN9252 EtherCAT slave controller.

Hardware Requirements

• NXP Freedom K64F development board
• LAN9252 EtherCAT slave controller (SPI connection)
• Ethernet cable (connects slave to your PC)
• USB cable (for programming the board)
• Linux PC with EtherCAT master

See the NuttX Prerequisite section before starting.

Step 1: Build the Slave Firmware

# Build firmware for Freedom K64F
./scripts/build_slave_bin.sh freedom-k64f ~/nuttxspace/nuttx

# Output will be in: build_freedom-k64f/easycat_frdm_k64f.bin
# We have deployment scripts that are available here is an example:
./examples/slave/nuttx/lan9252/freedom-k64f/deploy.sh build_freedom-k64f/easycat_frdm_k64f.bin

Step 2: Flash the Firmware

# Deploy to the board (connects via USB)
./examples/slave/nuttx/lan9252/freedom-k64f/board/deploy.sh \
    build_freedom-k64f/easycat_frdm_k64f.bin

Step 3: Program the EEPROM

The EtherCAT slave requires EEPROM configuration with device information:

# Connect slave to your PC via Ethernet
# Write EEPROM (interface ? will be auto-detected)
sudo ./tools/eeprom -s 0 -c write -f examples/slave/nuttx/lan9252/freedom-k64f/eeprom.bin -i "?"

Note: The ? tells the tool to auto-detect the interface where the slave is connected.

Step 4: Run the Master

Now you can control your slave using either C++ or Python:

Option A - C++ Master:

# Run master example and follow terminal instructions
sudo ./build/examples/master/freedom-k64f/freedom_k64f_example -i "?"

Option B - Python Master:

# Install KickCAT Python bindings
pip install kickcat

# Grant raw access to Python interpreter
./py_bindings/enable_raw_access.sh

# Run Python example
python py_bindings/examples/freedom-k64f.py -i enp8s0

Expected Output

The master will:

1. Discover the slave on the network
2. Transition through states: INIT → PRE-OP → SAFE-OP → OP
3. Begin exchanging process data (PDOs)
4. Display diagnostic information

<details> <summary><b>Troubleshooting</b></summary>

Slave not detected:

• Check Ethernet cable connection
• Verify EEPROM was written successfully
• Check that slave firmware is running (LED indicators)

Permission denied:

• Ensure you're running master with sudo or proper capabilities
• For Python: run ./py_bindings/enable_raw_access.sh

Interface not found:

• List available interfaces: ip link show
• Use the correct interface name (e.g., eth0, enp8s0, eno1)

</details>

---

Getting Started with Examples

KickCAT includes working master and slave examples that work together out of the box.

Master Examples

Located in examples/master/:

• easycat: Basic example for EasyCAT shield
• elmo: Motor control example (Elmo drives)
• ingenia: Motor control example (Ingenia drives)
• freedom-k64f: Example for Kinetis Freedom board
• gateway: EtherCAT mailbox gateway implementation
• load_esi: ESI file loading utility

Running a Master Example

C++ Examples:

cd build
./examples/master/easycat/easycat_example -i eth0

Python Examples:

KickCAT is available on PyPI for easy installation:

# Install from PyPI
pip install kickcat

# Run Python examples
python py_bindings/examples/freedom-k64f.py --interface eth0

# With redundancy
python py_bindings/examples/easycat.py -i eth0 -r eth1

<details> <summary><b>Python Examples Help</b></summary>

$ python py_bindings/examples/freedom-k64f.py --help
usage: freedom-k64f.py [-h] -i INTERFACE [-r REDUNDANCY]

EtherCAT master for Freedom K64F using EasyCAT

options:
  -h, --help            show this help message and exit
  -i INTERFACE, --interface INTERFACE
                        Primary network interface (e.g., eth0)
  -r REDUNDANCY, --redundancy REDUNDANCY
                        Redundancy network interface (e.g., eth1)

Important: Python interpreter needs raw socket capabilities:

# Use the helper script to grant permissions
./py_bindings/enable_raw_access.sh

</details>

Replace eth0 with your network interface name.

Slave Examples

Located in examples/slave/nuttx/:

Supported Boards:

• XMC4800 (Infineon XMC4800 Relax Kit)
• Arduino Due (with EasyCAT shield + LAN9252)
• Freedom K64F (NXP Kinetis with LAN9252)

NuttX Prerequisite:

<details> <summary><b>NuttX Setup Instructions</b></summary>

1. Install NuttX dependencies: https://nuttx.apache.org/docs/latest/quickstart/install.html
2. Download ARM GCC toolchain (>= 12.0): https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads

Board-Specific Setup

Arduino Due:

• Requires bossac-1.6.1-arduino for flashing (available from Arduino IDE installation)
• Connect USB to the port closest to power jack
• If flashing fails with "No device found on ttyACM0":
  • Press ERASE button for a few seconds, release
  • Press RESET button
  • Try flashing again

Freedom K64F:

• Standard OpenOCD flashing supported

XMC4800:

• Use provided flashing scripts in board directory

</details>

Building Slave Examples

All slave examples use NuttX RTOS. Use the automated build script:

./scripts/build_slave_bin.sh <board-name> <nuttx-src-path> [build-name]

Example:

# Build for XMC4800
./scripts/build_slave_bin.sh xmc4800-relax ~/nuttxspace/nuttx

# Deploy for XMC4800
./examples/slave/nuttx/xmc4800/deploy.sh build_xmc4800-relax/xmc4800_relax.bin

# Build for Arduino Due
./scripts/build_slave_bin.sh arduino-due ~/nuttxspace/nuttx

# Deploy for Arduino Due
./examples/slave/nuttx/lan9252/arduino-due/deploy.sh build_arduino-due/easycat_arduino_due.bin

# Build for Freedom K64F
./scripts/build_slave_bin.sh freedom-k64f ~/nuttxspace/nuttx

# Deploy for Freedom K64F
/examples/slave/nuttx/lan9252/freedom-k64f/deploy.sh build_freedom-k64f/easycat_frdm_k64f.bin

<details> <summary><b>Testing Master-Slave Communication</b></summary>

1. Start the simulator or flash a slave:

   # Option A: Use simulator with TAP socket (preferred, same machine)
   ./build/simulation/network_simulator -i "?" -s simulation/slave_configs/freedom-k64f.json
   # Then select "tap:server"
   
   # Option B: Flash real hardware (e.g., Arduino Due)
   ./scripts/build_slave_bin.sh arduino-due ~/nuttxspace/nuttx
   # Flash the resulting binary to your board
   

2. Run a master example:

   # With TAP socket (select "tap:client"):
   sudo ./build/examples/master/easycat/easycat_example -i "?"
   
   # Or with the interface connected to