Development

Prerequisites

• A stable Rust toolchain.

Not a Cargo workspace

The subcrates (ethercat_hal, ethercat_hal_derive, xtrem, units, common) are plain path dependencies of the root crate. Each one has its own Cargo.lock and target/. That means cargo test -p <crate> from the root fails with "not a member of the workspace". Run cargo inside the crate's directory instead.

Build and test

cargo build
cargo build --examples               # all examples
cargo fmt --all --check              # format check

cd ethercat_hal && cargo test                   # HAL unit tests, no hardware needed
cd ethercat_hal && cargo test <name_filter>     # a single test
cd xtrem && cargo test                          # protocol tests + tests/loopback.rs, no hardware needed
cd xtrem && cargo test --test loopback <name>   # a single loopback test

CI (.github/workflows/cargo.yml) builds with RUSTFLAGS="-D warnings", so a warning fails the build.

Running examples

EtherCAT examples live in the root examples/ and take the network interface name as their first argument:

cargo run --example el2004_minimal -- eth0

xtrem/examples/ holds the XTREM examples.

Why cargo run asks for sudo

On x86_64 Linux, .cargo/config.toml sets bin/run-linux as the runner. Before running the binary it:

• runs sudo setcap cap_dac_override,cap_net_raw,cap_sys_nice,cap_ipc_lock on it, so it can open raw sockets and use real-time scheduling and mlock;
• chowns /dev/ttyUSB*, so serial devices are accessible.

The config also applies inside the subcrate directories, so cargo test there asks for sudo too.

Git hooks

./setup-git-hooks.sh          # install (sets core.hooksPath = .githooks)
./setup-git-hooks.sh status

The pre-commit hook runs cargo fmt --check. Put formatting-only commits in .git-blame-ignore-revs.

Feature flags

• mock (root crate and ethercat_hal) replaces EtherCATThreadChannel with an in-memory SDO map and enables init_ethercat_mock. It has not kept up with the controller refactor and does not currently compile.
• legacy_code (ethercat_hal) gates the machine-ident EEPROM code.

Documentation

The wiki lives in docs/. Keep Architecture and Writing device drivers in sync when you change controller behaviour or the driver pattern.