Classes
struct	Fieldbus
	Structure representing the Fieldbus configuration and context for EtherCAT communication. More...
struct	IghMasterModule
	The IgH EtherCAT Master kernel module, as the running kernel reports it. More...
class	Master
class	Slave
	Represents a slave in the EtherCAT network. More...
struct	SlaveInfoMailbox
	Information about a slave's mailbox configuration. More...
struct	StationAddressReading
	What a slave's station address register holds, read by the slave's position on the bus. More...

Functions
std::recursive_mutex &	controlPlaneMutex ()
	The single mutex that serialises every control-plane transaction.
std::string	drainMailboxErrors (ecx_contextt *context)
	Empties SOEM's error list and describes the first entry found.
int	drainMailbox (ecx_contextt *context, uint16_t slave)
	Discards whatever is sitting in a slave's read mailbox.
std::map< std::string, std::string >	mapMacAddressesToInterfaces ()
	Maps MAC addresses to their corresponding network interface names.
IghMasterModule	readIghMasterModule (const std::string &moduleDirectory="/sys/module/ec_master")
	Reads the IgH EtherCAT Master kernel module's state from sysfs.
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, int timeoutUs=EC_TIMEOUTRET)
	Reads the current state of a specific EtherCAT slave directly from the device via an FPRD datagram.
bool	isSlaveAnswering (ecx_contextt *context, uint16_t slave)
	Tells whether a slave still answers at its configured station address.
StationAddressReading	readStationAddressByPosition (ecx_contextt *context, uint16_t slave, int timeoutUs=EC_TIMEOUTRET)
	Reads a slave's station address register (0x0010) by the slave's position on the bus.
std::string	convertSlaveStateToString (int state)
	Converts a numeric EtherCAT state value into a human-readable string.
void	resetBootMailboxTracking ()
	Clears the internal record of which slaves hold BOOT-sized mailbox sync managers.
bool	resetMailboxCounter (ecx_contextt *context, uint16_t slave)
	Makes the slave forget the counter of the last mailbox request.
void	transitionSlaves (ecx_contextt context, const std::vector< uint16_t > &positions, uint16_t requiredState, uint16_t targetState, const char targetName, std::chrono::steady_clock::duration timeout, std::chrono::steady_clock::duration resendInterval=std::chrono::seconds(2), std::function< void()> tick=nullptr, std::function< bool()> shouldAbort=nullptr)
	Transitions multiple EtherCAT slaves to a target state using a single-threaded fire-then-poll pattern safe for use with SOEM's fixed-size frame buffer (EC_MAXBUF=16).
bool	setSlaveState (ecx_contextt *context, uint16_t slave, uint16_t targetState, std::chrono::steady_clock::duration timeout=std::chrono::seconds(5))
	Transitions a single EtherCAT slave to `targetState`.
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.
std::vector< uint8_t >	readSii (ecx_contextt *context, uint16 position)
	Read the complete Slave Information Interface (SII) EEPROM from an EtherCAT slave device.
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
constexpr uint16_t	kAlStatusCodeNoValidFirmware = 0x0014
constexpr int	kSdoTimeoutUs = 3'000'000
constexpr int	kFoeTimeoutUs = 10'000'000
constexpr int	kFoeReadTimeoutUs = 2'000'000
constexpr int	kFoeRemoveTimeoutUs = 10'000'000
constexpr int	kFoeRemoveEsiTimeoutUs = 30'000'000
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.

◆ controlPlaneMutex()

std::recursive_mutex & mm::comm::soem::controlPlaneMutex ( )

The single mutex that serialises every control-plane transaction.

SDO, FoE, SDO Info and register transfers all run through a slave's mailbox, and a mailbox holds one message at a time. When two threads have a transfer in flight at once, ecx_mbxreceive hands one thread the other's reply, which SOEM reports as a working counter of 0 or a timeout. Every control-plane path takes this mutex so only one transfer is ever outstanding.

The cyclic process-data exchange deliberately does not take it: it uses no mailbox, and SOEM's port layer already serialises frame transmission, so a slow file transfer must not stall the 1 ms loop.

Recursive because the control plane nests — a coarse hold (a whole file transfer, a whole object dictionary scan) runs individual transfers that lock again on the same thread.

Returns: A reference to the process-wide control-plane mutex.

◆ 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.

◆ drainMailbox()

int mm::comm::soem::drainMailbox	(	ecx_contextt *	context,
		uint16_t	slave )

Discards whatever is sitting in a slave's read mailbox.

A slave pushes emergencies without being asked, and a transfer that timed out can leave a stale reply behind. Either way the next request collects the wrong message: ecx_mbxreceive recognises an emergency or mailbox error, handles it, and returns 0, so the transfer that triggered the read fails through no fault of its own. Reading the mailbox out with a zero timeout before a transfer starts, and after one fails, means the next request meets an empty mailbox.

Bounded so a slave producing a continuous stream of messages cannot hold the caller here indefinitely.

Also consumes the error-list entry each discarded message produced, since for an emergency or a mailbox error that entry is the only evidence a message was there at all. Call drainMailboxErrors first when the reason for a failed transfer is still wanted.

Call with controlPlaneMutex() held.

Parameters

context	The SOEM master context.
slave	The 1-based slave position.

Returns: The number of messages discarded.

◆ drainMailboxErrors()

std::string mm::comm::soem::drainMailboxErrors ( ecx_contextt * context )

Empties SOEM's error list and describes the first entry found.

SOEM queues a reason for every failed mailbox transaction: an SDO abort, a mailbox error, or an emergency the slave pushed unprompted. The list is a fixed 64-entry ring (EC_MAXELIST) that silently overwrites its tail once full, and an entry left behind is inherited by the next transfer to fail, which then reports a reason belonging to an unrelated transaction. Draining on every failure keeps each reported reason the one that describes its own transfer.

The list is context-wide rather than per-slave, so a drain clears entries for every slave. Call with controlPlaneMutex() held, so the drain happens in the same critical section as the transfer that filled the list — popping outside it would let a concurrent transfer claim this one's reason.

Parameters

context The SOEM master context.

Returns: A description of the first queued entry, or an empty string when the list was already empty.

◆ getSlaveInfo()

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

◆ getSlaveState()

uint16_t mm::comm::soem::getSlaveState	(	ecx_contextt *	context,
		uint16_t	slave,
		int	timeoutUs = EC_TIMEOUTRET )

Reads the current state of a specific EtherCAT slave directly from the device via an FPRD datagram.

Avoids ecx_readstate, which reads all slaves at once. Suitable for single-slave queries.

Parameters

context	Pointer to the EtherCAT master context.
slave	Slave index (1-based; 0 is the master and must not be used).
timeoutUs	How long the datagram has to come back. Defaults to `EC_TIMEOUTRET`, which is sized so that a frame the host holds back is still waited for rather than counted as lost. A caller on the cyclic thread should pass something short instead: there, a read that gives up early costs a log line, while one that waits costs the cycle.

Returns: The current AL state value (e.g., EC_STATE_INIT, EC_STATE_OPERATIONAL).

◆ 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.

◆ isSlaveAnswering()

bool mm::comm::soem::isSlaveAnswering	(	ecx_contextt *	context,
		uint16_t	slave )

Tells whether a slave still answers at its configured station address.

Every mailbox transfer and every FPRD/FPWR datagram reaches the slave through the station address that ec_config_init() wrote into it. The slave stops answering at that address when the link is gone, when the slave lost power (the station address register is cleared at power-up), or when another master wrote a different address into it. In all three cases every further transfer returns wkc 0 until the bus is enumerated again.

One lost frame does not mean the slave is gone, so the slave counts as not answering only after several reads in a row get no answer.

Parameters

context	Pointer to the EtherCAT master context.
slave	Slave index (1-based; 0 is the master and must not be used).

Returns: true if the slave answered at least one of the reads.

◆ 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.

◆ readIghMasterModule()

IghMasterModule mm::comm::soem::readIghMasterModule ( const std::string & moduleDirectory = "/sys/module/ec_master" )

Reads the IgH EtherCAT Master kernel module's state from sysfs.

The kernel lists a loaded module under /sys/module, with its parameters in the parameters directory. On a system without that directory, which includes Windows, the module is reported as not loaded.

Parameters

moduleDirectory The module's sysfs directory. Tests pass a directory of their own.

◆ 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.

◆ readSii()

std::vector< uint8_t > mm::comm::soem::readSii	(	ecx_contextt *	context,
		uint16	position )

Read the complete Slave Information Interface (SII) EEPROM from an EtherCAT slave device.

This function reads the raw SII (EEPROM) content of a slave using the context-based API of SOEM (Simple Open EtherCAT Master). It first determines the EEPROM size from the SII header and then reads the entire content byte-by-byte.

If the reported EEPROM size is invalid (0x0000, 0xFFFF, or exceeds a safe upper bound), the function falls back to a default maximum size (8 KB).

Parameters

context	Pointer to initialized SOEM context (ecx_contextt).
position	Slave position (1-based index).

Returns: std::vector<uint8_t> Raw SII data as a byte array. Returns an empty vector if the context is invalid or the read operation fails.

Note

The slave should be in INIT or PRE-OP state for reliable EEPROM access.
Reading is performed using ecx_siigetbyte(), which abstracts EEPROM access.
This operation is relatively slow and should not be used in real-time loops.

Warning

Some slaves may report incorrect EEPROM sizes; a fallback is applied.
No retry mechanism is implemented; transient read errors may affect results.

See also: ecx_siigetbyte

◆ readStationAddressByPosition()

StationAddressReading mm::comm::soem::readStationAddressByPosition	(	ecx_contextt *	context,
		uint16_t	slave,
		int	timeoutUs = EC_TIMEOUTRET )

Reads a slave's station address register (0x0010) by the slave's position on the bus.

Parameters

context	Pointer to the EtherCAT master context.
slave	Slave index (1-based; 0 is the master and must not be used).
timeoutUs	How long the datagram has to come back. A caller on the cyclic thread should pass something short, as for getSlaveState().

◆ resetBootMailboxTracking()

void mm::comm::soem::resetBootMailboxTracking ( )

Clears the internal record of which slaves hold BOOT-sized mailbox sync managers.

transitionSlaves only reprograms a slave's mailbox sync managers before INIT->PRE-OP when that slave was previously driven into BOOT (otherwise the SMs ecx_config_init/ec_config_init already programmed are correct, and touching them re-seizes the EEPROM from the slave's PDI). That record must be dropped whenever the bus is re-scanned, because a fresh config_init reprograms every slave's SMs to PRE-OP sizes and hands EEPROM back to the PDI. Callers that run ec_config_init / ecx_config_init must call this immediately after a successful scan.

◆ resetMailboxCounter()

bool mm::comm::soem::resetMailboxCounter	(	ecx_contextt *	context,
		uint16_t	slave )

Makes the slave forget the counter of the last mailbox request.

SOMANET firmware ignores a mailbox request whose counter equals the counter of the previous request. Firmware before v5.6.0 keeps that counter across INIT, while ec_config_init / ecx_config_init restart the master's counter, so the first request after a re-scan carries 1. When the last request before the re-scan also carried 1, the slave ignores the new request, its mailbox stays full, and only a power cycle recovers it.

The firmware never ignores a request with counter 0 and stores 0 as the last counter. This sends one CoE SDO upload of 0x1000:00 with counter 0 and reads the answer. The master's counter is never 0, so the slave accepts the next request whatever its value. ETG1000.4 reserves counter 0, so call this for SOMANET devices only, in PRE-OP, before any other mailbox request after the scan.

Parameters

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

Returns: true if the request was written and answered.

◆ 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). Also returns 0 as soon as the slave stops answering at its station address (see isSlaveAnswering()), without finishing the mapping.

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,
		uint16_t	targetState,
		std::chrono::steady_clock::duration	timeout = std::chrono::seconds(5) )

Transitions a single EtherCAT slave to targetState.

Convenience wrapper around transitionSlaves for single-slave use.

Parameters

[in]	context	Pointer to the EtherCAT master context.
[in]	slave	Slave index (1-based).
[in]	targetState	Desired EtherCAT state.
[in]	timeout	Maximum time to wait. Defaults to 5 seconds.

Returns: true if the slave reaches targetState within timeout.

◆ transitionSlaves()

void mm::comm::soem::transitionSlaves	(	ecx_contextt *	context,
		const std::vector< uint16_t > &	positions,
		uint16_t	requiredState,
		uint16_t	targetState,
		const char *	targetName,
		std::chrono::steady_clock::duration	timeout,
		std::chrono::steady_clock::duration	resendInterval = std::chrono::seconds(2),
		std::function< void()>	tick = nullptr,
		std::function< bool()>	shouldAbort = nullptr )

Transitions multiple EtherCAT slaves to a target state using a single-threaded fire-then-poll pattern safe for use with SOEM's fixed-size frame buffer (EC_MAXBUF=16).

For each slave position in positions whose current state (as reported by the most recent ecx_readstate call) exactly matches requiredState, the function writes targetState via ecx_writestate. Pass EC_STATE_NONE as requiredState to command every slave regardless of its current state.

After commanding all slaves it polls with ecx_readstate (a single broadcast read that updates context->slavelist[i].state for every slave at once) until every commanded slave reaches targetState or timeout expires. Every resendInterval the command is re-sent to slaves that have not yet responded; error flags are acknowledged before re-sending.

Slaves that have not reached targetState when the deadline expires are logged as errors.

Parameters

[in]	context	Pointer to the EtherCAT master context.
[in]	positions	1-based slave indices to operate on.
[in]	requiredState	Pre-filter: only command slaves whose current state equals this value. Use `EC_STATE_NONE` to skip filtering and command all supplied slaves.
[in]	targetState	The EtherCAT state to transition slaves into.
[in]	targetName	Human-readable name logged for `targetState`.
[in]	timeout	Maximum total time to wait for all slaves.
[in]	resendInterval	How often to re-send the command to lagging slaves.
[in]	tick	Optional callback invoked at ~1 ms intervals while waiting. Pass a process-data sender (e.g. roundtrip()) here when transitioning to OP so the SM watchdog does not fire during the wait.
[in]	shouldAbort	Optional predicate checked at each poll interval. When it returns true the wait is abandoned early and no error is logged for pending slaves.

◆ 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

◆ kAlStatusCodeNoValidFirmware

uint16_t mm::comm::soem::kAlStatusCodeNoValidFirmware = 0x0014

inlineconstexpr

◆ kFoeReadTimeoutUs

int mm::comm::soem::kFoeReadTimeoutUs = 2'000'000

inlineconstexpr

◆ kFoeRemoveEsiTimeoutUs

int mm::comm::soem::kFoeRemoveEsiTimeoutUs = 30'000'000

inlineconstexpr

◆ kFoeRemoveTimeoutUs

int mm::comm::soem::kFoeRemoveTimeoutUs = 10'000'000

inlineconstexpr

◆ kFoeTimeoutUs

int mm::comm::soem::kFoeTimeoutUs = 10'000'000

inlineconstexpr

◆ kSdoTimeoutUs

int mm::comm::soem::kSdoTimeoutUs = 3'000'000

inlineconstexpr

◆ 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.

Classes

Functions

Variables

Function Documentation

◆ checkPdoMapping()

◆ configureDetectedSmmModule()

◆ controlPlaneMutex()

◆ convertSlaveStateToString()

◆ drainMailbox()

◆ drainMailboxErrors()

◆ getSlaveInfo()

◆ getSlaveState()

◆ initFieldbus()

◆ isSlaveAnswering()

◆ logIoMap()

◆ logPdoMappingEntries()

◆ logSlaveInfo()

◆ mapMacAddressesToInterfaces()

◆ NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE() [1/4]

◆ NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE() [2/4]

◆ NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE() [3/4]

◆ NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE() [4/4]

◆ readIghMasterModule()

◆ readPdoMappings()

◆ readSii()

◆ readStationAddressByPosition()

◆ resetBootMailboxTracking()

◆ resetMailboxCounter()

◆ setPdoMappingFromUiConfig()

◆ setSlaveState()

◆ transitionSlaves()

◆ updateMailboxSyncManagersOnNextState()

Variable Documentation

◆ kAlStatusCodeNoValidFirmware

◆ kFoeReadTimeoutUs

◆ kFoeRemoveEsiTimeoutUs

◆ kFoeRemoveTimeoutUs

◆ kFoeTimeoutUs

◆ kSdoTimeoutUs

◆ position

◆ uiConfigWithDefaultPdoMapping