echocat

EchocatLink is a Link implementation using echocat, an EtherCAT main device written for AUTD3.

Installation

Rust

cargo add autd3-rs-link-echocat

Python

pip install autd3-link-echocat

C#

dotnet add package AUTD3.Link.Echocat

Privileges

Using echocat requires privileges, which differ per OS.

Linux

Either run as root, or grant the capabilities to the executable.

sudo setcap cap_net_raw,cap_net_admin,cap_sys_nice+ep ./target/release/my_app

The capabilities are attached to the binary, so they are lost on a rebuild.

When granting the capabilities for Python or C#, the target is the interpreter itself (python3, dotnet).

macOS

Either run as root, or grant read/write access to /dev/bpf*.

sudo chgrp admin /dev/bpf*
sudo chmod g+rw /dev/bpf*

/dev/bpf* is recreated on boot, so the permissions have to be granted again after every reboot.

Windows

Install npcap in “WinPcap API-compatible mode”. If “Restrict Npcap driver’s access to Administrators only” was selected in the installer, the program must be run with administrator privileges.

Without npcap, wpcap.dll is missing and the process fails to start at all (error code 0xc0000135).

API

Rust

EchocatLinkOption {
    iface,
    sync0_period,
    frame_phase,
    pdu_timeout,
    state_transition_timeout,
    dc_static_sync_iterations,
    dc_start_delay,
    sync_tolerance,
    sync_timeout,
    process_data_watchdog,
    sleep_strategy,
    ..Default::default()
};

Python

EchocatLinkOption(
    iface,
    sync0_period,
    frame_phase,
    pdu_timeout,
    state_transition_timeout,
    dc_static_sync_iterations,
    dc_start_delay,
    sync_tolerance,
    sync_timeout,
    process_data_watchdog,
)

C#

new EchocatLinkOption(
    iface,
    sync0Period,
    framePhase,
    pduTimeout,
    stateTransitionTimeout,
    dcStaticSyncIterations,
    dcStartDelay,
    syncTolerance,
    syncTimeout,
    processDataWatchdog
);

Field	Type	Description
iface	Interface	network interface to use. Interface::Auto for automatic selection, Interface::Name(..) to specify by name
sync0_period	Duration	period of the SYNC0 signal (= the cyclic frame period)
frame_phase	FramePhase	where in the SYNC0 period the frame lands
pdu_timeout	Duration	timeout to wait for the response to a single PDU
state_transition_timeout	Duration	timeout to wait for an EtherCAT state transition (INIT → PRE-OP → SAFE-OP → OP)
dc_static_sync_iterations	u32	number of frames used for DC static drift compensation
dc_start_delay	Duration	how far ahead of the current bus time the SYNC0 start time is placed
sync_tolerance	Duration	tolerance considered as synchronization complete
sync_timeout	Duration	timeout to wait for synchronization to complete
process_data_watchdog	Duration	time after which a subdevice detects that process data has stopped
sleep_strategy	SleepStrategy	how to wait for the next cycle (Rust only)

The default sync0_period is 2 ms on Windows and 1 ms elsewhere.

Landing phase (FramePhase)

Decides how long after the SYNC0 edge the frame lands.

Rust

FramePhase::Auto;
FramePhase::At(Duration::from_micros(500));

Python

FramePhase.Auto
FramePhase.At(Duration.from_micros(500))

C#

_ = FramePhase.Auto;
_ = FramePhase.At(TimeSpan.FromMicroseconds(500));

Variant	Description
Auto	decided automatically from the measured duration of one exchange
At(phase)	lands phase after SYNC0. Keep it inside 0 < phase < sync0_period

The default is Auto.

Waiting (SleepStrategy, Rust only)

Selects how the RT thread waits for the next cycle.

Rust

SleepStrategy::Sleep;
SleepStrategy::Spin {
    margin: Duration::from_micros(100),
};

Variant	Description
Sleep	waits with std::thread::sleep.
Spin { margin }	sleeps until margin before the deadline, then spins

The default is Sleep.