soempp::Master Class Reference

#include <soempp.h>

Public Member Functions
	Master ()
	Default constructor for the Master class. More...
	Master (const std::string &iface)
	Constructs and initializes the Master with the given network interface. More...
void	init (const std::string &iface)
	Initializes the fieldbus using the specified network interface. More...
void	deinit ()
	Deinitializes the fieldbus and releases associated resources. More...
	~Master ()
	Destructor for the Master class. More...
Fieldbus &	getFieldbus () const
	Returns a reference to the Fieldbus instance. More...
std::string	getInterfaceName () const
	Retrieves the interface name used by the fieldbus. More...
size_t	getIoMapSize () const
	Returns the total size of the I/O map for the current group. More...
int	initSlaves ()
	Initializes the slave devices on the EtherCAT network. More...
const std::vector< std::unique_ptr< soempp::Slave > > &	getSlaves () const
	Returns a reference to the list of slaves. More...
int	expectedWkc () const
	Calculates the expected working counter (WKC) for the current fieldbus group. More...
int	roundtrip ()
	Performs a complete send/receive process data cycle on the fieldbus. More...
void	exchangeProcessDataAndUpdateParameters ()
	Exchanges process data with slaves and updates parameters based on the response. More...
bool	start ()
	Initializes and starts the fieldbus master. More...

Constructor & Destructor Documentation

Master() [1/2]

soempp::Master::Master ( )

explicit

Default constructor for the Master class.

Does not perform any initialization. You must call initFieldbus() before use.

Master() [2/2]

soempp::Master::Master ( const std::string &  iface )

explicit

Constructs and initializes the Master with the given network interface.

Delegates to initFieldbus(iface). See initFieldbus() for detailed initialization steps.

Parameters

iface

The name of the network interface (e.g., "eth0").

Exceptions

std::runtime_error

if the fieldbus initialization fails.

~Master()

soempp::Master::~Master

(

)

Destructor for the Master class.

Ensures proper cleanup by calling deinit() to close the EtherCAT context and release all allocated resources.

Member Function Documentation

deinit()

void soempp::Master::deinit

(

)

Deinitializes the fieldbus and releases associated resources.

Calls ecx_close() to properly close the EtherCAT context and free related system resources such as sockets and buffers.

Logs a confirmation message upon successful closure.

This method is also invoked by the destructor to ensure clean shutdown.

exchangeProcessDataAndUpdateParameters()

void soempp::Master::exchangeProcessDataAndUpdateParameters

(

)

Exchanges process data with slaves and updates parameters based on the response.

This function initiates the process of exchanging data with all connected slaves. It first updates the output values for each slave using the updateOutputs method. Then, it performs a round-trip communication and checks the Working Counter (WKC).

If the WKC is greater than or equal to the expected WKC, it updates the parameters for each slave by calling updateParametersFromInputs. Otherwise, it logs an error indicating that the WKC is not as expected, and provides details about the slave responses and their states.

The function assumes that all slaves are properly initialized and that slavecount is a valid value.

Note

The function relies on the roundtrip() function to perform the communication with slaves, and uses the expectedWkc() to compare the result with the expected WKC.

See also

updateOutputs

updateParametersFromInputs

roundtrip

expectedWkc

Returns

void

expectedWkc()

int soempp::Master::expectedWkc ( ) const

inline

Calculates the expected working counter (WKC) for the current fieldbus group.

Computes the expected WKC as twice the number of outputs plus the number of inputs for the selected group in the fieldbus context.

Returns

The expected WKC value.

getFieldbus()

Fieldbus & soempp::Master::getFieldbus

(

)

const

Returns a reference to the Fieldbus instance.

Returns

Reference to the underlying Fieldbus object.

Exceptions

std::runtime_error

If the fieldbus is not initialized (i.e., null).

Note

Assumes that fieldbus_ has been properly initialized.

getInterfaceName()

std::string soempp::Master::getInterfaceName

(

)

const

Retrieves the interface name used by the fieldbus.

This function returns the network interface name associated with the fieldbus, which was set during initialization.

Returns

The interface name as a string.

getIoMapSize()

size_t soempp::Master::getIoMapSize

(

)

const

Returns the total size of the I/O map for the current group.

The total size is calculated as the sum of output bytes (Obytes) and input bytes (Ibytes) defined in the current group of the fieldbus.

Returns

Total number of bytes in the I/O map.

getSlaves()

const std::vector< std::unique_ptr< soempp::Slave > > & soempp::Master::getSlaves

(

)

const

Returns a reference to the list of slaves.

This function provides access to the internal vector of slave devices. The returned reference allows modification of the vector of std::unique_ptr<soempp::Slave> elements. Ownership of the slave objects remains with the Master object.

Returns

A reference to a std::vector<std::unique_ptr<soempp::Slave>> containing the slaves.

init()

void soempp::Master::init

(

const std::string &

iface

)

Initializes the fieldbus using the specified network interface.

Sets up the EtherCAT context and underlying Ethernet interface required for communication. This includes configuring the context to prevent devices without firmware from entering the SAFE-OPERATIONAL state — a condition that would otherwise require a power cycle to recover from.

The following operations are performed:

• Initializes the SOEM fieldbus context using ecx_init().
• Prepares the network interface for EtherCAT communication.
• Sets up the NIC, including:
  • Semaphore creation.
  • Frame buffer allocation.
  • Binding to the multiplex Ethernet driver (if applicable).
• Supports both primary and redundant (secondary) configurations.
• Initializes Ethernet headers for EtherCAT frame communication.

Detailed steps performed by ecx_init():

1. Opens a raw socket on the specified interface (e.g., "eth0", "enp3s0").
   • Uses a Linux raw socket (AF_PACKET) or Windows WinPcap/Npcap to directly send/receive Ethernet frames (not IP/TCP).
2. Binds the socket and enables promiscuous mode to capture EtherCAT frames.
   • EtherCAT uses a custom Ethernet type (0x88A4) that standard NICs ignore.
3. Configures internal SOEM structures (ecx_context, port, redport, etc.):
   • Initializes socket pointers, frame buffers, timing variables, slave tables, and state trackers.
4. Prepares transmission (Tx) and reception (Rx) buffers.
5. Resets EtherCAT frame sequence counters and working counters.
6. Sets up retry and retransmission mechanisms.

Note

• This method performs only the low-level Ethernet setup.
• Slave scanning and PDO configuration are not performed here. To do so, call ecx_config_init() separately — this is handled by initSlaves().

Warning

Potential issues during initialization:

• Incorrect interface name (e.g., "eth1" vs. "eth0").
• Insufficient permissions (requires CAP_NET_RAW or root).
• NIC driver or hardware limitations (e.g., promiscuous mode restrictions).
• On Windows, Npcap must be correctly installed and configured.

Parameters

iface

The name of the Ethernet interface to initialize (e.g., "eth0").

Exceptions

std::runtime_error

if ecx_init() fails or setup cannot complete.

initSlaves()

int soempp::Master::initSlaves

(

)

Initializes the slave devices on the EtherCAT network.

This function configures the slaves on the EtherCAT fieldbus by calling ecx_config_init() with the provided context. It scans the network for all connected slaves, assigns logical addresses to them, and configures their parameters (such as PDO mapping, communication settings, etc.).

If ecx_config_init() fails (e.g., no slaves detected, communication issues, or network misconfiguration), an error is logged, and a std::runtime_error is thrown, providing the cause of the failure.

Once the slaves are successfully initialized, the method loops through each detected slave and adds it to the slaves_ vector using emplace_back. This enables subsequent operations to be performed on each slave via the slaves_ collection, allowing communication and control after initialization.

Detailed initialization process:

1. Calls ecx_config_init() to scan and configure slaves based on the provided context:
   • Broadcasts a datagram to identify all connected slaves on the network.
   • Assigns logical addresses to each slave based on the provided configuration table.
   • For each slave:
     • Reads identity data (e.g., Vendor ID, Product Code, Serial Number, etc.).
     • Configures communication parameters such as frame sizes, synchronization settings, etc.
     • Sets up PDO mappings if usetable is TRUE, using the configuration table to map I/O data.
   • Initializes internal structures (e.g., ec_slave[], ec_group[]) to store slave and group information.
2. If slave initialization is successful, iterates through the detected slaves.
3. Each slave is added to the slaves_ vector using emplace_back, allowing for further operations.

This method should typically be called after ecx_init() to initialize the EtherCAT interface. It prepares the slaves for communication, allowing the system to begin exchanging data or transitioning to various states such as OPERATIONAL or SAFE-OPERATIONAL.

Returns

The number of slaves found and successfully initialized on the EtherCAT network.

Exceptions

std::runtime_error

if ecx_config_init() fails (e.g., no slaves found, network issues, or timeout).

Warning

Common issues during initialization:

• Slaves not found: Verify physical connections, check cables, or ensure correct interface settings.
• Incorrect slave address mapping: Ensure the configuration table is correct or manually configure slave addresses.

See also

ecx_init() for setting up the EtherCAT communication interface.

ecx_config_init() for details on slave enumeration and configuration.

ecx_config_map_group() for further manual configuration of slave PDO mappings and groups.

roundtrip()

int soempp::Master::roundtrip

(

)

Performs a complete send/receive process data cycle on the fieldbus.

Sends process data and then waits to receive the corresponding process data response.

Returns

The received working counter (WKC) from the fieldbus.

start()

bool soempp::Master::start

(

)

Initializes and starts the fieldbus master.

Maps process data I/O, configures distributed clocks, and transitions all slaves through SAFE-OPERATIONAL to OPERATIONAL state. Also sends an initial process data roundtrip to ensure proper output synchronization on the slaves.

Returns

True if the start sequence completes successfully.

---

The documentation for this class was generated from the following files:

• libs/soempp/soempp.h
• libs/soempp/soempp.cc