EthercatMaster.start()

[Ethercat Master]

Description

Start the EtherCAT master, configure the SM, FMMU, and DC registers of all slaves, and switch the EtherCAT state machine to the Operational state.

Syntax

int start(uint64_t cycletime_ns = 0, EthercatMasterMode mode = ECAT_FREERUN);

Parameters

• [in] uint64_t cycletime_ns
  EtherCAT cycle time. The EtherCAT firmware will periodically generate interrupts according to this cycle time to update process data and handle acyclic transmissions. If the user has registered a Cyclic Callback and the EtherCAT master control mode is not set to ECAT_FREERUN_MANUAL, the callback will be called during these periodic interrupts.
• [in] EthercatMasterMode mode
  Selection of the EtherCAT control mode. For detailed descriptions of each mode, please refer to the examples below.
  • ECAT_SYNC
  • ECAT_FREERUN
  • ECAT_FREERUN_MANUAL

Return Value

Return an error code. If the returned value is zero, it indicates a successful execution of this function.

Comment

This function is blocking and cannot be called within the callback functions.

Example

We will show how to select the EtherCAT control modes (ECAT_SYNC, ECAT_FREERUN, ECAT_FREERUN_MANUAL) in the following examples.

ECAT_SYNC

This mode offers the highest level of dual-system synchronization. As shown in the diagram, the numbered arrows indicate the sequence of operations, with no branching present. After the EtherCAT firmware triggers a cyclic interrupt to the EtherCAT master library (step 2), it waits for an ACK response from the EtherCAT master library (step 8) before proceeding with the next action. If the user has registered a cyclic callback, the cyclic interrupt will call it, as shown in step 4. As long as the user reads the current input process data within the cyclic callback, processes it, calculates the output process data, and writes it back, the current cycle will send the output process data to the EtherCAT network, fulfilling the requirements of real-time control systems.

#include "Ethercat.h"

EthercatMaster master;

void CyclicCallback() {
  // ...
}

void setup() {
  master.begin();
  master.attachCyclicCallback(CyclicCallback);
  master.start(1000000, ECAT_SYNC);
}

void loop() {
  // ... 
}

ECAT_FREERUN

This is the free-run mode without dual-system synchronization. As shown in the diagram, the numbered arrows indicate the sequence of operations. However, a branching occurs at step 3 because, after the EtherCAT firmware triggers a cyclic interrupt to the EtherCAT master library (step 2), it does not wait for the EtherCAT master library and directly continues with the next action. The two systems operate independently, with no synchronization. If the user has registered a cyclic callback, the cyclic interrupt will call it, as shown in step 4A.

#include "Ethercat.h"

EthercatMaster master;

void CyclicCallback() {
  // ...
}

void setup() {
  master.begin();
  master.attachCyclicCallback(CyclicCallback);
  master.start(1000000, ECAT_FREERUN);
}

void loop() {
  // ...
}

ECAT_FREERUN_MANUAL

This is also a free-run mode without dual-system synchronization. The primary difference from the ECAT_FREERUN mode is that there is no cyclic interrupt to update process data and handle acyclic commands. Instead, the user must manually call EthercatMaster::update() to update process data and handle acyclic commands. Additionally, since there is no cyclic interrupt in this mode, the cyclic callback will not be called. As indicated by the numbered arrows in the diagram, the two systems operate independently, with no synchronization.

#include "Ethercat.h"

EthercatMaster master;

void setup() {
  master.begin();
  master.start(1000000, ECAT_FREERUN_MANUAL);
}

void loop() {
  // ...
  master.update();
}

Please see the EtherCAT Library User Manual for more QEC EtherCAT instructions and API usage.