Handles TCP communication with SOMANET devices over SPoE. More...

#include <spoe.h>

Inheritance diagram for mm::comm::spoe::Device:

Collaboration diagram for mm::comm::spoe::Device:

Public Member Functions
	Device (const std::string &ip, uint16_t port, uint16_t position=0, std::chrono::milliseconds refresherInterval=std::chrono::milliseconds(3000))
	Constructs a SpoeDevice object with the specified IP address, port, and optionally position. More...

	~Device ()
	Destructor for the Device class. More...

std::string	getSocketAddress () const
	Returns the socket address as a string in the format "IP:port". More...

uint16_t	incrementSeqId ()
	Increments the sequence ID atomically and wraps it around at the maximum value. More...

bool	connect (std::chrono::seconds expiryTime=std::chrono::seconds(3))
	Attempts to connect the SPoE device to the specified endpoint. More...

bool	isConnected ()
	Checks if the SPoE socket is currently open. More...

bool	disconnect ()
	Gracefully disconnects the SPoE device. More...

Message	exchangeWithTimeout (const Message &request, const std::chrono::steady_clock::duration expiryTime)
	Exchanges a message with a remote server and waits for a response with a timeout. More...

uint16_t	getPosition () const override
	Gets the device's position in the network chain. More...

uint8_t	getState (bool refresh=false, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000)) override
	Sends a request to read the state of the device and returns the state value. More...

bool	setState (uint8_t state, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000)) override
	Sends a state control command to the SPoE device and checks the response. More...

std::vector< uint8_t >	readFile (const std::string &filename, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000)) override
	Reads a file from the device using segmented SPoE messages. More...

std::vector< std::string >	readFileList (const bool stripSizeSuffix=true, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000)) override
	Reads a list of file names from the device. More...

void	removeFile (const std::string &filename, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000)) override
	Remove a file from the SPoE device. More...

void	updateFirmware (const std::vector< std::uint8_t > &data, const std::vector< std::string > &skipFiles={"SOMANET_CiA_402.xml.zip", "stack_image.svg.zip"}, std::function< void(uint8_t, std::string)> progressCallback=nullptr, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(60000)) override
	Updates the firmware on this SPoE device. More...

void	writeFile (const std::string &filename, const std::vector< uint8_t > &data, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000)) override
	Write a file to the SPoE device in segments. More...

bool	triggerFirmwareUpdate (const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(2000))
	Sends a firmware update request to the connected Integro device. More...

std::vector< mm::comm::base::Parameter >	getParametersFromDevice (bool readValues=false, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(1000))
	Retrieves the parameter list from the device. More...

std::vector< uint8_t >	readSdo (uint16_t index, uint8_t subindex, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(1000))
	Reads an SDO (Service Data Object) from the device. More...

std::vector< std::vector< uint8_t > >	readSdoBatch (const std::vector< mm::comm::base::Parameter::Address > &addresses, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(1000))
	Reads a batch of SDOs from the device in a single request. More...

std::vector< std::vector< uint8_t > >	readSdoBatch (const std::vector< mm::comm::base::Parameter > &parameters, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(1000))
	Reads a batch of SDOs for the specified parameters in a single request. More...

void	readSdoBatchAndUpdateParameters (std::vector< mm::comm::base::Parameter > &parameters, std::size_t batchSize=50, std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(1000))
	Reads the specified parameters in batches and updates their values. More...

bool	writeSdo (uint16_t index, uint8_t subindex, const std::vector< uint8_t > &data, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(1000))
	Writes a Service Data Object (SDO) to the device. More...

size_t	loadParameters (bool readValues=false, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(9000)) override
	Loads parameters from the device and stores them locally. More...

void	clearParameters () override
	Clears all loaded object dictionary parameters. More...

std::vector< std::reference_wrapper< mm::comm::base::Parameter > >	parameters () override
	Get a vector of references to parameters. More...

mm::comm::base::Parameter &	findParameter (uint16_t index, uint8_t subindex) override
	Finds and returns a reference to a parameter by its index and subindex. More...

mm::comm::base::Parameter &	upload (const uint16_t index, const uint8_t subindex, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(3000)) override
	Uploads a parameter from the device via SDO and updates the local parameter store. More...

template<typename T >
T	upload (uint16_t index, uint8_t subindex, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))
	Uploads a parameter from the device and returns its value as the specified type. More...

void	download (uint16_t index, uint8_t subindex, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000)) override
	Downloads a parameter to the device using SDO communication. More...

void	download (uint16_t index, uint8_t subindex, const mm::comm::base::ParameterValue &value, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000)) override
	Sets a parameter value in the local store and downloads it to the device. More...

template<typename T >
void	download (uint16_t index, uint8_t subindex, const T &value, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))
	Sets and downloads a parameter value to the device using the specified type. More...

ServerInfo	getServerInfo (const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(3000))
	Retrieves the server information from the connected SPoE device. More...

bool	setPdoMode (PdoMode mode, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(3000))

std::vector< uint8_t >	exchangeProcessData (const std::vector< uint8_t > &data, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(1000))
	Exchanges process data (PDO) with the device. More...

void	performProcessDataExchangeAsync ()
	Perform asynchronous process data exchange with the SPoE device. More...

void	exchangeProcessDataAndUpdateParameters (uint64_t missedCycles=0) override
	Exchanges process data and updates device parameters. More...

mm::comm::base::PdoMappingStatus	getPdoMappingStatus (uint16_t index, uint8_t subindex) const override
	Determines the PDO mapping status of a parameter by its index and subindex. More...

mm::comm::base::MappedParameterValues	getMappedParameterValues ()
	Retrieves the mapped parameter values for the SPoE device. More...

bool	isOnline () override
	Checks if the SPoE device is online. More...

DeviceParameterRefresher &	refresher ()
	Get a reference to the device parameter refresher. More...

virtual	~Device ()=default
	Virtual destructor for Device interface. More...

virtual uint16_t	getPosition () const =0
	Gets the device's position in the network chain. More...

virtual uint8_t	getState (bool refresh=false, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Reads and returns the current state of the device. More...

virtual bool	setState (uint8_t state, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Sets the device to a specified state. More...

virtual std::vector< uint8_t >	readFile (const std::string &filename, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Reads the contents of a file from the device. More...

virtual std::vector< std::string >	readFileList (const bool stripSizeSuffix, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Reads a list of file names from the device. More...

virtual void	writeFile (const std::string &filename, const std::vector< uint8_t > &data, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Sends a file to the device. More...

virtual void	removeFile (const std::string &filename, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Removes a file from the device. More...

virtual void	updateFirmware (const std::vector< std::uint8_t > &data, const std::vector< std::string > &skipFiles={}, std::function< void(uint8_t, std::string)> progressCallback=nullptr, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(60000))=0
	Updates the device firmwares. More...

virtual size_t	loadParameters (bool readValues, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(9000))=0
	Loads parameters from the device and stores them locally. More...

virtual void	clearParameters ()=0
	Clears all loaded object dictionary parameters. More...

virtual std::vector< std::reference_wrapper< Parameter > >	parameters ()=0
	Get a vector of references to parameters. More...

virtual Parameter &	findParameter (uint16_t index, uint8_t subindex)=0
	Finds and returns a reference to a parameter by its index and subindex. More...

virtual Parameter &	upload (uint16_t index, uint8_t subindex, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Uploads a parameter from the device via SDO and updates the local parameter store. More...

virtual void	download (uint16_t index, uint8_t subindex, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Downloads a parameter to the device using SDO communication. More...

virtual void	download (uint16_t index, uint8_t subindex, const ParameterValue &value, const std::chrono::steady_clock::duration expiryTime=std::chrono::milliseconds(5000))=0
	Sets a parameter value in the local store and downloads it to the device. More...

virtual void	exchangeProcessDataAndUpdateParameters (uint64_t missedCycles=0)=0
	Exchanges process data with the remote device and updates local parameters accordingly. More...

virtual PdoMappingStatus	getPdoMappingStatus (uint16_t index, uint8_t subindex) const =0
	Determines the PDO mapping status of a parameter by its index and subindex. More...

virtual bool	isOnline ()=0
	Checks if the device is online. More...

Detailed Description

Handles TCP communication with SOMANET devices over SPoE.

This class provides methods for connecting to a remote server, sending messages, and receiving responses over a TCP connection using Boost.Asio. It manages the underlying socket, connection, and I/O operations required for client-server communication.

Constructor & Destructor Documentation

◆ Device()

mm::comm::spoe::Device::Device	(	const std::string &	ip,
		uint16_t	port,
		uint16_t	position = `0`,
		std::chrono::milliseconds	refresherInterval = `std::chrono::milliseconds(3000)`
	)

Constructs a SpoeDevice object with the specified IP address, port, and optionally position.

Initializes the client with the target server's IP address and port number.

Parameters

ip	The IP address of the server to connect to.
port	The port number to use for the connection.
position	Device position in the network chain.
refresherInterval	The interval at which the device parameters are refreshed. Defaults to 3000 milliseconds.

◆ ~Device()

mm::comm::spoe::Device::~Device ( )

virtual

Destructor for the Device class.

Closes the socket and disconnects from the server if the socket is open.

Reimplemented from mm::comm::base::Device.

Member Function Documentation

◆ clearParameters()

void mm::comm::spoe::Device::clearParameters ( )

overridevirtual

Clears all loaded object dictionary parameters.

This function removes all entries from the internal parameter map, effectively resetting the parameter list of the slave device.

Implements mm::comm::base::Device.

◆ connect()

bool mm::comm::spoe::Device::connect ( std::chrono::seconds expiryTime = std::chrono::seconds(3) )

Attempts to connect the SPoE device to the specified endpoint.

This function starts an asynchronous connection attempt and waits for it to complete within the given expiry time. If the connection attempt exceeds the timeout, it is canceled.

Parameters

expiryTime The maximum duration to wait for the connection attempt.

Returns: true if the connection was successful, false otherwise.

◆ disconnect()

bool mm::comm::spoe::Device::disconnect ( )

Gracefully disconnects the SPoE device.

Cancels any outstanding asynchronous operations, performs a TCP shutdown for both send and receive directions, and closes the underlying socket. If the socket is already closed, this function does nothing.

Returns: true if the socket was closed successfully or was already closed, false if an error occurred during shutdown or close.

Note: This method safely handles any exceptions and logs all socket errors. Use this before attempting to reconnect with the same socket instance.

◆ download() [1/3]

void mm::comm::spoe::Device::download	(	uint16_t	index,
		uint8_t	subindex,
		const mm::comm::base::ParameterValue &	value,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

overridevirtual

Sets a parameter value in the local store and downloads it to the device.

This function updates the specified parameter in the local store with the provided value, serializes it, and then performs an SDO download to transfer the data to the device.

Parameters

index	The 16-bit index of the parameter in the object dictionary.
subindex	The 8-bit subindex of the parameter.
value	The new parameter value to set and download.
expiryTime	The maximum duration to wait for the SDO download operation to complete.

Exceptions

std::runtime_error If the parameter data is empty after setting the value, or if the SDO download operation fails.

Implements mm::comm::base::Device.

◆ download() [2/3]

void mm::comm::spoe::Device::download	(	uint16_t	index,
		uint8_t	subindex,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

overridevirtual

Downloads a parameter to the device using SDO communication.

This function sends the binary data of the specified parameter (retrieved from the local store) to the device. The operation fails if the parameter's data is empty.

Parameters

index	The 16-bit index of the parameter in the object dictionary.
subindex	The 8-bit subindex of the parameter.
expiryTime	The maximum duration to wait for the SDO download operation to complete.

Exceptions

std::runtime_error If the parameter data is empty or the SDO download fails.

Implements mm::comm::base::Device.

◆ download() [3/3]

template<typename T >

void mm::comm::spoe::Device::download	(	uint16_t	index,
		uint8_t	subindex,
		const T &	value,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

inline

Sets and downloads a parameter value to the device using the specified type.

This templated overload wraps the given value in a mm::comm::ParameterValue, updates the local parameter store, and performs an SDO download to transfer the data to the device.

Template Parameters

T	The type of the value to set and download.

Parameters

index	The 16-bit index of the parameter in the object dictionary.
subindex	The 8-bit subindex of the parameter.
value	The new parameter value to set and download.
expiryTime	The maximum duration to wait for the SDO download operation. Defaults to 5000 milliseconds.

Exceptions

std::runtime_error If the parameter data is empty after setting the value, or if the SDO download operation fails.

◆ exchangeProcessData()

std::vector< uint8_t > mm::comm::spoe::Device::exchangeProcessData	(	const std::vector< uint8_t > &	data,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(1000)`
	)

Exchanges process data (PDO) with the device.

Constructs and sends a PDO_RXTX_FRAME message containing the specified process data payload, then waits for the device to respond within the given expiry time. If the device responds with an unexpected status code, an DeviceResponseException is thrown.

Parameters

data	The process data to transmit to the device.
expiryTime	The maximum duration to wait for the response.

Returns: A vector of bytes containing the process data returned by the device.

Exceptions

DeviceResponseException If the response indicates an unexpected status code.

◆ exchangeProcessDataAndUpdateParameters()

void mm::comm::spoe::Device::exchangeProcessDataAndUpdateParameters ( uint64_t missedCycles = 0 )

overridevirtual

Exchanges process data and updates device parameters.

This function checks whether a process data exchange is already running, and if not, starts it asynchronously. It then checks for any exceptions thrown during the previous exchange and rethrows them to notify the caller. If new TX PDO data is available, it updates the corresponding parameters according to the TxPDO mapping by copying the received data slices into each mapped parameter.

Parameters

missedCycles Number of cycles missed since the last call.

Exceptions

Any	exception thrown during the asynchronous process data exchange will be rethrown here to the caller.

Implements mm::comm::base::Device.

◆ exchangeWithTimeout()

Message mm::comm::spoe::Device::exchangeWithTimeout	(	const Message &	request,
		const std::chrono::steady_clock::duration	expiryTime
	)

Exchanges a message with a remote server and waits for a response with a timeout.

This method serializes the request message, sends it to the server using an asynchronous write operation, and waits for a response with a timeout. If the operation takes longer than the specified expiry time, the operation will be canceled and an error will be thrown.

Parameters

requestMessage	The message to send to the remote server.
expiryTime	The duration to wait for the socket operation (read/write) before timing out.

Returns: SpoeMessage The parsed response message from the server.

Exceptions

std::runtime_error If the write or read operation fails, or if the operation times out.

◆ findParameter()

mm::comm::base::Parameter & mm::comm::spoe::Device::findParameter	(	uint16_t	index,
		uint8_t	subindex
	)

overridevirtual

Finds and returns a reference to a parameter by its index and subindex.

This function looks up a parameter in the internal parameter map using the specified index and subindex. If the parameter is found, a reference to it is returned. If not, a runtime exception is thrown.

Parameters

index	The index of the parameter to find.
subindex	The subindex of the parameter to find.

Returns: Reference to the found parameter.

Exceptions

std::runtime_error If the parameter with the specified index and subindex is not found in the map.

Implements mm::comm::base::Device.

◆ getMappedParameterValues()

mm::comm::base::MappedParameterValues mm::comm::spoe::Device::getMappedParameterValues ( )

Retrieves the mapped parameter values for the SPoE device.

This function iterates over the PDO mappings configured for the device, fetching the current parameter values associated with each mapping. It separates the mapped parameters into RX and TX groups based on the PDO direction and returns them in a structured format.

Returns

mm::comm::MappedParameterValues A structure containing two vectors:

rx: mapped parameter values for received PDOs.
tx: mapped parameter values for transmitted PDOs.

◆ getParametersFromDevice()

std::vector< mm::comm::base::Parameter > mm::comm::spoe::Device::getParametersFromDevice	(	bool	readValues = `false`,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(1000)`
	)

Retrieves the parameter list from the device.

Sends a PARAM_LIST request to the device and reads the response in multiple segments using a sequence ID for each segment. The response is validated after each exchange. If the status is not SpoeMessageParamListErrorStatus::SUCCESS_ACK, a DeviceResponseException is thrown.

Parses each 68-byte entry in the response into a mm::comm::Parameter object, extracting index, subindex, data type, code, flags, bit length, and name. Optionally performs an SDO batch read to update parameter values if readValues is true.

Uses a lock guard with a recursive mutex to ensure thread safety.

Parameters

readValues	If true, performs an additional SDO batch read to retrieve current parameter values from the device.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 1000 milliseconds.

Returns: A vector of parsed mm::comm::Parameter objects containing the parameters retrieved from the device.

Exceptions

boost::system::system_error	if sending or receiving fails.
DeviceResponseException	if any response status indicates an error.

◆ getPdoMappingStatus()

mm::comm::base::PdoMappingStatus mm::comm::spoe::Device::getPdoMappingStatus	(	uint16_t	index,
		uint8_t	subindex
	)		const

overridevirtual

Determines the PDO mapping status of a parameter by its index and subindex.

This function checks whether a parameter with the specified index and subindex is mapped in either the Receive (RX) or Transmit (TX) Process Data Objects (PDOs).

Parameters

index	The object dictionary index of the parameter.
subindex	The subindex of the parameter.

Returns

A PdoMappingStatus value indicating whether the parameter is:

NOT_MAPPED: Not mapped in any PDO.
MAPPED_RX_PDO: Mapped as an RX PDO.
MAPPED_TX_PDO: Mapped as a TX PDO.

Implements mm::comm::base::Device.

◆ getPosition()

uint16_t mm::comm::spoe::Device::getPosition ( ) const

overridevirtual

Gets the device's position in the network chain.

This value indicates the device's logical position or order within the network topology or communication chain.

Returns: The device's position as a 16-bit unsigned integer.

Implements mm::comm::base::Device.

◆ getServerInfo()

ServerInfo mm::comm::spoe::Device::getServerInfo ( const std::chrono::steady_clock::duration expiryTime = std::chrono::milliseconds(3000) )

Retrieves the server information from the connected SPoE device.

Sends a SERVER_INFO request message, waits for the response within the specified timeout, and extracts the protocol version from the response. The monitoring mode is currently set to 0 by default.

Parameters

expiryTime The maximum duration to wait for a response. Defaults to 3000 milliseconds.

Returns: ServerInfo Struct containing the protocol version and monitoring mode.

Exceptions

DeviceResponseException If the response indicates an unexpected status code.

◆ getSocketAddress()

std::string mm::comm::spoe::Device::getSocketAddress ( ) const

Returns the socket address as a string in the format "IP:port".

This function retrieves the IP address and port number from the configured endpoint and formats them as a single string (e.g., "192.168.1.10:8080").

Returns: A string representation of the socket address.

◆ getState()

uint8_t mm::comm::spoe::Device::getState	(	bool	refresh = `false`,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

overridevirtual

Sends a request to read the state of the device and returns the state value.

This function sends a request to the device using the SpoeMessageType::STATE_READ message type. It increments the sequence ID, constructs the request message, serializes it, and sends it to the device. After sending the request, the function waits for the response, parses the response message, and returns the state value as a uint8_t.

The returned state corresponds to the EtherCAT state machine states, where:

INIT: 1
PREOP: 2
SAFEOP: 4
OP: 8
BOOT: 3

Parameters

refresh	If true, forces a refresh of the device state by sending a `STATE_READ` request even if the state is already cached.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 5000 milliseconds.

Returns: The state value of the device as a uint8_t.

Exceptions

boost::system::system_error	if sending or receiving fails.
std::runtime_error	if the response buffer is too small to parse.

Implements mm::comm::base::Device.

◆ incrementSeqId()

uint16_t mm::comm::spoe::Device::incrementSeqId ( )

Increments the sequence ID atomically and wraps it around at the maximum value.

This function atomically increments the seq_id (a 16-bit unsigned integer). When the value reaches the maximum value of uint16_t (0xFFFF), it wraps around to 0. It ensures thread safety when used in multithreaded environments.

Returns: The updated sequence ID after incrementing, wrapped around if necessary.

◆ isConnected()

bool mm::comm::spoe::Device::isConnected ( )

Checks if the SPoE socket is currently open.

Returns true if the underlying socket is open, indicating an active or initialized connection. Returns false otherwise.

Returns: true if the socket is open, false otherwise.

◆ isOnline()

bool mm::comm::spoe::Device::isOnline ( )

overridevirtual

Checks if the SPoE device is online.

This method tries to retrieve basic server information with a short timeout. If the request succeeds, the device is considered online. If it fails (e.g., due to timeout, network error, or protocol error), the method returns false.

Returns: true if the device responds within the timeout; false otherwise.

Implements mm::comm::base::Device.

◆ loadParameters()

size_t mm::comm::spoe::Device::loadParameters	(	bool	readValues = `false`,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(9000)`
	)

overridevirtual

Loads parameters from the device and stores them locally.

This function retrieves a list of parameters using the getParameters method. It then stores each parameter in a map for later use, keyed by a pair consisting of the parameter's index and subindex.

Parameters

readValues	If true, the values of the parameters are read from the device; otherwise, only the parameter metadata is retrieved.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 9000 milliseconds.

Returns: The number of loaded parameters.

Implements mm::comm::base::Device.

◆ parameters()

std::vector< std::reference_wrapper< mm::comm::base::Parameter > > mm::comm::spoe::Device::parameters ( )

overridevirtual

Get a vector of references to parameters.

This function returns a vector containing reference wrappers to the parameters stored internally in parametersMap_. Each element in the returned vector references a parameter in the map, allowing for efficient, non-owning access.

Returns: std::vector<std::reference_wrapper<mm::comm::Parameter>> Vector of references to parameters.

Implements mm::comm::base::Device.

◆ performProcessDataExchangeAsync()

void mm::comm::spoe::Device::performProcessDataExchangeAsync ( )

Perform asynchronous process data exchange with the SPoE device.

Prepares the receive (RX) process data buffer according to the RxPDO mapping, sends it, and waits for the response. The received data is then split into fixed-size TX PDO frames (in bytes) and pushed to the transmit (TX) PDO queue. If the TX PDO queue exceeds a defined size, the oldest entries are removed to keep the queue manageable.

Any exceptions thrown during send or receive are caught and stored for later handling. The sending flag is always cleared to indicate that the operation has finished.

Note: The received TxPDO data may contain one or more fixed-size blocks concatenated together (for example, multiple blocks combined in a single TCP frame). Each block contains multiple PDO entries of varying lengths. This function splits the data into individual blocks and pushes them to the TX PDO queue.

◆ readFile()

std::vector< uint8_t > mm::comm::spoe::Device::readFile	(	const std::string &	filename,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

overridevirtual

Reads a file from the device using segmented SPoE messages.

This function sends a FILE_READ request to the device and reads the file in segments until the last segment is received. It validates the content and returns either the file data or an appropriate error.

Parameters

filename	The name of the file to read from the device.
expiryTime	Timeout duration for communication with the device.

Returns

std::variant<std::vector<uint8_t>, mm::comm::DeviceFileError>

On success: a vector containing the file content.
On failure: a DeviceFileError indicating the error type.

Possible errors:

DeviceFileError::NullTerminator if the file starts with a null byte.
DeviceFileError::EmptyContent if the content is empty and the file is not found in the file list.

Reads the contents of a file over SPoE from the device.

This function requests the file in multiple segments by sending SPoE messages with increasing sequence IDs. It accumulates the received data until the entire file is read.

The request starts with the filename in the first message, then subsequent messages request the next segments until the last segment is received.

Error handling:

If the device responds with an error status, a DeviceResponseException is thrown containing the device position and error code.
If the received content is empty, the function checks if the file exists on the device by calling readFileList(true).
- If the file is found, the empty content is considered valid and returned.
- If not found, a DeviceResponseException is thrown indicating the file was not found.

Parameters

filename	The name of the file to read.
expiryTime	Timeout duration for each socket read/write operation. Defaults to 5000 milliseconds.

Returns: A vector of bytes containing the file content. May be empty if the file exists but contains no data.

Exceptions

DeviceResponseException	When the device returns an error status, or the file does not exist on the device.
boost::system::system_error	If socket communication fails during the request or response.

Implements mm::comm::base::Device.

◆ readFileList()

std::vector< std::string > mm::comm::spoe::Device::readFileList	(	const bool	stripSizeSuffix = `true`,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

overridevirtual

Reads a list of file names from the device.

Sends a request to read the file list using the "fs-getlist" command, waits up to the specified timeout, and parses the result into individual lines. Each line represents a file name. Handles both Unix (\n) and Windows (\r\n) line endings.

If stripSizeSuffix is true, the size suffix will be removed from each file entry in the returned list.

If the device fails to provide the file list, an empty list is returned and an error is logged.

Parameters

stripSizeSuffix	If true, removes the ", size: <bytes>" suffix from each line. Defaults to true.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 5000 milliseconds.

Returns: A vector of strings, where each string is a file name from the response.

Implements mm::comm::base::Device.

◆ readSdo()

std::vector< uint8_t > mm::comm::spoe::Device::readSdo	(	uint16_t	index,
		uint8_t	subindex,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(1000)`
	)

Reads an SDO (Service Data Object) from the device.

Constructs and sends an SDO read request for the specified index and subindex, waits for a response within the given expiry time, and returns the received data. If the device responds with an error status, an DeviceResponseException is thrown.

Parameters

index	The index of the SDO to read.
subindex	The subindex of the SDO to read.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 1000 milliseconds.

Returns: A vector containing the data from the SDO response. An empty vector is returned if the operation fails.

Exceptions

boost::system::system_error	if sending or receiving fails.
DeviceResponseException	If the response contains an unexpected status code.

◆ readSdoBatch() [1/2]

std::vector< std::vector< uint8_t > > mm::comm::spoe::Device::readSdoBatch	(	const std::vector< mm::comm::base::Parameter > &	parameters,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(1000)`
	)

Reads a batch of SDOs for the specified parameters in a single request.

Converts the given list of parameters into (index, subindex) address pairs and performs a single batch read using the SPoE protocol.

Parameters

parameters	List of parameters to read.
expiryTime	Timeout duration for the read operation. Defaults to 1000 ms.

Returns: A vector of raw data buffers, one per parameter read.

◆ readSdoBatch() [2/2]

std::vector< std::vector< uint8_t > > mm::comm::spoe::Device::readSdoBatch	(	const std::vector< mm::comm::base::Parameter::Address > &	addresses,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(1000)`
	)

Reads a batch of SDOs from the device in a single request.

Constructs a batch read message containing the specified SDO indices and subindices, sends it to the device, and waits for a response within the given timeout. The response buffer contains the raw SDO values in sequence, each prefixed with a 2-byte little-endian length.

The method validates the response and splits it into individual SDO value blocks matching the requested addresses.

Parameters

addresses	A vector of (index, subindex) pairs representing the SDOs to read.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 1000 milliseconds.

Returns: A vector of SDO value blocks. Each entry holds the raw bytes for one SDO value, in the same order as the input addresses.

The returned buffer layout is: [Len1 (2 bytes)] [Data1 (Len1 bytes)] [Len2 (2 bytes)] [Data2 (Len2 bytes)] ...

Exceptions

boost::system::system_error	if sending or receiving fails.
DeviceResponseException	If the response indicates an unexpected status code.
std::runtime_error	If the response data format is invalid or incomplete.

Splits a raw SDO batch response buffer into individual SDO value blocks.

Each SDO value is prefixed with a 2-byte little-endian length. The lambda iterates through the buffer, extracts each length-prefixed value, and returns a vector of all extracted SDO values.

Parameters

buffer Raw buffer containing [length][value] pairs in sequence.

Returns: std::vector<std::vector<uint8_t>> List of extracted SDO values.

Exceptions

std::runtime_error if the buffer format is invalid (e.g., length field exceeds remaining size).

◆ readSdoBatchAndUpdateParameters()

void mm::comm::spoe::Device::readSdoBatchAndUpdateParameters	(	std::vector< mm::comm::base::Parameter > &	parameters,
		std::size_t	batchSize = `50`,
		std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(1000)`
	)

Reads the specified parameters in batches and updates their values.

Splits the given list of parameters into batches of the specified size, performs a batch SDO read for each batch, and updates each original parameter with the retrieved value.

Parameters

parameters	The parameters to read and update.
batchSize	The maximum number of parameters to read per batch.
expiryTime	The timeout for each batch read operation.

◆ refresher()

DeviceParameterRefresher & mm::comm::spoe::Device::refresher ( )

inline

Get a reference to the device parameter refresher.

Returns: Reference to the DeviceParameterRefresher.

◆ removeFile()

void mm::comm::spoe::Device::removeFile	(	const std::string &	filename,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

overridevirtual

Remove a file from the SPoE device.

This function removes a file on the device by reading a special file named "fs-remove=<filename>". The device signals successful removal by returning a response message starting with a specific confirmation prefix.

If the response does not contain the expected prefix or if the operation fails, a DeviceResponseException is thrown.

Parameters

filename	Name of the file to remove.
expiryTime	Maximum duration to wait for the response before timing out. Defaults to 5000 milliseconds.

Exceptions

mm::comm::DeviceResponseException if the removal fails or the device returns an unexpected response.

Implements mm::comm::base::Device.

◆ setPdoMode()

bool mm::comm::spoe::Device::setPdoMode	(	PdoMode	mode,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(3000)`
	)

◆ setState()

bool mm::comm::spoe::Device::setState	(	uint8_t	state,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

overridevirtual

Sends a state control command to the SPoE device and checks the response.

This method constructs a STATE_CONTROL type SpoeMessage with the given state, sends it over the socket, and waits for a response. It then parses the received message and returns true if the operation was acknowledged with OK status.

Parameters

state	The new state to set on the remote device.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 5000 milliseconds.

Returns: true if the response status is OK, false otherwise.

Exceptions

boost::system::system_error	if sending or receiving fails.
std::runtime_error	if the response buffer is too small to parse.

Implements mm::comm::base::Device.

◆ triggerFirmwareUpdate()

bool mm::comm::spoe::Device::triggerFirmwareUpdate ( const std::chrono::steady_clock::duration expiryTime = std::chrono::milliseconds(2000) )

Sends a firmware update request to the connected Integro device.

Constructs and transmits a firmware update request using the custom SPoE communication protocol. Waits for the device's response and verifies whether the request was successfully acknowledged.

This request must be issued after uploading one or both of the following files:

app_firmware.bin: Contains the SoC firmware.
com_firmware.bin: Contains the communication chip firmware.

Parameters

expiryTime The duration to wait for the socket operation (read/write) before timing out. Defaults to 2000 milliseconds.

Returns: true if the device responds with an OK status; false otherwise.

◆ updateFirmware()

void mm::comm::spoe::Device::updateFirmware	(	const std::vector< std::uint8_t > &	data,
		const std::vector< std::string > &	skipFiles = `{"SOMANET_CiA_402.xml.zip", "stack_image.svg.zip"}`,
		std::function< void(uint8_t, std::string)>	progressCallback = `nullptr`,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(60000)`
	)

overridevirtual

Updates the firmware on this SPoE device.

Puts the device into the INIT and BOOT states, writes the provided firmware package (optionally skipping specified files), triggers the firmware update process on the device, and then disconnects and reconnects the device.

Parameters

data	The firmware package as a vector of bytes (typically a zip archive).
skipFiles	A list of file names to skip when writing the firmware to the device.
progressCallback	Optional callback to report update progress (accepts a percentage [0–100]).
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 60000 milliseconds.

Exceptions

std::runtime_error If triggering the firmware update fails.

Note: This function disconnects and reconnects the device automatically after the update.

Implements mm::comm::base::Device.

◆ upload() [1/2]

mm::comm::base::Parameter & mm::comm::spoe::Device::upload	(	const uint16_t	index,
		const uint8_t	subindex,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(3000)`
	)

overridevirtual

Uploads a parameter from the device via SDO and updates the local parameter store.

This function reads a parameter value from the device using SDO communication, updates the corresponding local Parameter object with the received value, and returns a reference to it.

Parameters

index	The 16-bit parameter index in the object dictionary.
subindex	The 8-bit subindex of the parameter.
expiryTime	The maximum duration to wait for the SDO upload operation to complete.

Returns: Reference to the updated local Parameter object.

Exceptions

std::runtime_error If the upload fails or returns an empty payload.

Implements mm::comm::base::Device.

◆ upload() [2/2]

template<typename T >

T mm::comm::spoe::Device::upload	(	uint16_t	index,
		uint8_t	subindex,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

inlinevirtual

Uploads a parameter from the device and returns its value as the specified type.

This templated overload uploads a parameter using the given index and subindex, updates the corresponding parameter in the local store, and returns its value as type T.

Template Parameters

T	The type to extract from the uploaded parameter value.

Parameters

index	The 16-bit index of the parameter in the object dictionary.
subindex	The 8-bit subindex of the parameter.
expiryTime	The maximum duration to wait for the SDO upload operation. Defaults to 5000 milliseconds.

Returns: The uploaded parameter value cast to type T.

Exceptions

std::runtime_error	If the SDO upload fails or the value cannot be extracted as type `T`.
std::bad_variant_access	If the internal variant does not hold the requested type `T`.

Implements mm::comm::base::Device.

◆ writeFile()

void mm::comm::spoe::Device::writeFile	(	const std::string &	filename,
		const std::vector< uint8_t > &	data,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(5000)`
	)

overridevirtual

Write a file to the SPoE device in segments.

This function writes the specified file to the device by first sending the filename and then transmitting the file data in segments. The transfer uses a maximum segment size for each write operation and ensures that each segment is acknowledged by the device before proceeding.

If any part of the transfer fails, a DeviceResponseException is thrown with details about the error.

Parameters

filename	Name of the file to be written on the device.
data	File contents to write.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 5000 milliseconds.

Exceptions

mm::comm::DeviceResponseException	if the device responds with an error during any segment write.
boost::system::system_error	If socket communication fails during the request or response.

Implements mm::comm::base::Device.

◆ writeSdo()

bool mm::comm::spoe::Device::writeSdo	(	uint16_t	index,
		uint8_t	subindex,
		const std::vector< uint8_t > &	data,
		const std::chrono::steady_clock::duration	expiryTime = `std::chrono::milliseconds(1000)`
	)

Writes a Service Data Object (SDO) to the device.

Constructs and sends an SDO write request for the specified index and subindex, including the provided value bytes. Waits for a response within the given expiry time. If the device responds with an error status, an DeviceResponseException is thrown.

Parameters

index	The index of the SDO to write.
subindex	The subindex of the SDO to write.
value	A vector containing the data to be written to the SDO.
expiryTime	The duration to wait for the socket operation (read/write) before timing out. Defaults to 1000 milliseconds.

Returns: true if the write operation was successful, false otherwise.

Exceptions

boost::system::system_error	if sending or receiving fails.
DeviceResponseException	If the response indicates an unexpected status code.

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

libs/comm/spoe.h
libs/comm/spoe.cc

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Device()

◆ ~Device()

Member Function Documentation

◆ clearParameters()

◆ connect()

◆ disconnect()

◆ download() [1/3]

◆ download() [2/3]

◆ download() [3/3]

◆ exchangeProcessData()

◆ exchangeProcessDataAndUpdateParameters()

◆ exchangeWithTimeout()

◆ findParameter()

◆ getMappedParameterValues()

◆ getParametersFromDevice()

◆ getPdoMappingStatus()

◆ getPosition()

◆ getServerInfo()

◆ getSocketAddress()

◆ getState()

◆ incrementSeqId()

◆ isConnected()

◆ isOnline()

◆ loadParameters()

◆ parameters()

◆ performProcessDataExchangeAsync()

◆ readFile()

◆ readFileList()

◆ readSdo()

◆ readSdoBatch() [1/2]

◆ readSdoBatch() [2/2]

◆ readSdoBatchAndUpdateParameters()

◆ refresher()

◆ removeFile()

◆ setPdoMode()

◆ setState()

◆ triggerFirmwareUpdate()

◆ updateFirmware()

◆ upload() [1/2]

◆ upload() [2/2]

◆ writeFile()

◆ writeSdo()