Abstract interface representing a generic device. More...

#include <base.h>

Inheritance diagram for mm::comm::base::Device:

Public Member Functions
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

Abstract interface representing a generic device.

This class defines the virtual interface for device operations such as state management, parameter handling, and file transfer. All methods are pure virtual and must be implemented by derived classes.

Constructor & Destructor Documentation

◆ ~Device()

virtual mm::comm::base::Device::~Device ( )

virtualdefault

Virtual destructor for Device interface.

Ensures derived class destructors are called properly when deleting through a pointer to Device.

The default destructor implementation is used.

Reimplemented in mm::comm::spoe::Device.

Member Function Documentation

◆ clearParameters()

virtual void mm::comm::base::Device::clearParameters ( )

pure virtual

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.

Implemented in mm::comm::spoe::Device.

◆ download() [1/2]

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

pure virtual

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.

Implemented in mm::comm::spoe::Device.

◆ download() [2/2]

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

pure virtual

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.

Implemented in mm::comm::spoe::Device.

◆ exchangeProcessDataAndUpdateParameters()

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

pure virtual

Exchanges process data with the remote device and updates local parameters accordingly.

This function prepares the process data to send by collecting the current data from parameters mapped as RxPDOs. It then sends this data and receives updated process data from the remote device. The received data is used to update local parameters mapped as TxPDOs.

Parameters

missedCycles Number of cycles missed since the last call.

Implemented in mm::comm::spoe::Device.

◆ findParameter()

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

pure virtual

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.

Implemented in mm::comm::spoe::Device.

◆ getPdoMappingStatus()

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

pure virtual

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.

Implemented in mm::comm::spoe::Device.

◆ getPosition()

virtual uint16_t mm::comm::base::Device::getPosition ( ) const

pure virtual

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.

Implemented in mm::comm::spoe::Device.

◆ getState()

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

pure virtual

Reads and returns the current state of the device.

This function sends a request to retrieve the device’s state, which follows the EtherCAT state machine. The returned state is represented as a uint8_t with the following possible values:

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

Parameters

refresh	If true, forces a refresh of the device state.
expiryTime	The maximum time to wait for the operation to complete.

Returns: The current device state as a uint8_t.

Implemented in mm::comm::spoe::Device.

◆ isOnline()

virtual bool mm::comm::base::Device::isOnline ( )

pure virtual

Checks if the device is online.

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

Implemented in mm::comm::spoe::Device.

◆ loadParameters()

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

pure virtual

Loads parameters from the device and stores them locally.

Parameters

readValues	If true, the values of the parameters are read from the device; otherwise, only the parameter metadata is retrieved.
expiryTime	The maximum duration to wait for the operation to complete.

Returns: The number of loaded parameters.

Implemented in mm::comm::spoe::Device.

◆ parameters()

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

pure virtual

Get a vector of references to parameters.

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

Implemented in mm::comm::spoe::Device.

◆ readFile()

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

pure virtual

Reads the contents of a file from the device.

Sends a read request to the device and waits for a response within the specified timeout duration. The file may be transferred in multiple segments and is assembled internally.

Parameters

filename	The name of the file to read.
expiryTime	The maximum duration to wait for the operation to complete. Defaults to 5000 milliseconds.

Returns: A vector containing the file contents. May be empty if the file exists but has no data.

Implemented in mm::comm::spoe::Device.

◆ readFileList()

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

pure virtual

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.

Implemented in mm::comm::spoe::Device.

◆ removeFile()

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

pure virtual

Removes a file from the device.

Parameters

filename	The name of the file to be removed.
expiryTime	The maximum duration to wait for the operation to complete. Defaults to 5000 milliseconds.

Implemented in mm::comm::spoe::Device.

◆ setState()

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

pure virtual

Sets the device to a specified state.

Attempts to change the remote device's state to the given value, waiting up to the specified expiry time for the operation to complete.

Parameters

state	The new state to set on the remote device.
expiryTime	The maximum duration to wait for the operation to complete.

Returns: true if the state was successfully set; false otherwise.

Implemented in mm::comm::spoe::Device.

◆ updateFirmware()

virtual void mm::comm::base::Device::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)`
	)

pure virtual

Updates the device firmwares.

Parameters

data	The firmware package zip file data to be written to the device.
skipFiles	A list of file names to skip during the update process. This allows excluding specific files from the update.
progressCallback	An optional callback function that receives progress updates during the firmware update process.
expiryTime	The maximum duration to wait for the operation to complete. Defaults to 60000 milliseconds.

Implemented in mm::comm::spoe::Device.

◆ upload()

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

pure virtual

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.

Implemented in mm::comm::spoe::Device, and mm::comm::spoe::Device.

◆ writeFile()

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

pure virtual

Sends a file to the device.

Parameters

filename	The name of the file to be written.
data	The data to be written to the file.
expiryTime	The maximum duration to wait for the operation to complete. Defaults to 5000 milliseconds.

Returns: Returns DeviceFileError::None if the file was successfully written. Otherwise, returns the appropriate error code indicating the reason for failure.

Implemented in mm::comm::spoe::Device.

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

libs/comm/base.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Device()

Member Function Documentation

◆ clearParameters()

◆ download() [1/2]

◆ download() [2/2]

◆ exchangeProcessDataAndUpdateParameters()

◆ findParameter()

◆ getPdoMappingStatus()

◆ getPosition()

◆ getState()

◆ isOnline()

◆ loadParameters()

◆ parameters()

◆ readFile()

◆ readFileList()

◆ removeFile()

◆ setState()

◆ updateFirmware()

◆ upload()

◆ writeFile()