Skip to content

Rework README and doc in general #421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
trns1997 merged 1 commit into from
Jun 22, 2026
Merged

Rework README and doc in general #421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
889 changes: 109 additions & 780 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

168 changes: 168 additions & 0 deletions docs/BUILDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
# Building KickCAT

KickCAT uses Conan (for dependencies) and CMake, wrapped by the scripts in
`scripts/`. Prefer the wrappers over invoking `cmake` / `conan` directly.

## Prerequisites

- **Linux**: gcc, cmake, conan
- **Python bindings**: uv or pip
- **Hardware access**: a network interface with raw-socket capability

## Linux (recommended)

```bash
# 1. Configure build options (optional -- defaults are sensible)
./scripts/configure.sh build --with=unit_tests

# 2. Set up the build environment (installs Conan deps + runs CMake)
./scripts/setup_build.sh build

# 3. Build
cd build && make -j

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

`configure.sh` stores the selected options in `.buildconfig`, which
`setup_build.sh` consumes. Available options include `unit_tests`,
`code_coverage`, `esi_parser`, `simulation`, `tools`, `master_examples`,
`slave_examples`, `eeprom_editor`, and `kickui`.

### Rebuild after source changes

From an existing `build` directory, no need to re-run `configure.sh` /
`setup_build.sh` unless CMakeLists or Conan deps changed:

```bash
cd build && make -j
```

### GUI tools (KickUI, EEPROM editor)

These are off by default and need ImGui + GLFW:

```bash
./scripts/configure.sh build --with=kickui --with=eeprom_editor
./scripts/setup_build.sh build
cd build && make -j
```

See [TOOLS.md](TOOLS.md) for what each tool does.

## Python bindings

```bash
# Install with uv (recommended)
uv pip install .

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

The wheel build enables the EEPROM-editor GUI (`BUILD_EEPROM_EDITOR=ON` in
`pyproject.toml`), which needs `imgui` and `glfw`. The cibuildwheel images
provide them; on a bare environment that lacks them, either install them (via
Conan) or disable the GUI for the build:

```bash
uv pip install --config-setting=cmake.define.BUILD_EEPROM_EDITOR=OFF .
```

The published package is available on PyPI:

```bash
pip install kickcat
```

The Python interpreter needs raw-socket capabilities to drive a bus:

```bash
./py_bindings/enable_raw_access.sh
```

### Multi-wheel (CI)

This project uses cibuildwheel to generate wheels for all supported
configurations. To run it locally:

```bash
uvx cibuildwheel
```

## Manual build (without the wrapper scripts)

```bash
# 1. Create the 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.py -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 -j
```

## Windows

Windows is **not** suitable for real-time use, but it is 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 build instructions above, using the appropriate Windows paths
and the `conan/profile_windows_x86_64.txt` profile.

## PikeOS

Tested on PikeOS 5.1 for the native personality (p4ext).

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

## Slave firmware

Building and flashing NuttX slave firmware (XMC4800, Arduino Due, Freedom K64F)
is covered in [HARDWARE.md](HARDWARE.md).

## Testing

### Unit tests

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

The test binary is `build/kickcat_unit`. Run a subset with
`./kickcat_unit --gtest_filter='<Pattern>*'`.

### Code coverage

```bash
uv pip install gcovr

./scripts/configure.sh build --with=unit_tests --with=code_coverage
./scripts/setup_build.sh build
cd build && make -j
make coverage
```
120 changes: 120 additions & 0 deletions docs/FEATURES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
# Feature support matrix

This document maps the EtherCAT feature set to what the KickCAT stack currently
provides, separately for the **master** and **slave** sides. It is the
authoritative source for "what works today"; the README only summarizes it.

## Legend

| Status | Meaning |
|----------------|--------------------------------------------------------------------------------|
| Supported | Implemented and exercised by examples and/or unit tests. |
| Partial | Usable but incomplete, or limited to a subset of the feature. |
| Experimental | Implemented but not yet validated for production use. |
| Planned | On the roadmap; protocol definitions or scaffolding may already exist. |
| Not planned | No maintainer hardware to develop or test against. Contributions are welcome. |
| Not applicable | The feature does not apply to that side. |

## State machine and process data

| Feature | Master | Slave |
|------------------------------------------|-----------|-----------|
| EtherCAT State Machine (INIT/PRE-OP/SAFE-OP/OP) | Supported | Supported |
| Process data exchange (PDO read/write) | Supported | Supported |
| FMMU configuration | Supported | Supported |
| SyncManager configuration | Supported | Supported |
| One input + one output PDO mapping per slave | Supported | Supported |
| Multiple PDO SyncManagers (>1 input or >1 output per slave) | Not supported | Not supported |
| Mailbox status polling via dedicated FMMUs (LRD/LRW) | Supported | Not applicable |

## Mailbox protocols

| Protocol | Master | Slave | Notes |
|----------|------------|------------|-------|
| CoE (CANopen over EtherCAT) | Supported | Supported | See CoE breakdown below. |
| FoE (File over EtherCAT) | Planned | Planned | Protocol header only; no mailbox handlers yet. |
| EoE (Ethernet over EtherCAT)| Planned | Planned | Protocol header only; no mailbox handlers yet. |
| SoE (Servo over EtherCAT) | Not planned | Not planned | ESI parsing only. No maintainer hardware; contributions welcome. |
| AoE (ADS over EtherCAT) | Not planned | Not planned | ESI parsing only. No maintainer hardware; contributions welcome. |
| VoE (Vendor over EtherCAT) | Not planned | Not planned | ESI parsing only. No maintainer hardware; contributions welcome. |

### CoE breakdown

| CoE feature | Master | Slave |
|-------------------------------------|-----------|-----------|
| SDO expedited upload/download | Supported | Supported |
| SDO normal (sized) transfer | Supported | Supported |
| SDO segmented transfer | Supported | Supported |
| SDO Information service | Supported | Supported |
| Emergency messages | Supported | Not applicable |
| Object Dictionary | Not applicable | Supported |
| PDO mapping / assignment | Supported | Supported |

## Distributed Clocks (DC)

| Feature | Master | Slave |
|---------------------------------|--------------|-------------|
| DC synchronization | Experimental | Planned |
| DC modeling in the emulator | Supported (local clock, drift-ppm injection, SYNC0) | -- |

The ESC emulator models a DC clock with configurable drift; see
[SIMULATION.md](SIMULATION.md). Slave-side DC is not implemented on real ESCs yet.

## Networking and reliability

| Feature | Master | Slave |
|-------------------------------------------|-----------|-----------|
| Cable redundancy | Supported | Not applicable |
| Consecutive writes (frames in flight) | Supported | Not applicable |
| Mailbox gateway (ETG.8200) | Supported | Not applicable |
| Bus diagnostics and error counters | Supported | Supported |
| AF_XDP socket backend (Linux, opt-in) | Supported | Not applicable |
| Auto-discovery of broken wires | Planned | Not applicable |

## EEPROM / SII

| Feature | Master | Slave |
|----------------------------------|-----------|-----------|
| SII (EEPROM) parsing | Supported | Supported |
| EEPROM read/dump tooling | Supported | Not applicable |
| EEPROM write (slave provisioning)| Supported | Not applicable |

See [TOOLS.md](TOOLS.md) for the `eeprom` CLI and the EEPROM editor GUI.

## Platforms

The master and slave run on different layers: the master is a host OS process,
while the slave is the stack running on an RTOS against an EtherCAT Slave
Controller (ESC).

### Master (host operating system)

| OS | Architecture | Status |
|------------|--------------|----------------------------------------------|
| Linux | x86-64 | Supported; RT-PREEMPT recommended for real-time |
| PikeOS 5.1 | ARMv8 | Supported |
| Windows | x86-64 | Tools and testing only (not real-time) |

### Slave (RTOS + ESC hardware)

The slave stack runs on the NuttX RTOS. Supported EtherCAT Slave Controllers:

| ESC | Interface | Status |
|----------|------------|--------------------------|
| LAN9252 | SPI | Supported |
| XMC4800 | Integrated | Supported; CTT-validated |

Reference boards: NXP Freedom K64F (LAN9252), Arduino Due with EasyCAT shield
(LAN9252), and the Infineon XMC4800 Relax Kit (XMC4800). Build and flashing
details are in [HARDWARE.md](HARDWARE.md).

## Known limitations

- Little-endian hosts only.
- Windows is not suitable for real-time operation; use it for tooling and tests.
- Process data is limited to one input and one output PDO SyncManager per slave
on both master and slave; multiple PDO SyncManagers per direction are not
supported.
- Slave-side Distributed Clocks are not implemented.
- The simulator/emulator does not emulate interrupts; see
[SIMULATION.md](SIMULATION.md).
Loading
Loading