Version: 1.1.1

ecnet::EcNetwork

User-facing runtime facade for an EtherCAT network. More...

#include <ec_network.hpp>

Public Classes

	Name
struct	SyncTraceReport Per-cycle DC-sync and jitter capture snapshot, cached at `[stop()](/lxmaster/api/classes/EcNetwork#function-stop)` from the executor's ring buffer (see `NetworkConfig::DebugConfig::sync_trace_capacity`).
struct	JitterStats Per-run cycle-timing jitter summary, populated by the cyclic thread and finalised at `[stop()](/lxmaster/api/classes/EcNetwork#function-stop)`.
struct	DcSyncStats Per-run DC-sync alignment summary: the signed error between the host's cyclic wake time and the reference-slave's distributed-clock (DC) reference time, measured before the PI controller applies its correction offset.

Public Functions

	Name
	~EcNetwork()
std::uint64_t	syncTraceViolationCount() const Live violation tally while the cyclic thread is running (`sync_trace_window_ns` > 0).
SyncTraceReport	syncTraceReport() const Per-cycle DC-sync + host jitter capture from the last session (`NetworkConfig::sync_trace_capacity`).
SyncMode	syncMode() const Synchronization mode resolved from the ENI (DcSync0 when the bus carries a SYNC0 device, else SmEvent).
void	stop() Stop the cyclic thread and close the master.
bool	start() Phase 2 of bring-up (runs `prepare()` first if it has not been called): per-device CoE configuration (commits each drive's operating mode to 0x6060), configures DC, reaches SAFE_OP + OPERATIONAL, and spawns the cyclic thread.
void	reportDeviceStatus(std::ostream & os) const Print each device's exit status to `os`.
bool	prepare() Phase 1 of bring-up: applies RT scheduling, loads + validates the ENI, opens the NIC, verifies the scanned hardware, reaches PRE_OP, and binds devices so that `axes()` / `ioModules()` / `encoders()` become valid.
EcNetwork &	operator=(const EcNetwork & ) =delete
std::string	lastError() const Last human-readable error captured from the library (thread-safe).
JitterStats	jitterStats() const Snapshot of cycle-timing jitter (updated throughout the run; final at `[stop()](/lxmaster/api/classes/EcNetwork#function-stop)`).
bool	isRunning() const True once the cyclic thread is live, false after `[stop()](/lxmaster/api/classes/EcNetwork#function-stop)` or on failure.
std::vector< ecfacade::IoModule * >	ioModules() const I/O modules in bus order, one per slave whose auto-selected profile exposes a digital/analog I/O interface (e.g.
std::vector< ecfacade::Encoder * >	encoders() const Encoders in bus order, one per slave whose auto-selected profile exposes an encoder interface (e.g.
std::vector< ecfacade::GenericDevice * >	devices() const Every profile-carrying slave in bus order, as generic handles.
DcSyncStats	dcSyncStats() const Snapshot of DC-sync alignment quality (host cyclic wake vs reference-slave DC clock, the error before the PI controller corrects it).
std::uint32_t	cycleTimeNs() const Cyclic period in ns, adopted from the ENI's `<Config><Cyclic><CycleTime>`.
std::uint64_t	cycleCount() const Total EtherCAT cycles executed by the RT thread since `[start()](/lxmaster/api/classes/EcNetwork#function-start)`.
std::vector< ecfacade::Axis * >	axes() const Motion axes in bus order, one per slave whose auto-selected profile exposes a motion interface (e.g.
	EcNetwork(NetworkConfig cfg)
	EcNetwork(const EcNetwork & ) =delete

Detailed Description

class ecnet::EcNetwork;

User-facing runtime facade for an EtherCAT network.

Owns the EtherCAT master, the cyclic RT thread, and the devices auto-created from the ENI. A typical program is:

ecnet::NetworkConfig cfg = ecnet::NetworkConfig::defaults(); // iface from LXMASTER_RT_IFACE cfg.eni.eni_path = "network.eni.xml"; // required: ENI is the only setup mode and the // sole source of the cyclic period (CycleTime). ecnet::EcNetwork net(cfg); if (!net.start()) { std::cerr << net.lastError(); return 1; } auto axis = net.axes().front(); ... axis->moveTo(axis->actualPosition()); ... net.stop();

No backend types leak through this API. [start()](/lxmaster/api/classes/EcNetwork#function-start) loads + validates the ENI, verifies it against the scanned hardware, and creates one generic CiA402 device per slave.

Two-phase bring-up (per-axis configuration). Operating mode and fault policy are per-axis intent the application sets on each discovered drive before the bus is brought up. [prepare()](/lxmaster/api/classes/EcNetwork#function-prepare) runs the offline + PRE_OP phases so [axes()](/lxmaster/api/classes/EcNetwork#function-axes) becomes valid while the drives are still in PRE_OP and no mode has been committed; the application then configures each axis and calls [start()](/lxmaster/api/classes/EcNetwork#function-start) to finish:

ecnet::EcNetwork net(cfg); if (!net.prepare()) { std::cerr << net.lastError(); return 1; } for (ecfacade::Axis* ax : net.axes()) { ax->setDriveMode(ecdev::DriveOpMode::Cst); ax->configure(); } if (!net.start()) { std::cerr << net.lastError(); return 1; }

[start()](/lxmaster/api/classes/EcNetwork#function-start) calls [prepare()](/lxmaster/api/classes/EcNetwork#function-prepare) itself when it has not run, so the single-call form above still works.

Public Functions Documentation

function ~EcNetwork

~EcNetwork()

function syncTraceViolationCount

std::uint64_t syncTraceViolationCount() const

Live violation tally while the cyclic thread is running (sync_trace_window_ns > 0).

After [stop()](/lxmaster/api/classes/EcNetwork#function-stop), prefer [syncTraceReport()](/lxmaster/api/classes/EcNetwork#function-synctracereport).violation_count.

function syncTraceReport

inline SyncTraceReport syncTraceReport() const

Per-cycle DC-sync + host jitter capture from the last session (NetworkConfig::sync_trace_capacity).

Populated when [stop()](/lxmaster/api/classes/EcNetwork#function-stop) joins the executor; empty if tracing was off or the bus never ran.

function syncMode

SyncMode syncMode() const

Synchronization mode resolved from the ENI (DcSync0 when the bus carries a SYNC0 device, else SmEvent).

Valid after [prepare()](/lxmaster/api/classes/EcNetwork#function-prepare) / [start()](/lxmaster/api/classes/EcNetwork#function-start). Not an app input – the ENI decides.

function stop

void stop()

Stop the cyclic thread and close the master.

Safe to call multiple times.

function start

bool start()

Phase 2 of bring-up (runs prepare() first if it has not been called): per-device CoE configuration (commits each drive's operating mode to 0x6060), configures DC, reaches SAFE_OP + OPERATIONAL, and spawns the cyclic thread.

Return: true on success; false on failure — call [lastError()](/lxmaster/api/classes/EcNetwork#function-lasterror) for the reason. Failure at any step tears down what was initialized.

function reportDeviceStatus

void reportDeviceStatus(
    std::ostream & os
) const

Print each device's exit status to os.

Parameters:

os Output stream to write the human-readable status report to (e.g. std::cout).

Call after [stop()](/lxmaster/api/classes/EcNetwork#function-stop) to surface device-specific end-of-run diagnostics (e.g. final statusword, CiA402 fault code 0x603F).

function prepare

bool prepare()

Phase 1 of bring-up: applies RT scheduling, loads + validates the ENI, opens the NIC, verifies the scanned hardware, reaches PRE_OP, and binds devices so that axes() / ioModules() / encoders() become valid.

Return: true on success; false on failure — call [lastError()](/lxmaster/api/classes/EcNetwork#function-lasterror) for the reason. Failure tears down everything that was initialized.

Crucially it stops before any per-device CoE configuration, so the application can set per-axis intent (e.g. axis->setOperatingMode(...)) on the discovered drives before the operating mode is committed to the drive in [start()](/lxmaster/api/classes/EcNetwork#function-start). Idempotent: a second call after success is a no-op success. Calling it after [start()](/lxmaster/api/classes/EcNetwork#function-start) is an error.

function operator=

EcNetwork & operator=(
    const EcNetwork & 
) =delete

function lastError

std::string lastError() const

Last human-readable error captured from the library (thread-safe).

Includes [shutdown] step failures accumulated during [stop()](/lxmaster/api/classes/EcNetwork#function-stop) after the cyclic thread has been joined.

function jitterStats

JitterStats jitterStats() const

Snapshot of cycle-timing jitter (updated throughout the run; final at [stop()](/lxmaster/api/classes/EcNetwork#function-stop)).

function isRunning

bool isRunning() const

True once the cyclic thread is live, false after [stop()](/lxmaster/api/classes/EcNetwork#function-stop) or on failure.

function ioModules

std::vector< ecfacade::IoModule * > ioModules() const

I/O modules in bus order, one per slave whose auto-selected profile exposes a digital/analog I/O interface (e.g.

CiA 401 or non-CoE terminal). Valid after a successful [start()](/lxmaster/api/classes/EcNetwork#function-start); the storage is owned by this [EcNetwork](/lxmaster/api/classes/EcNetwork). Use [ioModules()](/lxmaster/api/classes/EcNetwork#function-iomodules)[i]->readDigital(ch) / writeDigital(ch, val) to access channels without seeing PDO offsets or CoE objects.

function encoders

std::vector< ecfacade::Encoder * > encoders() const

Encoders in bus order, one per slave whose auto-selected profile exposes an encoder interface (e.g.

CiA 406). Valid after a successful [start()](/lxmaster/api/classes/EcNetwork#function-start); the storage is owned by this [EcNetwork](/lxmaster/api/classes/EcNetwork). Use [encoders()](/lxmaster/api/classes/EcNetwork#function-encoders)[i]->position() to read the latest position in encoder counts.

function devices

std::vector< ecfacade::GenericDevice * > devices() const

Every profile-carrying slave in bus order, as generic handles.

This is the complete set: a device that also exposes a typed capability appears in both its typed list ([axes()](/lxmaster/api/classes/EcNetwork#function-axes) etc.) and here. Use this for brand-new device classes that fit none of the typed contracts (e.g. an IMU): configure() the handle to bring it to OPERATIONAL and deviceProfile() to reach its custom profile API. Valid after a successful [start()](/lxmaster/api/classes/EcNetwork#function-start); storage is owned by this [EcNetwork](/lxmaster/api/classes/EcNetwork).

function dcSyncStats

DcSyncStats dcSyncStats() const

Snapshot of DC-sync alignment quality (host cyclic wake vs reference-slave DC clock, the error before the PI controller corrects it).

samples == 0 outside DC-aligned mode.

function cycleTimeNs

std::uint32_t cycleTimeNs() const

Cyclic period in ns, adopted from the ENI's <Config><Cyclic><CycleTime>.

Valid (non-zero) after a successful [start()](/lxmaster/api/classes/EcNetwork#function-start); 0 before the ENI is loaded.

function cycleCount

std::uint64_t cycleCount() const

Total EtherCAT cycles executed by the RT thread since [start()](/lxmaster/api/classes/EcNetwork#function-start).

Monotonically increasing while running; final after [stop()](/lxmaster/api/classes/EcNetwork#function-stop). Useful for synchronising application-side event sequencing with the cyclic period and for progress monitoring during long moves.

function axes

std::vector< ecfacade::Axis * > axes() const

Motion axes in bus order, one per slave whose auto-selected profile exposes a motion interface (e.g.

CiA402 drives). Valid after a successful [start()](/lxmaster/api/classes/EcNetwork#function-start); the storage is owned by this [EcNetwork](/lxmaster/api/classes/EcNetwork). This is the high-level handle a PLC/application programmer uses ([axes()](/lxmaster/api/classes/EcNetwork#function-axes)[0]->moveTo(...)) – it never exposes CiA profiles, the ENI, or the backend.

function EcNetwork

explicit EcNetwork(
    NetworkConfig cfg
)

function EcNetwork

EcNetwork(
    const EcNetwork & 
) =delete

Updated on 2026-07-13 at 20:44:41 +0000

Public Classes​

Public Functions​

Detailed Description​

Public Functions Documentation​

function ~EcNetwork​

function syncTraceViolationCount​

function syncTraceReport​

function syncMode​

function stop​

function start​

function reportDeviceStatus​

function prepare​

function operator=​

function lastError​

function jitterStats​

function isRunning​

function ioModules​

function encoders​

function devices​

function dcSyncStats​

function cycleTimeNs​

function cycleCount​

function axes​

function EcNetwork​

function EcNetwork​

Public Classes

Public Functions

Detailed Description

Public Functions Documentation

function ~EcNetwork

function syncTraceViolationCount

function syncTraceReport

function syncMode

function stop

function start

function reportDeviceStatus

function prepare

function operator=

function lastError

function jitterStats

function isRunning

function ioModules

function encoders

function devices

function dcSyncStats

function cycleTimeNs

function cycleCount

function axes

function EcNetwork

function EcNetwork