Classes
struct	Fieldbus
	Structure representing the Fieldbus configuration and context for EtherCAT communication. More...

class	Master

class	Slave
	Represents a slave in the EtherCAT network. More...

Functions
std::map< std::string, std::string >	mapMacAddressesToInterfaces ()
	Maps MAC addresses to their corresponding network interface names. More...

int	setPdoMappingFromUiConfig (ecx_contextt *context, uint16 slave)
	Sets PDO mapping for a specified EtherCAT slave using UI configuration. More...

void	checkPdoMapping (ecx_contextt *context, uint16 slave)
	Diagnoses and prints the PDO mapping for a given slave. More...

uint16_t	getSlaveState (ecx_contextt *context, uint16_t slave, bool forceRefresh)
	Retrieves the current state of a specific EtherCAT slave. More...

std::string	convertSlaveStateToString (int state)
	Converts a numeric EtherCAT state value into a human-readable string. More...

bool	transitionToHigherSlaveState (ecx_contextt *context, uint16_t slave, int targetState)
	Transitions a slave to a higher EtherCAT state. More...

void	updateMailboxSyncManagersOnNextState (ecx_contextt *context, uint16_t slave, int targetState)
	Updates the mailbox and sync manager (SM) configurations for an EtherCAT slave when transitioning to specific states (e.g., BOOT or INIT). More...

void	configureDetectedSmmModule (ecx_contextt *context, uint16_t slave)
	Reads the detected SMM module ID from the slave device and configures the module identification object accordingly. More...

bool	setSlaveState (ecx_contextt *context, uint16_t slave, int targetState)
	Sets the state of a specified EtherCAT slave. More...

common::PdoMappings	readPdoMappings (ecx_contextt *context, uint16_t slave)
	Read and parse all mapped PDO entries for a given slave. More...

void	logPdoMappingEntries (const std::vector< common::PdoMappingEntry > &entries)
	Logs PDO mapping entries grouped by PDO index. More...

void	logIoMap (uint8_t *ioMap, size_t totalBytes)
	Logs the I/O map as a formatted hexadecimal string. More...

void	initFieldbus (std::unique_ptr< Fieldbus > &fieldbus, const std::string &iface)
	Initializes a Fieldbus instance for EtherCAT communication. More...

Variables
std::string	uiConfigWithDefaultPdoMapping
	Default UI configuration used for PDO mapping. More...

Function Documentation

◆ checkPdoMapping()

void soempp::checkPdoMapping	(	ecx_contextt *	context,
		uint16	slave
	)

Diagnoses and prints the PDO mapping for a given slave.

This function reads the number of RxPDO and TxPDO assignments from the slave, then iterates through them to read and print the mappings and their entries. It checks for RxPDOs in the range 0x1600-0x16FF and TxPDOs in the range 0x1A00-0x1AFF. For each PDO, it reads the index and subindex values and prints them along with the length (in bits) of the entry.

Parameters

context	The EtherCAT context for communication.
slave	The slave address to be diagnosed.

Note: This function uses ecx_SDOread to fetch the assignment counts and entries for both RxPDO and TxPDO. It prints out the data to the console for inspection. It assumes the slave supports PDO mappings in the specified ranges.

◆ configureDetectedSmmModule()

void soempp::configureDetectedSmmModule	(	ecx_contextt *	context,
		uint16_t	slave
	)

Reads the detected SMM module ID from the slave device and configures the module identification object accordingly.

This function reads the detected module identification (object 0xF050:02) from the specified slave device using the given EtherCAT context. If a valid module ID is found (non-zero), it writes this ID back to the configured module identification object (0xF030:02) on the slave.

Parameters

[in,out]	context	Pointer to the EtherCAT master context.
[in]	slave	Slave device number to query.

Note: Logs informational messages about detected modules and errors if writing the configured module ID fails.

◆ convertSlaveStateToString()

std::string soempp::convertSlaveStateToString ( int state )

Converts a numeric EtherCAT state value into a human-readable string.

This function maps a numeric EtherCAT state (e.g., EC_STATE_INIT, EC_STATE_OPERATIONAL) to its corresponding human-readable string representation. If the state includes the ERROR flag, the string will append " + ERROR" to the state name.

The function recognizes common EtherCAT states such as INIT, PRE-OPERATIONAL, SAFE-OPERATIONAL, and OPERATIONAL, as well as combinations with the ERROR flag. If the state is unrecognized, the function returns the string "UNRECOGNIZED".

Parameters

state The numeric EtherCAT state value to convert.

Returns: A string representing the EtherCAT state, including its numeric value in parentheses. If the state is unrecognized, the string "UNRECOGNIZED" is returned.

◆ getSlaveState()

uint16_t soempp::getSlaveState	(	ecx_contextt *	context,
		uint16_t	slave,
		bool	forceRefresh
	)

Retrieves the current state of a specific EtherCAT slave.

This function returns the current state of a specified EtherCAT slave. If forceRefresh is true, the function explicitly reads the state from the slave device using ecx_FPRD, bypassing the cached value. The retrieved state is then stored in the master context.

The function accesses the AL status register and status code register of the slave to update the internal state tracking. This method avoids using ecx_readstate, which reads all slaves' states and may introduce delays, making this function more suitable for single-slave queries.

Parameters

context	Pointer to the EtherCAT master context.
slave	The slave index in the master's list, starting at 1 (0 is reserved for the master).
forceRefresh	If true, the state is re-read from the slave hardware.

Returns: The current state of the specified slave (e.g., EC_STATE_INIT, EC_STATE_OPERATIONAL). If forceRefresh is false, the cached state is returned.

◆ initFieldbus()

void soempp::initFieldbus	(	std::unique_ptr< Fieldbus > &	fieldbus,
		const std::string &	iface
	)

Initializes a Fieldbus instance for EtherCAT communication.

This function allocates and initializes a new Fieldbus object using the specified network interface name. It sets default values and links internal pointers in the ecx_contextt structure to the corresponding members of the Fieldbus object.

Parameters

[out]	fieldbus	A reference to a unique pointer that will hold the newly created Fieldbus instance.
	iface	The name of the network interface (e.g., "eth0") to use for EtherCAT communication.

Note: The contents of the allocated Fieldbus object are zero-initialized before assignment. Internal SOEM context structures are set up to refer to this object’s members.

◆ logIoMap()

void soempp::logIoMap	(	uint8_t *	ioMap,
		size_t	totalBytes
	)

Logs the I/O map as a formatted hexadecimal string.

This function takes a pointer to an I/O map and its total size in bytes, then logs the contents in hexadecimal format using LOG_F. Each byte is formatted as 0xNN with uppercase hex digits and padded to two characters.

Parameters

ioMap	Pointer to the I/O map buffer.
totalBytes	Total number of bytes in the I/O map.

◆ logPdoMappingEntries()

void soempp::logPdoMappingEntries ( const std::vector< common::PdoMappingEntry > & entries )

Logs PDO mapping entries grouped by PDO index.

This function organizes PDO mapping entries by their PDO index and logs each group, displaying entries in the order of their appearance. Within each PDO group, the entries are displayed in the format:

PDO index
Index, Subindex, and Bitlength of each entry in the group

Parameters

entries A vector of PDO mapping entries to be logged, where each entry contains the PDO index, object index, subindex, and bit length.

Note: This function uses LOG_F(INFO, ...) for logging the details.

◆ mapMacAddressesToInterfaces()

std::map< std::string, std::string > soempp::mapMacAddressesToInterfaces ( )

Maps MAC addresses to their corresponding network interface names.

Scans available network adapters and constructs a map where each entry associates a MAC address (as a string) with its corresponding interface name.

This is useful for identifying interfaces by their hardware address, e.g., when selecting a specific NIC for EtherCAT communication.

Returns: A map with MAC address strings as keys and interface names as values.

◆ readPdoMappings()

common::PdoMappings soempp::readPdoMappings	(	ecx_contextt *	context,
		uint16_t	slave
	)

Read and parse all mapped PDO entries for a given slave.

This function reads the PDO assignments (0x1C12 and 0x1C13) and gathers all mapped objects into categorized RxPDO and TxPDO vectors.

Parameters

context	Pointer to the active EtherCAT context.
slave	Slave index (starting from 1).

Returns: A PdoMappings structure containing the parsed Rx and Tx PDO mappings.

◆ setPdoMappingFromUiConfig()

int soempp::setPdoMappingFromUiConfig	(	ecx_contextt *	context,
		uint16	slave
	)

Sets PDO mapping for a specified EtherCAT slave using UI configuration.

This function attempts to read a ui.config.json file from the given EtherCAT slave using File-over-EtherCAT (FoE). If the read fails, it falls back to using a built-in default configuration.

The function then:

Parses the configuration JSON to obtain PDO mapping details.
Clears existing PDO and Sync Manager (SM) mappings on the slave.
Writes new PDO mapping entries and SM assignments to the slave's object dictionary.

Parameters

context	Pointer to the EtherCAT master context (`ecx_contextt`).
slave	Index of the slave device (starting from 1).

Returns: int Returns 1 on success, or 0 on failure (e.g., JSON parse error).

Note: This function requires the common::UiConfigJson struct to be properly defined and compatible with the JSON structure in ui.config.json.

Warning: Uses hardcoded buffer size for reading the file. Make sure the file fits.

◆ setSlaveState()

bool soempp::setSlaveState	(	ecx_contextt *	context,
		uint16_t	slave,
		int	targetState
	)

Sets the state of a specified EtherCAT slave.

This function attempts to transition the state of a slave to the target state. If the slave is in an error state, it acknowledges and clears the error before transitioning to the target state. The function handles special cases for state transitions, including moving to the INIT or BOOT states.

Parameters

context	A pointer to the EtherCAT master context.
slave	The slave index in the master's list, starting at 1 (0 is reserved for the master).
targetState	The desired state to set for the slave.

Returns: True if the slave successfully transitions to the target state, false otherwise.

◆ transitionToHigherSlaveState()

bool soempp::transitionToHigherSlaveState	(	ecx_contextt *	context,
		uint16_t	slave,
		int	targetState
	)

Transitions a slave to a higher EtherCAT state.

This function attempts to transition an EtherCAT slave to a specified target state. If the slave is in an error state, it acknowledges the error and attempts to transition to the target state. The function performs state checks during the process and ensures that the slave transitions correctly.

Parameters

context	A pointer to the EtherCAT master context.
slave	The slave index in the master's list, starting at 1 (0 is reserved for the master).
targetState	The desired target state for the slave.

Returns: True if the slave successfully transitions to the target state, false otherwise.

◆ updateMailboxSyncManagersOnNextState()

void soempp::updateMailboxSyncManagersOnNextState	(	ecx_contextt *	context,
		uint16_t	slave,
		int	targetState
	)

Updates the mailbox and sync manager (SM) configurations for an EtherCAT slave when transitioning to specific states (e.g., BOOT or INIT).

This function configures the sync managers (SM0 and SM1) for the target slave based on the target state. It handles the following scenarios:

For the BOOT state, it reads and configures the BOOT RX and TX mailbox data, and programs the corresponding sync manager configurations (SM0 and SM1).
For the INIT state, it reads the RX and TX mailbox addresses and lengths, and configures the respective sync managers (SM0 and SM1) for the slave.

Parameters

context	A pointer to the EtherCAT master context.
slave	The position of the target slave in the master's slave list.
target_state	The target EtherCAT state the slave is transitioning to (e.g., EC_STATE_BOOT, EC_STATE_INIT).

Note: This function programs the mailbox configurations for the slave based on the specified state and also handles special cases for the BOOT and INIT states.

Variable Documentation

◆ uiConfigWithDefaultPdoMapping

std::string soempp::uiConfigWithDefaultPdoMapping

inline

Default UI configuration used for PDO mapping.

This JSON string defines the default Process Data Object (PDO) mapping configuration, including Receive (Rx) and Transmit (Tx) PDOs. It is used as a fallback when reading the configuration file from an EtherCAT slave fails.

The structure follows a JSON schema compatible with common::UiConfigJson, and includes:

Rx PDO assignments under "rx" (e.g., 0x1600, 0x1601, ...)
Tx PDO assignments under "tx" (e.g., 0x1a00, 0x1a01, ...)

Note: This string should remain synchronized with the expected JSON schema in the common::UiConfigJson parser implementation.

Classes

Functions

Variables

Function Documentation

◆ checkPdoMapping()

◆ configureDetectedSmmModule()

◆ convertSlaveStateToString()

◆ getSlaveState()

◆ initFieldbus()

◆ logIoMap()

◆ logPdoMappingEntries()

◆ mapMacAddressesToInterfaces()

◆ readPdoMappings()

◆ setPdoMappingFromUiConfig()

◆ setSlaveState()

◆ transitionToHigherSlaveState()

◆ updateMailboxSyncManagersOnNextState()

Variable Documentation

◆ uiConfigWithDefaultPdoMapping