EtherCAT network-config codegen¶

This page captures the requirements for the EtherCAT network-config codegen toolchain: a layered set of build-host crates that translate an integrator-authored network.yaml describing one bus’s topology and application channel wiring into the &'static tables (SubDeviceMap, EthercatRouting, channel-name constants) that taktora-connector-ethercat consumers hand-write today.

It is the network/topology peer of the device-internal codegen toolchains:

Device-driver codegen toolc... (FEAT_0050) (ethercat-esi) translates a vendor ESI XML file into a typed driver for one device’s object dictionary / PDO catalog.
CANopen device-driver codeg... (FEAT_0060) (canopen-eds) does the same for CANopen EDS.
This umbrella (EtherCAT network-config cod... (FEAT_0080)) describes how this integrator wires these devices into one bus’s process image, and which executor channels bind to which process-data slices.

ESI/EDS describe what a device can do (vendor-supplied); this toolchain describes how the integrator wires devices together (integrator-authored). They compose: a device entry in the YAML may reference an ESI file to inherit its PDO catalog and identity.

The design rationale and the full grilling trail live in docs/superpowers/specs/2026-05-31-ethercat-netcfg-codegen-design.md. The decomposition mirrors the convention established in Device-driver codegen: a top-level umbrella feature, capability-cluster sub-features that :satisfies: it, and concrete shall-clauses under each cluster.

This round covers EtherCAT only and one bus per file. Multi-bus documents / distribution over multiple files are explicitly deferred (see One file, one bus; multi-bu... (ADR_0096)).

Top-level umbrella¶

Feature: EtherCAT network-config codegen toolchain FEAT_0080

status: open

is satisfied by: FEAT_0083, FEAT_0084, FEAT_0082, FEAT_0081, FEAT_0085

is refined by: ADR_0092

A layered set of build-host Rust crates that consume an integrator-authored network.yaml (one bus per file) and emit, at build time, the &'static bus tables a taktora-connector-ethercat application consumes. The toolchain is organised as four layers that depend only leftwards:

Parse layer — ethercat-netcfg: YAML → typed IR. Depends on ethercat-esi and fieldbus-od-core to resolve ESI references; no dependency on the connector runtime.
Codegen layer — ethercat-netcfg-codegen: IR → TokenStream (prettyplease formatting).
Tooling layer — ethercat-netcfg-build (build.rs glue) and ethercat-netcfg-cli (netcfg expand / netcfg fetch).

The generated code names taktora-connector-ethercat types (SubDeviceMap, PdoEntry, EthercatRouting) textually; the codegen crates never link the connector runtime, and no change to EtherCAT reference connector (FEAT_0041)’s runtime contracts is required (mirror of the ESI toolchain’s no-runtime-modification rule).

Capability clusters¶

The umbrella decomposes into five capability clusters. Each cluster is a sub-feature :satisfies: EtherCAT network-config cod... (FEAT_0080), with concrete shall-clauses underneath.

Requirements at a glance¶

Used filter: types(req OR feat)

ID	Title	Status	Satisfies
FEAT_0080	EtherCAT network-config codegen toolchain	open
FEAT_0081	Network-config parser and IR	open	FEAT_0080
FEAT_0082	Network-config codegen	open	FEAT_0080
FEAT_0083	Build-script glue	open	FEAT_0080
FEAT_0084	CLI and ESI vendoring	open	FEAT_0080
FEAT_0085	Validation and bring-up assertions	open	FEAT_0080
REQ_0820	YAML parse to typed network IR	open	FEAT_0081
REQ_0821	IR carries bus config, device instances, and channel bindings	open	FEAT_0081
REQ_0822	One file describes exactly one bus	open	FEAT_0081
REQ_0823	Devices referenced by stable label, not address	open	FEAT_0081
REQ_0824	Parser depends on ethercat-esi, never on the connector runtime	open	FEAT_0081
REQ_0825	Emit static SubDeviceMap PDO tables	open	FEAT_0082
REQ_0826	Emit named routing and channel-name constants	open	FEAT_0082
REQ_0827	Configured addresses assigned by bus position	open	FEAT_0082
REQ_0828	Working-counter expectation derived, never overridden	open	FEAT_0082
REQ_0829	Generated output is byte-deterministic	open	FEAT_0082
REQ_0830	Generate into OUT_DIR for include	open	FEAT_0083
REQ_0831	Rebuild on config or ESI change	open	FEAT_0083
REQ_0832	Expand subcommand prints generated module	open	FEAT_0084
REQ_0833	Fetch subcommand vendors and pins remote ESI	open	FEAT_0084
REQ_0834	Build resolves ESI from local files only	open	FEAT_0084
REQ_0835	ESI references pinned by content hash and revision	open	FEAT_0084
REQ_0836	Hard build errors for derivable faults	open	FEAT_0085
REQ_0837	Warn on unmapped process-image gaps	open	FEAT_0085
REQ_0838	Emit bring-up assertions for physical-bus facts	open	FEAT_0085
REQ_0839	No runtime parsing, no connector-runtime modification	open	FEAT_0085
REQ_0844	Resolve and emit each output device's SM-watchdog registers	implemented	FEAT_0085
REQ_0845	Validate the SM-watchdog bound and enable at config time	implemented	FEAT_0085