Namespaces
namespace	soem

Classes
struct	AlStatusCode
	Metadata for a single AL Status Code entry. More...

struct	DcConfig
	Distributed-clock configuration for a slave. More...

struct	DcSyncDiagnostics
	Live distributed-clock synchronisation status for one slave, read from its ESC. More...

struct	EscRegister
	Metadata for a single ESC register entry. More...

class	FieldbusDriver
	Abstract interface for an EtherCAT fieldbus driver. More...

struct	FmmuConfig
	One FMMU's configuration as programmed on a slave's ESC. More...

struct	FoeError
	A structured FoE failure. String-like where a caller only forwards it (`operator<<`, .message, `what()`); branchable where a caller must react (`kind`, `retry`). More...

struct	FoeErrorCode
	Metadata for a single FoE error code entry. More...

struct	MailboxConfig
	Mailbox configuration for a slave (the CoE/FoE/EoE/SoE transport windows). More...

struct	MailboxErrorCode
	Metadata for a single CoE mailbox error code entry. More...

struct	NetworkAdapter

struct	ObjectDataTypeInfo
	Metadata for a single object dictionary data type. More...

struct	OdEntry
	Schema of a single object dictionary entry uploaded from a slave. More...

struct	PdoLayout
	Layout of the process-data images, produced by `configureProcessData`. More...

struct	PortDiagnostics
	Per-port link state and error counters decoded from a slave's ESC. More...

struct	ProcessDataWatchdogConfig
	Process-data (sync-manager) watchdog configuration of one slave. More...

class	ScopedQuietSdoLog
	RAII guard that suppresses per-transfer SDO debug logging for its scope (and restores the previous state on exit, so it nests correctly). More...

struct	SdoAbortCode
	Metadata for a single CoE SDO abort code entry. More...

struct	SiiCategoryDistributedClockElement
	One distributed-clock setting from SII category 60 (0x3C). More...

struct	SiiCategoryGeneral
	General device information (SII category 30 / 0x1E). More...

struct	SiiCategoryPdoElement
	One default PDO (RxPDO category 51 / 0x33, or TxPDO category 50 / 0x32). More...

struct	SiiCategoryPdoEntryElement
	One mapped object within a default PDO (SII categories 50/51). More...

struct	SiiCategorySection
	The decoded category section of an SII image. More...

struct	SiiCategorySyncManagerElement
	One Sync-Manager default from SII category 41 (0x29). More...

struct	SiiInfo
	SII (Slave Information Interface) — the structured EEPROM image of an EtherCAT slave. More...

struct	SlaveConfig
	Static ESC configuration snapshot for one slave, captured by `configureProcessData`. More...

struct	SlaveDiagnostics
	Decoded health diagnostics for one slave, read live from its ESC registers. More...

struct	SlaveInfo
	Immutable identity fields read from a slave's EEPROM during configuration. More...

struct	SlaveInformationInterface
	A fully parsed SII image: fixed header plus decoded categories. More...

struct	SlaveIo
	One slave's input and output windows within the process-data images. More...

struct	SyncManagerConfig
	One Sync Manager's configuration as programmed on a slave's ESC. More...

Enumerations
enum class	EtherCatState : uint16_t { Init = 0x01 , PreOp = 0x02 , Boot = 0x03 , SafeOp = 0x04 , Op = 0x08 }
	EtherCAT Application Layer state values. More...

enum class	Retry { Transient , Permanent }
	Retry disposition of a failed operation: whether re-issuing the identical call could plausibly succeed. This is the one axis callers branch on uniformly — a firmware flasher retries `Transient` failures and aborts on `Permanent` ones — so it rides alongside the FoE-specific kind rather than being folded into it. More...

enum class	FoeErrorKind { NoResponse , FileNotFound , BufferTooSmall , PacketMismatch , Protocol }
	Specific File-over-EtherCAT failure kind. Transport-agnostic: a SOEM driver decodes it from a negated `ec_err_type`, a future SPoE driver from its own protocol codes. More...

enum class	ObjectDataType : uint16_t { UNSPECIFIED = 0x0000 , BOOLEAN = 0x0001 , BYTE = 0x001E , WORD = 0x001F , DWORD = 0x0020 , BIT1 = 0x0030 , BIT2 = 0x0031 , BIT3 = 0x0032 , BIT4 = 0x0033 , BIT5 = 0x0034 , BIT6 = 0x0035 , BIT7 = 0x0036 , BIT8 = 0x0037 , BIT9 = 0x0038 , BIT10 = 0x0039 , BIT11 = 0x003A , BIT12 = 0x003B , BIT13 = 0x003C , BIT14 = 0x003D , BIT15 = 0x003E , BIT16 = 0x003F , BITARR8 = 0x002D , BITARR16 = 0x002E , BITARR32 = 0x002F , INTEGER8 = 0x0002 , INTEGER16 = 0x0003 , INTEGER24 = 0x0010 , INTEGER32 = 0x0004 , INTEGER40 = 0x0012 , INTEGER48 = 0x0013 , INTEGER56 = 0x0014 , INTEGER64 = 0x0015 , UNSIGNED8 = 0x0005 , UNSIGNED16 = 0x0006 , UNSIGNED24 = 0x0016 , UNSIGNED32 = 0x0007 , UNSIGNED40 = 0x0018 , UNSIGNED48 = 0x0019 , UNSIGNED56 = 0x001A , UNSIGNED64 = 0x001B , REAL32 = 0x0008 , REAL64 = 0x0011 , GUID = 0x001D , VISIBLE_STRING = 0x0009 , OCTET_STRING = 0x000A , UNICODE_STRING = 0x000B , WSTRING = 0x0268 , TIME_OF_DAY = 0x000C , TIME_DIFFERENCE = 0x000D , DOMAIN = 0x000F , ARRAY_OF_INT = 0x0260 , ARRAY_OF_SINT = 0x0261 , ARRAY_OF_DINT = 0x0262 , ARRAY_OF_UDINT = 0x0263 , ARRAY_OF_BITARR8 = 0x0264 , ARRAY_OF_BITARR16 = 0x0265 , ARRAY_OF_BITARR32 = 0x0266 , ARRAY_OF_USINT = 0x0267 , ARRAY_OF_REAL = 0x0269 , ARRAY_OF_LREAL = 0x026A , PDO_MAPPING = 0x0021 , IDENTITY = 0x0023 , COMMAND_PAR = 0x0025 , PDO_PARAMETER = 0x0027 , ENUM = 0x0028 , SM_SYNCHRONISATION = 0x0029 , RECORD = 0x002A , BACKUP_PARAMETER = 0x002B , MODULAR_DEVICE_PROFILE = 0x002C , ERROR_SETTING = 0x0281 , DIAGNOSIS_HISTORY = 0x0282 , EXTERNAL_SYNC_STATUS = 0x0283 , EXTERNAL_SYNC_SETTINGS = 0x0284 , DEFTYPE_FSOEFRAME = 0x0285 , DEFTYPE_FSOECOMMPAR = 0x0286 , UTYPE_START = 0x0800 , UTYPE_END = 0x0FFF }
	CoE object dictionary data type codes. More...

enum class	SiiCategoryType : uint16_t { Nop = 0 , DeviceSpecific = 1 , Strings = 10 , DataTypes = 20 , General = 30 , Fmmu = 40 , SyncM = 41 , FmmuX = 42 , SyncUnit = 43 , TxPdo = 50 , RxPdo = 51 , Dc = 60 , Timeouts = 70 , Dictionary = 80 , Hardware = 90 , VendorInformation = 100 , Images = 110 , VendorSpecific = 0x0800 , ApplicationSpecific = 0x2000 , End = 0xFFFF }
	Recognised SII category type identifiers (ETG.2010 Table 5). More...

Functions
void	to_json (nlohmann::json &j, const AlStatusCode &c)
	Serialises an AlStatusCode to JSON.

constexpr const AlStatusCode *	findAlStatusCode (uint16_t code)
	Looks up `code` in kAlStatusCodes, or returns nullptr if it is not catalogued.

constexpr bool	isAlStatusCodeTerminal (uint16_t code)
	Returns true if `code` indicates a state-transition failure that cannot be resolved by retrying the same writestate.

constexpr std::string_view	alStatusCodeName (uint16_t code)
	Returns the short name for `code`, or an empty view if `code` is not a known AL Status Code.

void	to_json (nlohmann::json &j, const NetworkAdapter &a)
	Serialises a NetworkAdapter to JSON.

bool	isMacAddress (const std::string &s)
	Returns true if `s` is a MAC address in either Linux (:) or Windows (`-`) separator format.

std::string	normalizeMac (const std::string &raw, char sep)
	Normalises a MAC address string to uppercase with the given separator.

std::vector< NetworkAdapter >	enumerateNetworkAdapters ()
	Enumerates all network adapters visible to the OS.

std::expected< NetworkAdapter, std::string >	resolveNetworkAdapter (const std::string &input)
	Resolves a network adapter specifier to a fully populated `NetworkAdapter`.

void	to_json (nlohmann::json &j, const EscRegister &r)
	Serialises an EscRegister to JSON.

EtherCatState	alState (uint16_t alStatus)
	Extracts the AL state (bits 3:0) from a raw AL Status register value (0x0130).

bool	alHasError (uint16_t alStatus)
	Returns whether the AL Status error indicator (bit 4 of register 0x0130) is set.

std::string_view	toString (EtherCatState state)
	Human-readable name of an AL state, for log and error messages.

int	workingCounterContribution (EtherCatState state, bool hasOutputs, bool hasInputs)
	Working-counter contribution of one slave for a given AL state and PDO presence.

std::string_view	foeReason (FoeErrorKind kind)
	Short human-readable reason for a FoE kind (no surrounding punctuation).

Retry	foeRetry (FoeErrorKind kind)
	Retry disposition implied by a FoE kind. A missing file or an undersized buffer is a fixed condition that will recur identically; a desync or a not-yet-ready slave (the BOOT bootloader warm-up path) is worth another attempt.

std::ostream &	operator<< (std::ostream &os, const FoeError &e)
	Streams the message, so `ASSERT_TRUE(r) << r.error()` and spdlog `{}` work unchanged.

FoeError	makeFoeError (FoeErrorKind kind, std::string_view op, uint16_t slave, std::string_view filename)
	Builds a fully-formed FoeError from a decoded `kind` plus call context. Keeps the message wording identical to the pre-promotion string ("<op> slave N '<file>' failed (<reason>)") so nothing downstream that logs or displays it changes shape.

void	to_json (nlohmann::json &j, const FoeErrorCode &e)
	Serialises a FoeErrorCode to JSON.

void	to_json (nlohmann::json &j, const MailboxErrorCode &e)
	Serialises a MailboxErrorCode to JSON.

constexpr std::string_view	mailboxErrorCodeDescription (uint16_t code)
	Returns the description of `code`, or an empty view if `code` is not a known mailbox error code (vendor-specific, or a stale/garbage read).

void	to_json (nlohmann::json &j, const ObjectDataTypeInfo &info)
	Serialises an ObjectDataTypeInfo to JSON.

constexpr std::string_view	objectDataTypeName (uint16_t code)
	Returns the symbolic name of `code`, or `"UNKNOWN"` if it is not in the table.

constexpr uint16_t	objectDataTypeBitSize (uint16_t code)
	Returns the declared bit width of `code`, or `0` if unknown / variable-length.

void	to_json (nlohmann::json &j, const SdoAbortCode &e)
	Serialises an SdoAbortCode to JSON.

constexpr std::string_view	sdoAbortCodeDescription (uint32_t code)
	Returns the description of `code`, or an empty view if `code` is not a known SDO abort code (vendor-specific, or a stale/garbage read).

std::optional< SiiCategoryType >	resolveSiiCategoryType (uint16_t value)
	Normalises a raw 16-bit category-type word into a `SiiCategoryType`.

std::expected< SlaveInformationInterface, std::string >	parseSii (std::span< const uint8_t > buffer)
	Parses a raw SII EEPROM image into a `SlaveInformationInterface`.

void	to_json (nlohmann::json &j, const SiiInfo &v)

void	to_json (nlohmann::json &j, const SiiCategoryGeneral &v)

void	to_json (nlohmann::json &j, const SiiCategorySyncManagerElement &v)

void	to_json (nlohmann::json &j, const SiiCategoryPdoEntryElement &v)

void	to_json (nlohmann::json &j, const SiiCategoryPdoElement &v)

void	to_json (nlohmann::json &j, const SiiCategoryDistributedClockElement &v)

void	to_json (nlohmann::json &j, const SiiCategorySection &v)

void	to_json (nlohmann::json &j, const SlaveInformationInterface &v)

Variables
constexpr auto	kAlStatusCodes
	Catalogue of AL Status Codes.

constexpr auto	kEscRegisters
	Catalogue of well-known ESC registers.

constexpr std::size_t	kMaxProcessImageBytes = 32768
	Maximum size in bytes of the combined process-data image (all outputs + all inputs).

constexpr auto	kFoeErrorCodes
	Catalogue of FoE error codes defined in ETG.1000.6 §5.8.5, Table 93.

constexpr auto	kMailboxErrorCodes
	Catalogue of CoE mailbox error codes.

constexpr auto	kObjectDataTypes
	Catalogue of ETG.1020 object dictionary data types.

constexpr auto	kSdoAbortCodes
	Catalogue of CoE SDO abort codes.

thread_local bool	sdoLogQuiet = false
	When true on the calling thread, a driver demotes its per-transfer SDO debug logs to `trace`. Set it via `ScopedQuietSdoLog` around background polling so a periodic poller does not flood the log, while direct (user-initiated) reads keep their `debug` trace.

Enumeration Type Documentation

◆ EtherCatState

enum class mm::comm::EtherCatState : uint16_t

strong

EtherCAT Application Layer state values.

Numeric values match the EtherCAT standard AL control/status register encoding (ETG.1000.6 §6.4.1).

Enumerator
Init	INIT — reset state, no communication.
PreOp	PRE-OPERATIONAL — mailbox communication active.
Boot	BOOT — firmware download mode.
SafeOp	SAFE-OPERATIONAL — inputs only; outputs ignored.
Op	OPERATIONAL — full PDO exchange.

◆ FoeErrorKind

enum class mm::comm::FoeErrorKind

strong

Specific File-over-EtherCAT failure kind. Transport-agnostic: a SOEM driver decodes it from a negated ec_err_type, a future SPoE driver from its own protocol codes.

Enumerator
NoResponse	The slave answered nothing (work counter 0 — timeout or not ready).
FileNotFound	Firmware recognises no such filename.
BufferTooSmall	The slave's buffer cannot hold the requested transfer.
PacketMismatch	Packet-number desync mid-transfer.
Protocol	Generic FoE-protocol error with no finer classification.

◆ ObjectDataType

enum class mm::comm::ObjectDataType : uint16_t

strong

CoE object dictionary data type codes.

Maps the 16-bit DataType field returned by ecx_readOE to its symbolic name. Base numbering follows SOEM (ec_type.h) / CiA 301 — what the wire actually reports — extended with the record/array/DEFTYPE codes from ETG.1020 v1.6.0 (§26 Base Data Types, Tables 119-121) plus ETG.5001 / ETG.5120 cross-references. Where SOEM and ETG.1020 disagree (notably 0x000B, see below) SOEM's numbering wins.

Enumerator
UNSPECIFIED	Undefined or unknown data type.
BOOLEAN	Boolean value (true or false), transported as a byte.
BYTE	8-bit unsigned integer.
WORD	16-bit unsigned integer.
DWORD	32-bit unsigned integer.
BIT1	1-bit field.
BIT2	2-bit field.
BIT3	3-bit field.
BIT4	4-bit field.
BIT5	5-bit field.
BIT6	6-bit field.
BIT7	7-bit field.
BIT8	8-bit field.
BIT9	9-bit field.
BIT10	10-bit field.
BIT11	11-bit field.
BIT12	12-bit field.
BIT13	13-bit field.
BIT14	14-bit field.
BIT15	15-bit field.
BIT16	16-bit field.
BITARR8	Array of 8 bits.
BITARR16	Array of 16 bits.
BITARR32	Array of 32 bits.
INTEGER8	8-bit signed integer.
INTEGER16	16-bit signed integer.
INTEGER24	24-bit signed integer.
INTEGER32	32-bit signed integer.
INTEGER40	40-bit signed integer.
INTEGER48	48-bit signed integer.
INTEGER56	56-bit signed integer.
INTEGER64	64-bit signed integer.
UNSIGNED8	8-bit unsigned integer.
UNSIGNED16	16-bit unsigned integer.
UNSIGNED24	24-bit unsigned integer.
UNSIGNED32	32-bit unsigned integer.
UNSIGNED40	40-bit unsigned integer.
UNSIGNED48	48-bit unsigned integer.
UNSIGNED56	56-bit unsigned integer.
UNSIGNED64	64-bit unsigned integer.
REAL32	32-bit IEEE 754 floating point.
REAL64	64-bit IEEE 754 floating point.
GUID	128-bit globally unique identifier.
VISIBLE_STRING	Null-terminated ASCII string.
OCTET_STRING	Variable-length byte array.
UNICODE_STRING	UCS-2 string (SOEM/CiA numbering; see note above).
WSTRING	UCS-2/wide string — ETG.1020's UNICODE_STRING code (cf. 0x000B).
TIME_OF_DAY	Time of day (ETG.1020).
TIME_DIFFERENCE	Time difference (ETG.1020).
DOMAIN	Application-specific domain (ETG.1020).
ARRAY_OF_INT	Sequence of INT (IEC 61131-3).
ARRAY_OF_SINT	Sequence of SINT.
ARRAY_OF_DINT	Sequence of DINT.
ARRAY_OF_UDINT	Sequence of UDINT.
ARRAY_OF_BITARR8	Sequence of BITARR8.
ARRAY_OF_BITARR16	Sequence of BITARR16.
ARRAY_OF_BITARR32	Sequence of BITARR32.
ARRAY_OF_USINT	Sequence of USINT.
ARRAY_OF_REAL	Sequence of REAL.
ARRAY_OF_LREAL	Sequence of LREAL.
PDO_MAPPING	PDO mapping (ETG.1000).
IDENTITY	Identity object (ETG.1000).
COMMAND_PAR	Command parameter (ETG.1000).
PDO_PARAMETER	PDO parameter (ETG.1020).
ENUM	Enumeration (ETG.1020).
SM_SYNCHRONISATION	Sync manager synchronisation (ETG.1000).
RECORD	Generic record structure.
BACKUP_PARAMETER	Backup parameter (ETG.1020).
MODULAR_DEVICE_PROFILE	Modular device profile (ETG.5001).
ERROR_SETTING	Error setting (ETG.1020).
DIAGNOSIS_HISTORY	Diagnosis history (ETG.1020).
EXTERNAL_SYNC_STATUS	External sync status (ETG.1020).
EXTERNAL_SYNC_SETTINGS	External sync settings (ETG.1020).
DEFTYPE_FSOEFRAME	FSoE frame (ETG.5120).
DEFTYPE_FSOECOMMPAR	FSoE communication parameters (ETG.5120).
UTYPE_START	Start of user-defined type range.
UTYPE_END	End of user-defined type range.

◆ Retry

enum class mm::comm::Retry

strong

Retry disposition of a failed operation: whether re-issuing the identical call could plausibly succeed. This is the one axis callers branch on uniformly — a firmware flasher retries Transient failures and aborts on Permanent ones — so it rides alongside the FoE-specific kind rather than being folded into it.

Enumerator
Transient	A fresh attempt may succeed (protocol desync, slave not yet ready after BOOT).
Permanent	The identical call will fail the same way (no such file, undersized buffer).

◆ SiiCategoryType

enum class mm::comm::SiiCategoryType : uint16_t

strong

Recognised SII category type identifiers (ETG.2010 Table 5).

ETG.2010 is the authoritative SII spec; its Table 5 supersedes ETG.1000.6 Table 19. The base IDs up to Dc (60) are common to both; the extended IDs (FmmuX, SyncUnit, Timeouts, Dictionary, Hardware, VendorInformation, Images, ApplicationSpecific) and the wider vendor/application ranges (see resolveSiiCategoryType) are ETG.2010's. Several spec ranges collapse to a single representative (e.g. all vendor-specific values map to VendorSpecific); the category-type word is a full Unsigned16 (no vendor-specific flag bit).

Enumerator
Nop
DeviceSpecific
Strings
DataTypes
General
Fmmu
SyncM
FmmuX
SyncUnit
TxPdo
RxPdo
Dc
Timeouts
Dictionary
Hardware
VendorInformation
Images
VendorSpecific
ApplicationSpecific
End

Function Documentation

◆ alHasError()

bool mm::comm::alHasError ( uint16_t alStatus )

inline

Returns whether the AL Status error indicator (bit 4 of register 0x0130) is set.

◆ alState()

EtherCatState mm::comm::alState ( uint16_t alStatus )

inline

Extracts the AL state (bits 3:0) from a raw AL Status register value (0x0130).

The single place the AL Status register layout is decoded: the low nibble is the current state, bit 4 is the error indicator (see alHasError). Callers compare the result against EtherCatState rather than re-masking the raw register.

◆ alStatusCodeName()

constexpr std::string_view mm::comm::alStatusCodeName ( uint16_t code )

constexpr

Returns the short name for code, or an empty view if code is not a known AL Status Code.

An empty result is the signal that a slave reported a code outside the catalogue — vendor-specific, or a stale/garbage read — which a caller should flag rather than present as a decoded error.

◆ enumerateNetworkAdapters()

std::vector< NetworkAdapter > mm::comm::enumerateNetworkAdapters ( )

Enumerates all network adapters visible to the OS.

Scans every network adapter and returns a fully populated NetworkAdapter per NIC, so callers can select a specific one by its hardware address rather than by its OS-assigned name, which can change across reboots or driver updates. All three representations are populated at enumeration time.

Platform behaviour

Linux — iterates the adapter list returned by SOEM's ec_find_adapters() and queries each interface with SIOCGIFHWADDR via a temporary SOCK_DGRAM socket. Adapters for which the ioctl call fails are silently skipped.
macOS — reads link-layer (AF_LINK) addresses from getifaddrs().
Windows — calls GetAdaptersAddresses() (IPHLPAPI) to enumerate adapters. Interface names are formatted as WinPcap/Npcap NPF paths: "\\Device\\NPF_<AdapterName>".

MAC address format — macLinux is uppercase colon-separated hex octets, e.g. "AA:BB:CC:DD:EE:FF"; macWindows is the dash-separated equivalent. Both are consistent across platforms.

Returns an empty vector if adapter enumeration fails (e.g. insufficient privileges or no adapters present).

Note: Call once at startup to resolve a configured MAC address to the interface name required by a fieldbus driver. Do not call in a tight loop — OS adapter enumeration is slow.

◆ findAlStatusCode()

constexpr const AlStatusCode * mm::comm::findAlStatusCode ( uint16_t code )

constexpr

Looks up code in kAlStatusCodes, or returns nullptr if it is not catalogued.

◆ foeReason()

std::string_view mm::comm::foeReason ( FoeErrorKind kind )

inline

Short human-readable reason for a FoE kind (no surrounding punctuation).

◆ foeRetry()

Retry mm::comm::foeRetry ( FoeErrorKind kind )

inline

Retry disposition implied by a FoE kind. A missing file or an undersized buffer is a fixed condition that will recur identically; a desync or a not-yet-ready slave (the BOOT bootloader warm-up path) is worth another attempt.

◆ isAlStatusCodeTerminal()

constexpr bool mm::comm::isAlStatusCodeTerminal ( uint16_t code )

constexpr

Returns true if code indicates a state-transition failure that cannot be resolved by retrying the same writestate.

A terminal code means the polling loop in FieldbusDriver::transitionToState should abandon the slave immediately rather than waiting for the timeout — the master must change something (re-init, reflash, power cycle) before another transition attempt can succeed. Unknown codes are treated as non-terminal.

◆ isMacAddress()

bool mm::comm::isMacAddress ( const std::string & s )

Returns true if s is a MAC address in either Linux (:) or Windows (-) separator format.

Accepts exactly 17 characters: six pairs of hex digits separated by consistent colon or dash delimiters, e.g. "AA:BB:CC:DD:EE:FF" or "aa-bb-cc-dd-ee-ff". Mixed separators are rejected.

Parameters

s	String to test.

Returns: true when s matches the pattern; false otherwise.

◆ mailboxErrorCodeDescription()

constexpr std::string_view mm::comm::mailboxErrorCodeDescription ( uint16_t code )

constexpr

Returns the description of code, or an empty view if code is not a known mailbox error code (vendor-specific, or a stale/garbage read).

◆ makeFoeError()

FoeError mm::comm::makeFoeError	(	FoeErrorKind	kind,
		std::string_view	op,
		uint16_t	slave,
		std::string_view	filename
	)

inline

Builds a fully-formed FoeError from a decoded kind plus call context. Keeps the message wording identical to the pre-promotion string ("<op> slave N '<file>' failed (<reason>)") so nothing downstream that logs or displays it changes shape.

◆ normalizeMac()

std::string mm::comm::normalizeMac	(	const std::string &	raw,
		char	sep
	)

Normalises a MAC address string to uppercase with the given separator.

Extracts the six hex-octet pairs from raw (which must have passed isMacAddress()) and rebuilds the string in uppercase with sep as the field delimiter.

Parameters

raw	Source MAC string (colon- or dash-separated, any case).
sep	Output separator character, typically `'`:' or `'-'`.

Returns: Normalised MAC string of the form "XX<sep>XX<sep>…<sep>XX".

Precondition: isMacAddress(raw) == true

◆ objectDataTypeBitSize()

constexpr uint16_t mm::comm::objectDataTypeBitSize ( uint16_t code )

constexpr

Returns the declared bit width of code, or 0 if unknown / variable-length.

◆ objectDataTypeName()

constexpr std::string_view mm::comm::objectDataTypeName ( uint16_t code )

constexpr

Returns the symbolic name of code, or "UNKNOWN" if it is not in the table.

◆ operator<<()

std::ostream & mm::comm::operator<<	(	std::ostream &	os,
		const FoeError &	e
	)

inline

Streams the message, so ASSERT_TRUE(r) << r.error() and spdlog {} work unchanged.

◆ parseSii()

std::expected< SlaveInformationInterface, std::string > mm::comm::parseSii ( std::span< const uint8_t > buffer )

Parses a raw SII EEPROM image into a SlaveInformationInterface.

Decodes the fixed 128-byte header, then walks the category section starting at offset 128 (each category is a 16-bit type, a 16-bit word-size, then wordSize × 2 payload bytes), dispatching recognised categories to their decoders and stopping at the End (0xFFFF) or Nop marker. Unrecognised categories are skipped; multiple PDO categories accumulate. The walk is bounds-checked: a category claiming more bytes than remain is clamped, never read past the end.

Parameters

buffer Raw SII bytes (at least 128 for a valid header).

Returns: The parsed structure, or an error string if buffer is shorter than the fixed header.

◆ resolveNetworkAdapter()

std::expected< NetworkAdapter, std::string > mm::comm::resolveNetworkAdapter ( const std::string & input )

Resolves a network adapter specifier to a fully populated NetworkAdapter.

input may be any of the three accepted forms:

Linux MAC address: "AA:BB:CC:DD:EE:FF"
Windows MAC address: "AA-BB-CC-DD-EE-FF"
OS interface name: "eth0", "\\Device\\NPF_{GUID}"

Calls enumerateNetworkAdapters() once to resolve the form that was not supplied.

Parameters

input User-supplied adapter specifier string.

Returns: Fully populated NetworkAdapter, or an error string if the adapter cannot be found in the OS adapter map.

◆ resolveSiiCategoryType()

std::optional< SiiCategoryType > mm::comm::resolveSiiCategoryType ( uint16_t value )

Normalises a raw 16-bit category-type word into a SiiCategoryType.

Range-based values are folded to a single representative (DeviceSpecific for 0x0001–0x0009, VendorSpecific for 0x0800–0x1FFF and 0x3000–0xFFFE, ApplicationSpecific for 0x2000–0x2FFF); the original numeric value is not preserved. Fixed IDs (Strings, General, …) and the End marker resolve directly. Returns std::nullopt for unrecognised values, which the caller skips.

◆ sdoAbortCodeDescription()

constexpr std::string_view mm::comm::sdoAbortCodeDescription ( uint32_t code )

constexpr

Returns the description of code, or an empty view if code is not a known SDO abort code (vendor-specific, or a stale/garbage read).

◆ to_json() [1/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const AlStatusCode &	c
	)

Serialises an AlStatusCode to JSON.

Produces an object with keys code, name, description, terminal. Participates in nlohmann ADL so that nlohmann::json(kAlStatusCodes) works automatically.

Parameters

j	Output JSON value.
c	AL Status Code entry to serialise.

◆ to_json() [2/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const EscRegister &	r
	)

Serialises an EscRegister to JSON.

Produces an object with keys address, length, name, description. Participates in nlohmann ADL so that nlohmann::json(kEscRegisters) works automatically.

Parameters

j	Output JSON value.
r	Register entry to serialise.

◆ to_json() [3/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const FoeErrorCode &	e
	)

Serialises a FoeErrorCode to JSON.

Produces an object with keys code, name, description. Participates in nlohmann ADL so that nlohmann::json(kFoeErrorCodes) works automatically.

Parameters

j	Output JSON value.
e	FoE error code entry to serialise.

◆ to_json() [4/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const MailboxErrorCode &	e
	)

Serialises a MailboxErrorCode to JSON.

Produces an object with keys code, name, description. Participates in nlohmann ADL so that nlohmann::json(kMailboxErrorCodes) works automatically.

◆ to_json() [5/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const NetworkAdapter &	a
	)

Serialises a NetworkAdapter to JSON.

Produces an object with keys macLinux, macWindows, name. Participates in nlohmann ADL so that nlohmann::json(adapters) serialises a std::vector<NetworkAdapter> automatically.

Parameters

j	Output JSON value.
a	Adapter to serialise.

◆ to_json() [6/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const ObjectDataTypeInfo &	info
	)

Serialises an ObjectDataTypeInfo to JSON.

Produces an object with keys code, name, bitSize. Participates in nlohmann ADL so that nlohmann::json(kObjectDataTypes) works automatically.

◆ to_json() [7/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SdoAbortCode &	e
	)

Serialises an SdoAbortCode to JSON.

Produces an object with keys code and description. Participates in nlohmann ADL so that nlohmann::json(kSdoAbortCodes) works automatically.

◆ to_json() [8/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SiiCategoryDistributedClockElement &	v
	)

◆ to_json() [9/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SiiCategoryGeneral &	v
	)

◆ to_json() [10/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SiiCategoryPdoElement &	v
	)

◆ to_json() [11/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SiiCategoryPdoEntryElement &	v
	)

◆ to_json() [12/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SiiCategorySection &	v
	)

◆ to_json() [13/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SiiCategorySyncManagerElement &	v
	)

◆ to_json() [14/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SiiInfo &	v
	)

◆ to_json() [15/15]

void mm::comm::to_json	(	nlohmann::json &	j,
		const SlaveInformationInterface &	v
	)

◆ toString()

std::string_view mm::comm::toString ( EtherCatState state )

inline

Human-readable name of an AL state, for log and error messages.

◆ workingCounterContribution()

int mm::comm::workingCounterContribution	(	EtherCatState	state,
		bool	hasOutputs,
		bool	hasInputs
	)

inline

Working-counter contribution of one slave for a given AL state and PDO presence.

EtherCAT increments the working counter per successful datagram access: a slave exchanging outputs contributes 2 (the process-data LRW both reads and writes its output region) and inputs contribute 1. Process data flows only in SAFE-OP (inputs only) and OP (outputs + inputs); below that a slave does not contribute. Summed across the bus this is the WKC a (possibly partially operational) bus is expected to produce — the figure a health check compares the live working counter against. The protocol rule lives here, with the other AL vocabulary, rather than in the transport-agnostic node layer.

Parameters

state	Current AL state of the slave.
hasOutputs	Whether the slave has any mapped output (RxPDO) bits.
hasInputs	Whether the slave has any mapped input (TxPDO) bits.

Variable Documentation

◆ kAlStatusCodes

constexpr auto mm::comm::kAlStatusCodes

inlineconstexpr

Catalogue of AL Status Codes.

The first block is a faithful transcription of ETG.1000.6 V1.0.4 Table 11 (the latest released revision). The second block adds codes that are not in that table but are reported by real slaves and carried by SOEM's own ec_ALstatuscodelist — most relevantly the firmware/EEPROM/FMMU failures raised during BOOT/FoE flashing and re-mapping. They earn their place here because isAlStatusCodeTerminal must classify them so FieldbusDriver::transitionToState fails fast instead of spinning to timeout.

◆ kEscRegisters

constexpr auto mm::comm::kEscRegisters

inlineconstexpr

Catalogue of well-known ESC registers.

Addresses and sizes follow the Beckhoff EtherCAT ESC datasheet (Section II) and ETG.1000.4. FMMU and SyncManager entries list the full block for the first instance; subsequent instances follow at fixed strides (FMMU: 16 bytes, SM: 8 bytes).

◆ kFoeErrorCodes

constexpr auto mm::comm::kFoeErrorCodes

inlineconstexpr

Initial value:

= std::to_array<FoeErrorCode>({
    {0x00000000, "Undefined", "Unspecified or vendor-specific FoE error"},
    {0x00008000, "Not defined", "General FoE error with no further classification"},
    {0x00008001, "Not found", "The requested file was not found on the slave"},
    {0x00008002, "Access denied", "Access to the requested file is denied"},
    {0x00008003, "Disk full", "The slave has insufficient storage to complete the transfer"},
    {0x00008004, "Illegal", "Illegal FoE operation"},
    {0x00008005, "Packet number wrong",
     "Received a data packet with an unexpected sequence number"},  
    {0x00008006, "Already exists", "The file already exists on the slave"},
    {0x00008007, "No user", "No user is logged in; authentication required"},
    {0x00008008, "Bootstrap only", "This operation is only available in Bootstrap state"},
    {0x00008009, "Not Bootstrap", "This operation is not available in Bootstrap state"},
    {0x0000800A, "No rights", "Insufficient rights to perform the requested operation"},
    {0x0000800B, "Program error", "A program error occurred on the slave"},
})

Catalogue of FoE error codes defined in ETG.1000.6 §5.8.5, Table 93.

Codes in the 0x8000 range are the standard EtherCAT FoE error codes. The 0x00000000 entry is a catch-all for unspecified or vendor-specific errors, which otherwise fall outside this range.

◆ kMailboxErrorCodes

constexpr auto mm::comm::kMailboxErrorCodes

inlineconstexpr

Initial value:

= std::to_array<MailboxErrorCode>({
    {0x0001, "MBXERR_SYNTAX", "Syntax of the 6-octet mailbox header is wrong"},
    {0x0002, "MBXERR_UNSUPPORTEDPROTOCOL", "The mailbox protocol is not supported"},
    {0x0003, "MBXERR_INVALIDCHANNEL",
     "Channel field contains a wrong value (a slave may ignore it)"},
    {0x0004, "MBXERR_SERVICENOTSUPPORTED", "The service in the mailbox protocol is not supported"},
    {0x0005, "MBXERR_INVALIDHEADER",
     "The mailbox protocol header is wrong (excluding the 6-octet mailbox header)"},
    {0x0006, "MBXERR_SIZETOOSHORT", "Length of received mailbox data is too short"},
    {0x0007, "MBXERR_NOMOREMEMORY",
     "Mailbox protocol cannot be processed because of limited resources"},
    {0x0008, "MBXERR_INVALIDSIZE", "The length of data is inconsistent"},
    {0x0009, "MBXERR_SERVICEINWORK", "Mailbox service already in use"},
})

Catalogue of CoE mailbox error codes.

A faithful transcription of ETG.1000.4 Table 30 ("Error Reply Service Data"). A slave returns one of these in a mailbox error reply when the mailbox layer (below any specific protocol like CoE/FoE) rejects a transfer. SOEM carries the same set in its ec_mbxerrorlist but stops at 0x0008 — this table also lists the spec's 0x0009. The FieldbusDriver surfaces mailbox errors as text embedding the raw 0x... code, so this table lets a caller decode it to a reason.

◆ kMaxProcessImageBytes

constexpr std::size_t mm::comm::kMaxProcessImageBytes = 32768

inlineconstexpr

Maximum size in bytes of the combined process-data image (all outputs + all inputs).

The whole bus is exchanged as one IOmap laid out as [all outputs | all inputs]; on SOEM that is a single buffer of this size, so it is the combined image (outputs + inputs) that both buildProcessImage and configureProcessData() bound against this cap. Each per-direction RT ProcessBuffer scratch is also this size — one direction alone may use the whole budget when the other is empty. A SOMANET drive maps ~100 bytes across both directions, so 50 drives total ~5 KB — under 15% of this cap. This is not a practical limit: on 100 Mbit EtherCAT an image approaching 32 KB already forces a many-millisecond cycle, so the cap sits well clear of any realistic configuration.

◆ kObjectDataTypes

constexpr auto mm::comm::kObjectDataTypes

inlineconstexpr

Catalogue of ETG.1020 object dictionary data types.

◆ kSdoAbortCodes

constexpr auto mm::comm::kSdoAbortCodes

inlineconstexpr

Catalogue of CoE SDO abort codes.

A faithful transcription of ETG.1000.6 §5.6.2.7.2, Table 41 (which reproduces the CANopen CiA 301 SDO abort transfer codes). A slave returns one of these in the Abort SDO Transfer request when a mailbox SDO read/write fails. SOEM carries the identical set in its ec_sdoerrorlist; the FieldbusDriver surfaces SDO failures only as text, embedding the raw 0x... code, so this table lets a caller decode that code to a reason.

◆ sdoLogQuiet

thread_local bool mm::comm::sdoLogQuiet = false

inline

When true on the calling thread, a driver demotes its per-transfer SDO debug logs to trace. Set it via ScopedQuietSdoLog around background polling so a periodic poller does not flood the log, while direct (user-initiated) reads keep their debug trace.

Thread-local (the comment, not the name, carries that): the flag is read on the same thread that issues the transfer — SDO reads run synchronously on the caller's thread — so a scope set by the caller reliably covers the driver's logging. Inline so the one instance is shared across translation units.

Namespaces

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ EtherCatState

◆ FoeErrorKind

◆ ObjectDataType

◆ Retry

◆ SiiCategoryType

Function Documentation

◆ alHasError()

◆ alState()

◆ alStatusCodeName()

◆ enumerateNetworkAdapters()

◆ findAlStatusCode()

◆ foeReason()

◆ foeRetry()

◆ isAlStatusCodeTerminal()

◆ isMacAddress()

◆ mailboxErrorCodeDescription()

◆ makeFoeError()

◆ normalizeMac()

◆ objectDataTypeBitSize()

◆ objectDataTypeName()

◆ operator<<()

◆ parseSii()

◆ resolveNetworkAdapter()

◆ resolveSiiCategoryType()

◆ sdoAbortCodeDescription()

◆ to_json() [1/15]

◆ to_json() [2/15]

◆ to_json() [3/15]

◆ to_json() [4/15]

◆ to_json() [5/15]

◆ to_json() [6/15]

◆ to_json() [7/15]

◆ to_json() [8/15]

◆ to_json() [9/15]

◆ to_json() [10/15]

◆ to_json() [11/15]

◆ to_json() [12/15]

◆ to_json() [13/15]

◆ to_json() [14/15]

◆ to_json() [15/15]

◆ toString()

◆ workingCounterContribution()

Variable Documentation

◆ kAlStatusCodes

◆ kEscRegisters

◆ kFoeErrorCodes

◆ kMailboxErrorCodes

◆ kMaxProcessImageBytes

◆ kObjectDataTypes

◆ kSdoAbortCodes

◆ sdoLogQuiet