mm::comm::soem::SoemFieldbusDriver Class Reference

SOEM-backed EtherCAT fieldbus driver. More...

#include <soem_fieldbus_driver.h>

Inheritance diagram for mm::comm::soem::SoemFieldbusDriver:

Collaboration diagram for mm::comm::soem::SoemFieldbusDriver:

Public Member Functions
	SoemFieldbusDriver (SoemFieldbusDriverConfig config)
	Constructs the driver from its SOEM-specific configuration.
	~SoemFieldbusDriver () override
	Closes the NIC if init() succeeded.
	SoemFieldbusDriver (const SoemFieldbusDriver &)=delete
SoemFieldbusDriver &	operator= (const SoemFieldbusDriver &)=delete
std::expected< void, std::string >	init () override
	Opens the NIC and initialises the SOEM master context.
std::expected< int, std::string >	scan () override
	Scans the bus for slaves and configures their sync managers and FMMUs.
SlaveInfo	slaveInfo (uint16_t position) const override
	Returns the immutable identity fields for the slave at position.
uint16_t	slaveState (uint16_t position) const override
	Returns the last-known AL status for a slave without any bus I/O.
std::expected< void, std::string >	configureProcessData () override
	Maps the process data and lays out the IOmap (one-time, control-plane).
PdoLayout	processDataLayout () override
	Returns the current process-data layout established by configureProcessData.
std::vector< SlaveConfig >	busConfig () const override
	Returns the static ESC configuration of every slave, as last programmed by the master.
int	exchangeProcessData (std::span< const uint8_t > outputs, std::span< uint8_t > inputs) override
	Copies outputs into the IOmap, sends and receives, copies inputs back out.
void	stop () override
	Closes the NIC and releases all driver resources.
std::expected< std::vector< FieldbusDriver::SlaveStateRaw >, std::string >	readStates (const std::vector< uint16_t > &positions) override
	Reads the current AL Status for each slave in positions.
std::expected< std::vector< SlaveDiagnostics >, std::string >	readDiagnostics (const std::vector< uint16_t > &positions) override
	Reads live link-quality and watchdog diagnostics for each slave in positions.
std::expected< std::vector< DcSyncDiagnostics >, std::string >	readDcSync (const std::vector< uint16_t > &positions) override
	Reads live distributed-clock synchronisation status for each slave in positions.
std::expected< std::vector< uint8_t >, std::string >	readSdo (uint16_t slavePosition, uint16_t index, uint8_t subindex) override
	Reads an object dictionary entry via CoE SDO upload.
std::expected< std::vector< uint8_t >, std::string >	readSdoComplete (uint16_t slavePosition, uint16_t index) override
	Reads an entire object in one CoE SDO upload using Complete Access.
std::expected< void, std::string >	writeSdo (uint16_t slavePosition, uint16_t index, uint8_t subindex, std::span< const uint8_t > data) override
	Writes an object dictionary entry to a slave (CoE SDO download).
std::expected< std::vector< OdEntry >, std::string >	readObjectDictionary (uint16_t slavePosition) override
	Enumerates the entire CoE object dictionary of a slave via SDO Info.
std::expected< std::vector< uint8_t >, std::string >	readSii (uint16_t slavePosition) override
	Reads the raw Slave Information Interface (SII / EEPROM) image of a slave.
std::expected< void, std::string >	writeSii (uint16_t slavePosition, std::span< const uint8_t > data) override
	Writes a raw SII (EEPROM) image to a slave.
std::expected< std::vector< uint8_t >, std::string >	readFile (uint16_t slavePosition, const std::string &filename) override
	Reads a file from the slave via File over EtherCAT (FoE).
std::expected< void, std::string >	writeFile (uint16_t slavePosition, const std::string &filename, std::span< const uint8_t > data) override
	Writes a file to the slave via File over EtherCAT (FoE).
std::expected< void, std::string >	readRegister (uint16_t slavePosition, uint16_t address, std::span< uint8_t > data) override
	Reads bytes from an ESC register via FPRD.
std::expected< void, std::string >	writeRegister (uint16_t slavePosition, uint16_t address, std::span< const uint8_t > data) override
	Writes bytes to an ESC register via FPWR.
std::expected< ProcessDataWatchdogConfig, std::string >	processDataWatchdog (uint16_t slavePosition) override
	Reads the process-data (sync-manager) watchdog configuration of one slave.
std::expected< ProcessDataWatchdogConfig, std::string >	setProcessDataWatchdog (uint16_t slavePosition, std::chrono::nanoseconds timeout) override
	Sets the process-data (sync-manager) watchdog timeout of one slave.
int	slaveCount () const
	Returns the number of discovered slaves, or 0 before discovery.
void	transitionToState (const std::vector< uint16_t > &positions, std::optional< EtherCatState > requiredState, EtherCatState targetState, 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) override
	Commands a set of devices to targetState and blocks until all arrive or timeout elapses.
Public Member Functions inherited from mm::comm::FieldbusDriver
virtual	~FieldbusDriver ()=default

Additional Inherited Members
Protected Attributes inherited from mm::comm::FieldbusDriver
std::mutex	controlPlaneMutex_

Detailed Description

SOEM-backed EtherCAT fieldbus driver.

Owns one ecx_contextt master context and its PDO I/O map. The composition root (main.cc) creates exactly one instance and injects it into DeviceManager via DeviceManager::init; GameLoop does not reference it.

Note

As with the FieldbusDriver interface, the slave-indexed methods trust slavePosition and index SOEM's fixed-size slavelist without bounds-checking — pass only valid, discovered positions (1..slaveCount). DeviceManager guarantees this; a direct caller must validate positions itself.

Calling any method before a successful init() (or after stop()) is safe: the value-returning accessors report empty/zero, and the std::expected ones fail with "no driver — call init() first" instead of dereferencing a null context. init() is the only method that establishes the context.

Constructor & Destructor Documentation

SoemFieldbusDriver() [1/2]

mm::comm::soem::SoemFieldbusDriver::SoemFieldbusDriver ( SoemFieldbusDriverConfig  config )

explicit

Constructs the driver from its SOEM-specific configuration.

Parameters

config

Network interface plus SOEM tuning knobs (see SoemFieldbusDriverConfig).

~SoemFieldbusDriver()

mm::comm::soem::SoemFieldbusDriver::~SoemFieldbusDriver ( )

override

Closes the NIC if init() succeeded.

SoemFieldbusDriver() [2/2]

mm::comm::soem::SoemFieldbusDriver::SoemFieldbusDriver ( const SoemFieldbusDriver &  )

delete

Member Function Documentation

busConfig()

std::vector< SlaveConfig > mm::comm::soem::SoemFieldbusDriver::busConfig ( ) const

overridevirtual

Returns the static ESC configuration of every slave, as last programmed by the master.

A diagnostic snapshot (Sync Managers, FMMUs, mailbox, distributed clock, addresses) of what the master programmed into each slave's EtherCAT Slave Controller. Read from cached state — no bus I/O — so it mirrors what the master believes it programmed, not a live ESC read. It is built up across control-plane operations, not one: scan() sets identity, addresses, the mailbox SMs and DC capability; configureProcessData() adds the process-data SMs, FMMUs and DC timing (and rebuilds the FMMUs on a re-map); and a BOOT state transition transiently reprograms the mailbox SMs (reset on the return to PRE-OP). A meaningful snapshot therefore needs scan(), plus configureProcessData() for the process-data SMs/FMMUs. Optional capability: the default returns an empty vector for transports without an ESC (e.g. SPoE); the SOEM driver overrides it.

Returns

Per-slave configuration in bus order, or an empty vector if unsupported / unscanned.

Reimplemented from mm::comm::FieldbusDriver.

configureProcessData()

std::expected< void, std::string > mm::comm::soem::SoemFieldbusDriver::configureProcessData ( )

overridevirtual

Maps the process data and lays out the IOmap (one-time, control-plane).

Reads each slave's active PDO assignment, computes the process image, programs the FMMUs, and fills the driver-owned IOmap. Slaves must be in PRE-OP (mailbox active) so the assignment can be read. Run again to re-map after the slave set changes (e.g. a device returning from a firmware download) — the previous PdoLayout is invalidated. Serialised with other control-plane operations via the socket mutex. This is the one operation that must not overlap exchangeProcessData — it rewrites the IOmap the RT cycle reads — and, since the lock-free PDO path does not take the socket mutex, that exclusion is enforced by the caller (DeviceManager drains exchange and unpublishes the process image before re-mapping), not by the mutex.

Returns

Void on success, or an error string if no driver is initialised, no process data is mapped, or the image exceeds kMaxProcessImageBytes.

Implements mm::comm::FieldbusDriver.

exchangeProcessData()

int mm::comm::soem::SoemFieldbusDriver::exchangeProcessData ( std::span< const uint8_t >  outputs, std::span< uint8_t >  inputs  )

overridevirtual

Copies outputs into the IOmap, sends and receives, copies inputs back out.

Called once per GameLoop cycle. Must not be called before configureProcessData() or after stop().

Parameters

outputs	Output image to send; size must equal PdoLayout::outputBytes.
inputs	Buffer receiving the input image; size must equal PdoLayout::inputBytes.

Returns

The transaction working counter, or 0 if not initialised.

Implements mm::comm::FieldbusDriver.

init()

std::expected< void, std::string > mm::comm::soem::SoemFieldbusDriver::init ( )

overridevirtual

Opens the NIC and initialises the SOEM master context.

Must be called before any other driver method. Device discovery and state transitions are performed by separate functions after a successful init.

Returns

Void on success, or an error string if the interface cannot be opened.

Implements mm::comm::FieldbusDriver.

operator=()

SoemFieldbusDriver & mm::comm::soem::SoemFieldbusDriver::operator= ( const SoemFieldbusDriver &  )

delete

processDataLayout()

PdoLayout mm::comm::soem::SoemFieldbusDriver::processDataLayout ( )

overridevirtual

Returns the current process-data layout established by configureProcessData.

The returned spans alias the driver-owned IOmap and remain valid until the next configureProcessData or stop. Before a successful configureProcessData the layout is empty (zero-sized spans, no slaves).

Implements mm::comm::FieldbusDriver.

processDataWatchdog()

std::expected< ProcessDataWatchdogConfig, std::string > mm::comm::soem::SoemFieldbusDriver::processDataWatchdog ( uint16_t  slavePosition )

overridevirtual

Reads the process-data (sync-manager) watchdog configuration of one slave.

FPRD-reads the watchdog divider (0x0400), process-data watchdog time (0x0420), and process-data watchdog status (0x0440) ESC registers, decoding the timeout as ticks × 40 ns × (divider + 2) plus the live running/expired status. A zero time register means the watchdog is disabled. Unlike readDiagnostics (which returns the expiration counter), this returns the configured timeout and its current run state. Serialised via the socket mutex; runs concurrently with the lock-free exchangeProcessData.

Optional capability: the default returns an error for transports without an ESC (e.g. SPoE); the SOEM driver overrides it.

Parameters

slavePosition

1-based slave position on the bus.

Returns

The decoded watchdog configuration, or an error string if the transport has no ESC or a register read fails.

Reimplemented from mm::comm::FieldbusDriver.

readDcSync()

std::expected< std::vector< DcSyncDiagnostics >, std::string > mm::comm::soem::SoemFieldbusDriver::readDcSync ( const std::vector< uint16_t > &  positions )

overridevirtual

Reads live distributed-clock synchronisation status for each slave in positions.

Performs FPRD reads of the DC system-time delay (0x0928) and system-time difference (0x092C) registers for every DC-capable slave and decodes the signed deviation of each slave's local clock from the bus reference. The reference clock is the first DC-capable slave; its own difference is zero. Values are meaningful only while the bus is exchanging process data in SAFE-OP/OP (the reference time is distributed in the cyclic frame), and the difference converges toward zero as the slaves' drift-compensation loops settle — poll this and watch for one that stays large or grows. Serialised with other control-plane operations via the socket mutex; runs concurrently with the lock-free exchangeProcessData and never blocks the RT cycle.

Optional capability: the default returns an error for transports without an ESC (e.g. SPoE); the SOEM driver overrides it.

Parameters

positions

1-based slave positions to read.

Returns

Decoded DC sync status per position in the same order as positions, or an error string if the transport has no ESC or a register read fails.

Reimplemented from mm::comm::FieldbusDriver.

readDiagnostics()

std::expected< std::vector< SlaveDiagnostics >, std::string > mm::comm::soem::SoemFieldbusDriver::readDiagnostics ( const std::vector< uint16_t > &  positions )

overridevirtual

Reads live link-quality and watchdog diagnostics for each slave in positions.

Performs FPRD reads of the DL Status (0x0110), error-counter (0x0300–0x0313), and watchdog (0x0440–0x0443) ESC register blocks for every requested slave and returns the decoded counters. The counters are monotonic since the last clear (power cycle / explicit write), so callers compare successive snapshots and alert on a rising delta — a single non-zero value is historical, a climbing one is an active fault. Serialised with other control-plane operations via the socket mutex; runs concurrently with the lock-free exchangeProcessData and never blocks the RT cycle.

Optional capability: the default returns an error for transports without an ESC (e.g. SPoE); the SOEM driver overrides it.

Parameters

positions

1-based slave positions to read.

Returns

Decoded diagnostics per position in the same order as positions, or an error string if the transport has no ESC or a register read fails.

Reimplemented from mm::comm::FieldbusDriver.

readFile()

std::expected< std::vector< uint8_t >, std::string > mm::comm::soem::SoemFieldbusDriver::readFile ( uint16_t  slavePosition, const std::string &  filename  )

overridevirtual

Reads a file from the slave via File over EtherCAT (FoE).

Sends an FoE read request for filename and collects all data packets from the slave. FoE is available in Boot, Pre-Op, Safe-Op, and Op states (device-dependent); the caller is responsible for ensuring the device is in a suitable state. Called from HTTP handler threads; serialised with other control-plane operations via the socket mutex, and runs concurrently with the lock-free exchangeProcessData.

Parameters

slavePosition	1-based slave position on the bus.
filename	FoE filename as recognised by the slave firmware.

Returns

File bytes on success, or an error string if the transfer fails.

Implements mm::comm::FieldbusDriver.

readObjectDictionary()

std::expected< std::vector< OdEntry >, std::string > mm::comm::soem::SoemFieldbusDriver::readObjectDictionary ( uint16_t  slavePosition )

overridevirtual

Enumerates the entire CoE object dictionary of a slave via SDO Info.

Performs the "Get Object List" → "Get Object Description" → "Get Entry Description" sequence (ETG.1000.6 §5.6) and returns one OdEntry per (index, subindex) pair. The slave must be in PRE-OP, SAFE-OP, or OP — i.e. mailbox communication enabled. Many transfers are issued; expect the call to take seconds on a fully populated drive.

Slaves that do not implement the SDO Info service return an error.

Parameters

slavePosition

1-based slave position on the bus.

Returns

All OD entries on success, or an error string if any phase of the enumeration fails after the driver's internal retries.

Implements mm::comm::FieldbusDriver.

readRegister()

std::expected< void, std::string > mm::comm::soem::SoemFieldbusDriver::readRegister ( uint16_t  slavePosition, uint16_t  address, std::span< uint8_t >  data  )

overridevirtual

Reads bytes from an ESC register via FPRD.

Parameters

slavePosition	1-based slave position on the bus.
address	ESC register address.
data	Output buffer; its size determines how many bytes are read.

Returns

Void on success, or an error string if the working counter is not 1.

Implements mm::comm::FieldbusDriver.

readSdo()

std::expected< std::vector< uint8_t >, std::string > mm::comm::soem::SoemFieldbusDriver::readSdo ( uint16_t  slavePosition, uint16_t  index, uint8_t  subindex  )

overridevirtual

Reads an object dictionary entry via CoE SDO upload.

Allocates up to 4096 bytes, performs a mailbox SDO upload, and returns the exact bytes the slave sent (resized to the actual transfer size). Called from HTTP handler threads; serialised with other control-plane operations via the socket mutex, but runs concurrently with the lock-free exchangeProcessData — a slow SDO never blocks the RT cycle (the reason the PDO path stays out of the mutex).

Returns an owning std::vector, not a std::span, deliberately: the bytes are produced by this call and their ownership must transfer to the caller, which a non-owning view cannot do (a span would have to alias driver state that the next call clobbers, or storage nothing frees). Nor can the caller lend a sized buffer the way readRegister does — an SDO object's size is unknown until the transfer completes (expedited vs. segmented), which is exactly why the implementation over-allocates and resizes. The return is moved out, so this costs no copy. (std::span is used elsewhere in this interface only for borrowed inputs — e.g. writeSdo / exchangeProcessData — never to hand back freshly produced data.)

Parameters

slavePosition	1-based slave position on the bus.
index	CoE object index.
subindex	CoE object subindex.

Returns

The bytes transferred on success, or an error string if the mailbox transfer fails.

Implements mm::comm::FieldbusDriver.

readSdoComplete()

std::expected< std::vector< uint8_t >, std::string > mm::comm::soem::SoemFieldbusDriver::readSdoComplete ( uint16_t  slavePosition, uint16_t  index  )

overridevirtual

Reads an entire object in one CoE SDO upload using Complete Access.

Uploads every subindex of index in a single mailbox transfer (SDO command with the complete-access bit set, starting at subindex 0), replacing one readSdo per subindex. The returned blob is what the slave sends: subindex 0 as a 16-bit value (1 data byte + 1 alignment pad), then subindices 1..N concatenated at their native bit lengths. The caller slices it back into per-subindex values from the object's known entry layout.

Complete access is optional in CoE — a slave, or an individual object, that does not support it answers with an SDO abort. Callers must therefore treat any error as "fall back to per-subindex @c readSdo", not as a hard failure. The default implementation reports it unsupported; drivers backed by a real CoE mailbox override this.

Parameters

slavePosition	1-based slave position on the bus.
index	CoE object index.

Returns

The raw complete-access blob on success, or an error string (including when the driver or the slave does not support complete access).

Reimplemented from mm::comm::FieldbusDriver.

readSii()

std::expected< std::vector< uint8_t >, std::string > mm::comm::soem::SoemFieldbusDriver::readSii ( uint16_t  slavePosition )

overridevirtual

Reads the raw Slave Information Interface (SII / EEPROM) image of a slave.

Reads the slave's EEPROM through the ESC's EEPROM-control registers and returns the raw byte image — a fixed 128-byte header followed by the self-describing category section (strings, general info, FMMU/Sync-Manager and PDO defaults, distributed-clock settings). Decode it with mm::comm::parseSii. EEPROM access is a control-plane operation serialised on the socket mutex per transaction (it runs concurrently with the lock-free exchangeProcessData); the real constraint is slave state — it is most reliable while the slave is in INIT or PRE-OP. The driver hands EEPROM control back to the slave's PDI before returning.

Optional capability: the default returns an error for transports without an ESC EEPROM (e.g. SPoE); the SOEM driver overrides it.

Parameters

slavePosition

1-based slave position on the bus.

Returns

The raw SII image on success, or an error string if the transport has no EEPROM, the position is out of range, or the driver is not initialised.

Reimplemented from mm::comm::FieldbusDriver.

readStates()

std::expected< std::vector< FieldbusDriver::SlaveStateRaw >, std::string > mm::comm::soem::SoemFieldbusDriver::readStates ( const std::vector< uint16_t > &  positions )

overridevirtual

Reads the current AL Status for each slave in positions.

Refreshes slave state from the hardware in one pass, then returns the raw AL Status register and AL Status Code register for each requested position. AL Status bits 3:0 encode the current state (1=Init, 2=PreOp, 3=Boot, 4=SafeOp, 8=Op); bit 4 is the error indicator. AL Status Code is non-zero when an error is present and identifies the cause (ETG.1000.6 §6.4.1).

Parameters

positions

1-based slave positions to read.

Returns

Raw state per position in the same order as positions, or an error string if the hardware read fails.

Implements mm::comm::FieldbusDriver.

scan()

std::expected< int, std::string > mm::comm::soem::SoemFieldbusDriver::scan ( )

overridevirtual

Scans the bus for slaves and configures their sync managers and FMMUs.

Sets manualstatechange so slaves remain in INIT after the scan — state transitions are left to the caller.

Returns

Number of slaves found (0 is a valid result — an empty/unpowered bus), or an error string if the underlying scan fails.

Implements mm::comm::FieldbusDriver.

setProcessDataWatchdog()

std::expected< ProcessDataWatchdogConfig, std::string > mm::comm::soem::SoemFieldbusDriver::setProcessDataWatchdog ( uint16_t  slavePosition, std::chrono::nanoseconds  timeout  )

overridevirtual

Sets the process-data (sync-manager) watchdog timeout of one slave.

Reads the slave's current watchdog divider (0x0400) — left untouched, since it is shared with the PDI watchdog — computes the nearest tick count for timeout, and FPWR-writes the process-data watchdog time register (0x0420). A timeout of zero disables the watchdog. Because the tick resolution is the divider's time base, the achieved timeout is rounded; the returned config reports what was actually programmed. Fails if timeout exceeds what the current divider can represent (more than 65535 ticks) — the error names the maximum.

The write persists across re-maps and re-scans (SOEM never reprograms these registers) until the ESC reloads EEPROM (power cycle / explicit reload). Serialised via the socket mutex; runs concurrently with the lock-free exchangeProcessData.

Optional capability: the default returns an error for transports without an ESC (e.g. SPoE); the SOEM driver overrides it.

Parameters

slavePosition	1-based slave position on the bus.
timeout	Desired watchdog timeout; zero disables the watchdog.

Returns

The watchdog configuration actually programmed (timeout rounded to the tick base), or an error string if the transport has no ESC, timeout is unrepresentable, or a register access fails.

Reimplemented from mm::comm::FieldbusDriver.

slaveCount()

int mm::comm::soem::SoemFieldbusDriver::slaveCount

(

)

const

Returns the number of discovered slaves, or 0 before discovery.

slaveInfo()

SlaveInfo mm::comm::soem::SoemFieldbusDriver::slaveInfo ( uint16_t  position ) const

overridevirtual

Returns the immutable identity fields for the slave at position.

Parameters

position

1-based slave position on the bus.

Implements mm::comm::FieldbusDriver.

slaveState()

uint16_t mm::comm::soem::SoemFieldbusDriver::slaveState ( uint16_t  position ) const

overridevirtual

Returns the last-known AL status for a slave without any bus I/O.

Returns the cached AL Status register (bits 3:0 = state, bit 4 = error) from the most recent readStates() or state transition — no network round trip. Returns 0 before any state is known. Call readStates() to refresh the cache from the hardware. Lets callers (e.g. Device) derive online / exchanging status without a redundant cached copy.

Implements mm::comm::FieldbusDriver.

stop()

void mm::comm::soem::SoemFieldbusDriver::stop ( )

overridevirtual

Closes the NIC and releases all driver resources.

Implements mm::comm::FieldbusDriver.

transitionToState()

void mm::comm::soem::SoemFieldbusDriver::transitionToState ( const std::vector< uint16_t > &  positions, std::optional< EtherCatState >  requiredState, EtherCatState  targetState, 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  )

overridevirtual

Commands a set of devices to targetState and blocks until all arrive or timeout elapses.

Devices whose current state (error bit masked) does not match requiredState are skipped; pass std::nullopt to command all positions unconditionally.

The call polls at ~100 ms intervals, re-sending the command to lagging devices every resendInterval. Devices that do not arrive in time are logged at error level; no exception is thrown. The outcome per device is not returned here — read it back via readStates after the call (this is what DeviceManager::transitionToState does).

Parameters

positions	1-based device positions to target.
requiredState	Pre-filter: only command devices whose current state equals this value. std::nullopt skips filtering and commands all positions.
targetState	Desired state.
timeout	Maximum time to wait for all devices.
resendInterval	How often to re-send the command to lagging devices.
tick	Optional callback invoked at ~1 ms intervals while waiting. Pass a PDO sender when targeting EtherCatState::Op so the sync-manager watchdog does not fire during the wait.
shouldAbort	Optional predicate; when it returns true the wait is abandoned early without logging failures for pending devices.

Implements mm::comm::FieldbusDriver.

writeFile()

std::expected< void, std::string > mm::comm::soem::SoemFieldbusDriver::writeFile ( uint16_t  slavePosition, const std::string &  filename, std::span< const uint8_t >  data  )

overridevirtual

Writes a file to the slave via File over EtherCAT (FoE).

Sends an FoE write request for filename and streams data to the slave. FoE is available in Boot, Pre-Op, Safe-Op, and Op states (device-dependent); the caller is responsible for ensuring the device is in a suitable state. Called from non-RT (HTTP handler) threads; serialized with other control-plane operations via the driver's socket mutex.

Parameters

slavePosition	1-based slave position on the bus.
filename	FoE filename as recognised by the slave firmware.
data	File bytes to write.

Returns

Void on success, or an error string if the transfer fails.

Implements mm::comm::FieldbusDriver.

writeRegister()

std::expected< void, std::string > mm::comm::soem::SoemFieldbusDriver::writeRegister ( uint16_t  slavePosition, uint16_t  address, std::span< const uint8_t >  data  )

overridevirtual

Writes bytes to an ESC register via FPWR.

Parameters

slavePosition	1-based slave position on the bus.
address	ESC register address.
data	Bytes to write.

Returns

Void on success, or an error string if the working counter is not 1.

Implements mm::comm::FieldbusDriver.

writeSdo()

std::expected< void, std::string > mm::comm::soem::SoemFieldbusDriver::writeSdo ( uint16_t  slavePosition, uint16_t  index, uint8_t  subindex, std::span< const uint8_t >  data  )

overridevirtual

Writes an object dictionary entry to a slave (CoE SDO download).

Performs a mailbox SDO download of data to (index, subindex). The slave must be in PRE-OP, SAFE-OP, or OP (mailbox communication active). Called from non-RT (HTTP handler) threads; serialized with other control-plane operations via the driver's socket mutex, and runs concurrently with the lock-free exchangeProcessData (never blocks the RT cycle).

Parameters

slavePosition	1-based slave position on the bus.
index	CoE object index.
subindex	CoE object subindex.
data	Bytes to write; size must match the object's length.

Returns

Void on success, or an error string if the mailbox transfer fails.

Implements mm::comm::FieldbusDriver.

writeSii()

std::expected< void, std::string > mm::comm::soem::SoemFieldbusDriver::writeSii ( uint16_t  slavePosition, std::span< const uint8_t >  data  )

overridevirtual

Writes a raw SII (EEPROM) image to a slave.

Writes data to the slave's EEPROM through the ESC's EEPROM-control registers, one 16-bit word at a time from word address 0. data must be a whole number of 16-bit words (even length). This is a destructive control-plane operation: a malformed image can leave the slave unidentifiable until re-flashed. EEPROM access takes the socket mutex (running concurrently with the lock-free exchangeProcessData) and is only safe while the slave is in INIT or PRE-OP. The slave does not adopt the new contents until its ESC reloads the EEPROM — i.e. after a power cycle.

Optional capability: the default returns an error for transports without an ESC EEPROM (e.g. SPoE); the SOEM driver overrides it.

Parameters

slavePosition	1-based slave position on the bus.
data	Raw SII image to write (even length).

Returns

Void on success, or an error string if the transport has no EEPROM, the position is out of range, data has an odd length, or a word write fails.

Reimplemented from mm::comm::FieldbusDriver.

---

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

• libs/comm/soem_fieldbus_driver.h
• libs/comm/soem_fieldbus_driver.cc