SOEM

SOEM is an open-source EtherCAT Master library developed by volunteers. Unlike TwinCAT, real-time performance is not guaranteed. Therefore, it is generally recommended to use TwinCAT. Using SOEM should be limited to unavoidable reasons or for development purposes only. On the other hand, SOEM has the advantage of being cross-platform and simple to install.

For Windows, install npcap in “WinPcap API compatible mode”. For Linux/macOS, no special preparation is required.

Install

cargo add autd3-link-soem

if(WIN32)
  FetchContent_Declare(
    autd3-link-soem
    URL https://github.com/shinolab/autd3-cpp-link-soem/releases/download/v32.0.1/autd3-link-soem-v32.0.1-win-x64.zip
  )
elseif(APPLE)
  FetchContent_Declare(
    autd3-link-soem
    URL https://github.com/shinolab/autd3-cpp-link-soem/releases/download/v32.0.1/autd3-link-soem-v32.0.1-macos-aarch64.tar.gz
  )
else()
  FetchContent_Declare(
    autd3-link-soem
    URL https://github.com/shinolab/autd3-cpp-link-soem/releases/download/v32.0.1/autd3-link-soem-v32.0.1-linux-x64.tar.gz
  )
endif()
FetchContent_MakeAvailable(autd3-link-soem)
target_link_libraries(<TARGET> PRIVATE autd3::link::soem)

dotnet add package AUTD3Sharp.Link.SOEM

Add https://github.com/shinolab/AUTD3Sharp.Link.SOEM.git#upm/latest to Unity Package Manager.

pip install pyautd3_link_soem

APIs

The first argument is a callback function for errors, and the second argument specifies options.

#[cfg(target_os = "windows")]
use autd3_link_soem::ProcessPriority;
use autd3_link_soem::{Status, SyncMode, ThreadPriority, TimerStrategy, SOEM, SOEMOption};
use std::num::NonZeroUsize;
use std::time::Duration;

fn main() {
let _ = 
SOEM::new(
    |slave, status| {
        eprintln!("slave [{}]: {}", slave, status);
        if status == Status::Lost {
            std::process::exit(-1);
        }
    },
    SOEMOption {
        buf_size: NonZeroUsize::new(32).unwrap(),
        timer_strategy: TimerStrategy::SpinSleep,
        sync_mode: SyncMode::DC,
        ifname: String::new(),
        state_check_interval: Duration::from_millis(100),
        sync0_cycle: Duration::from_millis(1),
        send_cycle: Duration::from_millis(1),
        thread_priority: ThreadPriority::Max,
        #[cfg(target_os = "windows")]
        process_priority: ProcessPriority::High,
        sync_tolerance: Duration::from_micros(1),
        sync_timeout: Duration::from_secs(10),
    },
);
}
#include <iostream>
#include <autd3_link_soem.hpp>

int main() {
using namespace autd3;
link::SOEM(
    [](const uint16_t slave, const link::Status status) {
      std::cout << "slave [" << slave << "]: " << status << std::endl;
      if (status == link::Status::Lost()) {
        exit(-1);
      }
    },
    link::SOEMOption{
        .buf_size = 32,
        .timer_strategy = link::TimerStrategy::SpinSleep,
        .sync_mode = link::SyncMode::DC,
        .ifname = "",
        .state_check_interval = std::chrono::milliseconds(100),
        .sync0_cycle = std::chrono::milliseconds(1),
        .send_cycle = std::chrono::milliseconds(1),
        .thread_priority = link::ThreadPriority::Max(),
        .process_priority = link::ProcessPriority::High,
        .sync_tolerance = std::chrono::microseconds(1),
        .sync_timeout = std::chrono::seconds(10),

    });
return 0; }

using AUTD3Sharp;
using AUTD3Sharp.Link;

using AUTD3Sharp.Utils;
new SOEM(
    errHandler: (slave, status) =>
    {
        Console.Error.WriteLine($"slave [{slave}]: {status}");
        if (status == Status.Lost)
            Environment.Exit(-1);
    },
    option: new SOEMOption
    {
        BufSize = 32,
        TimerStrategy = TimerStrategy.SpinSleep,
        SyncMode = SyncMode.DC,
        Ifname = "",
        StateCheckInterval = Duration.FromMillis(100),
        Sync0Cycle = Duration.FromMillis(1),
        SendCycle = Duration.FromMillis(1),
        ThreadPriority = AUTD3Sharp.Link.ThreadPriority.Max,
        ProcessPriority = ProcessPriority.High,
        SyncTolerance = Duration.FromMicros(1),
        SyncTimeout = Duration.FromSecs(10),
    }
);

import os
from pyautd3 import Duration
from pyautd3_link_soem import (
    SOEM,
    ProcessPriority,
    SOEMOption,
    Status,
    SyncMode,
    ThreadPriority,
    TimerStrategy,
)


def err_handler(slave: int, status: Status) -> None:
    print(f"slave [{slave}]: {status}")
    if status == Status.Lost():
        os._exit(-1)


SOEM(
    err_handler=err_handler,
    option=SOEMOption(
        buf_size=32,
        timer_strategy=TimerStrategy.SpinSleep,
        sync_mode=SyncMode.DC,
        ifname="",
        state_check_interval=Duration.from_millis(100),
        sync0_cycle=Duration.from_millis(1),
        send_cycle=Duration.from_millis(1),
        thread_priority=ThreadPriority.Max,
        process_priority=ProcessPriority.High,  # only available on Windows
        sync_tolerance=Duration.from_micros(1),
        sync_timeout=Duration.from_secs(10),
    ),
)

The options that can be specified for the SOEM link are as follows. The default values are as above.

  • buf_size: Transmission queue buffer size. Usually, there is no need to change this.
  • timer_strategy: Timer strategy
    • StdSleep : Uses the standard library sleep
    • SpinSleep : Uses the spin_sleep crate. Combines OS native sleep (WaitableTimer on Windows) and spin loop.
    • SpinWait : Uses a spin loop. High resolution but high CPU load.
  • sync_mode: Synchronization mode
  • ifname: Network interface name. If empty, the network interface to which the AUTD3 device is connected is automatically selected.
  • state_check_interval: Interval to check for errors
  • sync0_cycle: Synchronization signal cycle
  • send_cycle: Transmission cycle
    • SOEM may become unstable when connecting a large number of devices. In this case, increase the values of sync0_cycle and send_cycle. These values should be as small as possible without causing errors. The appropriate values depend on the number of connected devices. For example, for 9 devices, a value of about should work.
  • thread_priority: Thread priority
  • process_priority: Process priority (Windows only)
  • sync_tolerance: Synchronization tolerance level. During initialization, this link waits until the system time difference of each device is below this value. If synchronization is not completed within the timeout period below, an error occurs. It is not recommended to change this value.
  • sync_timeout: Synchronization timeout. Timeout period for the system time difference measurement above.