mm::comm::soem Namespace Reference

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...
struct	SlaveInfoMailbox
	Information about a slave's mailbox configuration. More...

Functions
std::map< std::string, std::string >	mapMacAddressesToInterfaces ()
	Maps MAC addresses to their corresponding network interface names.
SlaveInfo	getSlaveInfo (ecx_contextt *context, uint16 position)
void	logSlaveInfo (ecx_contextt *context, uint16 position)
	Logs detailed information about a specific EtherCAT slave in JSON format.
int	setPdoMappingFromUiConfig (ecx_contextt *context, uint16 slave)
	Sets PDO mapping for a specified EtherCAT slave using UI configuration.
void	checkPdoMapping (ecx_contextt *context, uint16 slave)
	Diagnoses and prints the PDO mapping for a given slave.
uint16_t	getSlaveState (ecx_contextt *context, uint16_t slave, bool forceRefresh)
	Retrieves the current state of a specific EtherCAT slave.
std::string	convertSlaveStateToString (int state)
	Converts a numeric EtherCAT state value into a human-readable string.
bool	transitionToHigherSlaveState (ecx_contextt *context, uint16_t slave, int targetState)
	Transitions a slave to a higher EtherCAT state.
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).
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.
bool	setSlaveState (ecx_contextt *context, uint16_t slave, int targetState)
	Sets the state of a specified EtherCAT slave.
mm::comm::base::PdoMappings	readPdoMappings (ecx_contextt *context, uint16_t slave)
	Read and parse all mapped PDO entries for a given slave.
void	logPdoMappingEntries (const std::vector< mm::comm::base::PdoMappingEntry > &entries)
	Logs PDO mapping entries grouped by PDO index.
void	logIoMap (uint8_t *ioMap, size_t totalBytes)
	Logs the I/O map as a formatted hexadecimal string.
void	initFieldbus (std::unique_ptr< Fieldbus > &fieldbus, const std::string &iface)
	Initializes a Fieldbus instance for EtherCAT communication.
	NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE (SlaveInfoMailbox, readLength, readOffset, supportedProtocols, writeLength, writeOffset) struct SlaveInfoSyncManager
	Information about a slave's Sync Manager (SM) configuration.
	NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE (SlaveInfoSyncManager, flags, length, startAddress, type) struct SlaveInfoFmmu
	Information about a slave's Fieldbus Memory Management Unit (FMMU).
	NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE (SlaveInfoFmmu, active, logicalEndBit, logicalStartBit, logicalStartAddress, logicalLength, physicalStartBit, physicalStartAddress, type) struct SlaveInfo
	General information about an EtherCAT slave device.
	NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE (SlaveInfo, alStatusCode, aliasAddress, fmmus, mailbox, productCode, position, revisionNumber, syncManagers, name, vendorId) SlaveInfo getSlaveInfo(ecx_contextt *context
	Retrieves detailed information about a specific EtherCAT slave.

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

Function Documentation

checkPdoMapping()

void mm::comm::soem::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 mm::comm::soem::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 mm::comm::soem::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.

getSlaveInfo()

SlaveInfo mm::comm::soem::getSlaveInfo	(	ecx_contextt *	context,
		uint16	position )

getSlaveState()

uint16_t mm::comm::soem::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 mm::comm::soem::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 mm::comm::soem::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 mm::comm::soem::logPdoMappingEntries

(

const std::vector< mm::comm::base::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.

logSlaveInfo()

void mm::comm::soem::logSlaveInfo	(	ecx_contextt *	context,
		uint16	position )

Logs detailed information about a specific EtherCAT slave in JSON format.

This function retrieves all relevant information about a slave at the given position in the ECX context's slave list, converts it to JSON using nlohmann::json, and logs it.

Parameters

context	Pointer to an initialized ECX context (ecx_contextt*) containing the slave list.
position	Slave position in the context's slave list, starts from 1.

Note

Requires that the SlaveInfo struct can be serialized to JSON using nlohmann::json.

Logging is done using LOG_F(INFO, ...) macro.

mapMacAddressesToInterfaces()

std::map< std::string, std::string > mm::comm::soem::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.

NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE() [1/4]

mm::comm::soem::NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE	(	SlaveInfo	,
		alStatusCode	,
		aliasAddress	,
		fmmus	,
		mailbox	,
		productCode	,
		position	,
		revisionNumber	,
		syncManagers	,
		name	,
		vendorId	)

Retrieves detailed information about a specific EtherCAT slave.

This function extracts all relevant data from the given EtherCAT context for the slave at the specified position in the slave list.

Parameters

context	Pointer to an initialized ECX context (ecx_contextt*) containing the slave list.
position	Slave position in the context's slave list, starts from 1.

Returns

SlaveInfo Struct containing all collected information about the slave.

NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE() [2/4]

mm::comm::soem::NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE	(	SlaveInfoFmmu	,
		active	,
		logicalEndBit	,
		logicalStartBit	,
		logicalStartAddress	,
		logicalLength	,
		physicalStartBit	,
		physicalStartAddress	,
		type	)

General information about an EtherCAT slave device.

This struct aggregates key properties and configuration of a slave, including identity, mailbox settings, FMMUs, and sync managers.

Application Layer (AL) status code.

Represents the current EtherCAT AL status of the slave (see EtherCAT standard AL Status Codes).

Alias address of the slave.

Used to differentiate between multiple slaves with the same position in the network. Default is 0x0000 if not configured.

List of Fieldbus Memory Management Units (FMMUs) for this slave.

Each FMMU maps logical process data to the slave's physical memory.

Mailbox configuration.

Defines offsets, lengths, and supported protocols for mailbox communication (e.g., CoE, FoE, EoE).

Product code of the slave.

Vendor-assigned identifier for the device type.

Retrieved from the slave's EEPROM.

Position of the slave in the EtherCAT network.

Also called the slave number; starts from 1 for the first slave.

Revision number of the slave device.

Vendor-assigned revision/version identifier.

Retrieved from the slave's EEPROM.

List of Sync Manager configurations.

Sync Managers handle cyclic process data transfer for inputs, outputs, and mailbox communication.

Name of the slave device.

Retrieved from the slave's EEPROM.

Vendor ID of the slave.

Unique identifier assigned by the EtherCAT Technology Group to the manufacturer.

Retrieved from the slave's EEPROM.

NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE() [3/4]

mm::comm::soem::NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE	(	SlaveInfoMailbox	,
		readLength	,
		readOffset	,
		supportedProtocols	,
		writeLength	,
		writeOffset	)

Information about a slave's Sync Manager (SM) configuration.

Sync Managers in EtherCAT control the flow of process data between the master and slave. Each SM defines a memory area for input, output, or mailbox communication.

SM flags.

Flags indicate the characteristics of the Sync Manager, such as:

• Direction (read/write)
• Whether it is enabled
• Other device-specific attributes

Length of the Sync Manager area (in bytes).

Specifies the size of the memory block that the Sync Manager manages for process data.

Start address of the Sync Manager area in the slave memory.

Indicates where the data block starts in the slave's process data memory.

Type of the Sync Manager.

Common EtherCAT SM types:

• 0: Unused
• 1: Mailbox Write (MbxWr)
• 2: Mailbox Read (MbxRd)
• 3: Outputs (from master to slave)
• 4: Inputs (from slave to master)

NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE() [4/4]

mm::comm::soem::NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE	(	SlaveInfoSyncManager	,
		flags	,
		length	,
		startAddress	,
		type	)

Information about a slave's Fieldbus Memory Management Unit (FMMU).

FMMUs in EtherCAT map logical process data addresses to physical memory in the slave. They allow flexible and efficient data access between master and slave.

Whether the FMMU is active.

0 = inactive, 1 = active.

Logical end bit of the FMMU mapping.

Indicates the last bit within the logical address space covered by this FMMU.

Logical start bit of the FMMU mapping.

Indicates the first bit within the logical address space covered by this FMMU.

Logical start address.

Start address in the slave's logical process data space.

Length of the logical memory area.

Specifies the number of bytes covered by this FMMU.

Physical start bit of the FMMU mapping.

Indicates the starting bit in the slave's physical memory that corresponds to logicalStartAddress.

Physical start address.

Start address in the slave's physical memory for this FMMU mapping.

FMMU type.

Usually indicates read/write direction or other attributes defined by the slave device.

readPdoMappings()

mm::comm::base::PdoMappings mm::comm::soem::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 mm::comm::soem::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 mm::comm::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 mm::comm::soem::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 mm::comm::soem::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 mm::comm::soem::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

position

uint16 mm::comm::soem::position

uiConfigWithDefaultPdoMapping

std::string mm::comm::soem::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 mm::comm::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 mm::comm::UiConfigJson parser implementation.