Represents a slave in the EtherCAT network. More...

#include <soempp.h>

Public Member Functions
	Slave (ecx_contextt &context, uint16_t position)
	Constructs a Slave object with a given context and position. More...

uint16_t	getPosition () const
	Gets the position of the slave. More...

uint32_t	getVendorId () const
	Gets the Vendor ID of the slave device. More...

uint32_t	getProductCode () const
	Gets the Product Code of the slave device. More...

uint32_t	getRevisionNumber () const
	Gets the Revision Number of the slave device. More...

int	getState (bool forceRefresh=true) const
	Retrieves the current state of the slave. More...

bool	setState (int targetState, int timeoutMs=0, int intervalMs=100)
	Attempts to set the slave to the specified EtherCAT state and optionally waits until it is reached. More...

void	loadParameters (bool readValues=false)
	Loads the parameters (object dictionary entries) from the EtherCAT slave device. More...

void	logParameters () const
	Logs all loaded object dictionary parameters. More...

void	logRxPdoMappedParameters ()
	Logs all mapped RxPDO parameters with their current values. More...

void	logTxPdoMappedParameters ()
	Logs all mapped TxPDO parameters with their current values. More...

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

std::unordered_map< common::ParameterKey, common::Parameter > &	getParametersMap ()
	Returns a reference to the internal parameters map. More...

common::Parameter &	findParameter (uint16_t index, uint8_t subindex)
	Finds and returns a reference to a Parameter in the parameters map. More...

template<typename T = std::vector<uint8_t>>
T	upload (uint16_t index, uint8_t subindex, bool refresh=true)
	Uploads a parameter value from the device's object dictionary. More...

template<typename T = std::vector<uint8_t>>
bool	download (uint16_t index, uint8_t subindex, const T &value)
	Downloads a value to the specified object dictionary entry via SDO. More...

common::PdoMappings	readPdoMappings () const
	Reads the PDO mappings from the slave device. More...

void	updatePdoMappings ()
	Updates the PDO mapping entries for the slave. More...

void	logPdoMappings () const
	Logs the PDO (Process Data Object) mappings for the device. More...

common::PdoMappings &	getPdoMappings ()
	Returns a reference to the cached PDO mappings. More...

void	updateOutputs ()
	Updates the outputs for the slave device. More...

void	updateParametersFromInputs ()
	Updates parameters from the received input data. More...

Detailed Description

Represents a slave in the EtherCAT network.

Constructor & Destructor Documentation

◆ Slave()

soempp::Slave::Slave	(	ecx_contextt &	context,
		uint16_t	position
	)

explicit

Constructs a Slave object with a given context and position.

This constructor initializes the Slave object with a provided context and position, which are used for further operations involving the slave.

Parameters

context	A reference to the `ecx_contextt` structure that contains the context for the EtherCAT communication.
position	The position of the slave in the EtherCAT network.

Member Function Documentation

◆ clearParameters()

void soempp::Slave::clearParameters ( )

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.

◆ download()

template<typename T = std::vector<uint8_t>>

bool soempp::Slave::download	(	uint16_t	index,
		uint8_t	subindex,
		const T &	value
	)

inline

Downloads a value to the specified object dictionary entry via SDO.

This templated function allows writing either raw byte data or typed values (e.g., int32_t, float) to a device's object dictionary. If a typed value is provided, it is first converted to its raw byte representation using the parameter model.

The function verifies that the device is in a state that allows SDO access, performs value-to-bytes conversion if necessary, and then sends the data using an SDO write operation. The trySetValue() method is used for typed values to serialize them into the appropriate byte format.

Template Parameters

T	The type of value to write. Defaults to std::vector<uint8_t> if not specified.

Parameters

index	The index of the object dictionary entry.
subindex	The subindex of the object within the dictionary.
value	The value to write, either as raw bytes or a typed variant.

Returns: true if the write was successful; false if value conversion failed or SDO write failed.

Exceptions

std::runtime_error if the device is in an invalid state or if the data size does not match the expected size of the parameter.

◆ findParameter()

common::Parameter & soempp::Slave::findParameter	(	uint16_t	index,
		uint8_t	subindex
	)

Finds and returns a reference to a Parameter in the parameters map.

This function searches for a parameter in the parametersMap_ using the provided index and subindex. If the parameter is found, a reference to it is returned. If the parameter is not found, an exception is thrown.

Parameters

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

Returns: A reference to the found Parameter.

Exceptions

std::runtime_error If the parameter is not found in the map.

◆ getParametersMap()

std::unordered_map< common::ParameterKey, common::Parameter > & soempp::Slave::getParametersMap ( )

Returns a reference to the internal parameters map.

Provides direct access to the map of parameters, where each entry is identified by a pair of index and subindex.

Returns: Reference to the parameters map.

◆ getPdoMappings()

common::PdoMappings & soempp::Slave::getPdoMappings ( )

Returns a reference to the cached PDO mappings.

Returns: Reference to the internal PDO mappings of the slave device.

◆ getPosition()

uint16_t soempp::Slave::getPosition ( ) const

Gets the position of the slave.

This method returns the position of the slave, which is stored in the position_ member variable.

Returns: uint16_t The position of the slave.

◆ getProductCode()

uint32_t soempp::Slave::getProductCode ( ) const

Gets the Product Code of the slave device.

This function retrieves the Product Code stored in the EEPROM of the slave device at the current position in the slave list.

Returns: The Product Code as an integer.

◆ getRevisionNumber()

uint32_t soempp::Slave::getRevisionNumber ( ) const

Gets the Revision Number of the slave device.

This function retrieves the Revision Number stored in the EEPROM of the slave device at the current position in the slave list.

Returns: The Revision Number as an integer.

◆ getState()

int soempp::Slave::getState ( bool forceRefresh = true ) const

Retrieves the current state of the slave.

This method calls getSlaveState to fetch the state of the slave based on its context and position. The function is const because it doesn't modify any internal state of the Slave object.

Parameters

forceRefresh If true, the state is re-read from the slave hardware.

Returns: int The current state of the slave.

◆ getVendorId()

uint32_t soempp::Slave::getVendorId ( ) const

Gets the Vendor ID of the slave device.

This function retrieves the Vendor ID stored in the EEPROM of the slave device at the current position in the slave list.

Returns: The Vendor ID as an integer.

◆ loadParameters()

void soempp::Slave::loadParameters ( bool readValues = false )

Loads the parameters (object dictionary entries) from the EtherCAT slave device.

This function reads the object dictionary (OD) of the slave device and populates the internal parametersMap_ with discovered entries. It first verifies that no parameters have been loaded before and ensures that the slave is in the PRE-OPERATIONAL state. It then reads the object dictionary list and entry details using SOEM API calls (ecx_readODlist, ecx_readODdescription, and ecx_readOE).

Parameters

readValues If true, the function reads SDO values from the slave.

Exceptions

std::runtime_error

if:

Parameters are already loaded.
The device is not in the PRE-OPERATIONAL state.
Reading the object dictionary list or entries fails.

Object entries are added to parametersMap_, each uniquely identified by a pair of index and subindex.

◆ logParameters()

void soempp::Slave::logParameters ( ) const

Logs all loaded object dictionary parameters.

This function retrieves all parameters stored in the parametersMap_, sorts them by index and subindex, and then logs each parameter's details, including its index, subindex, bit length, access type, and name. The parameters are logged in a sorted order with a sequence number for easy identification.

Note: The parameters are sorted before being logged, ensuring that the output is consistent and easy to interpret.

◆ logPdoMappings()

void soempp::Slave::logPdoMappings ( ) const

Logs the PDO (Process Data Object) mappings for the device.

This function logs the mapped RxPDO (Receive PDO) and TxPDO (Transmit PDO) entries for the device. The mappings are retrieved from the pdoMappings_ object, and the entries are logged using the logPdoMappingEntries function.

Note: The function first logs the RxPDO mappings followed by the TxPDO mappings.

◆ logRxPdoMappedParameters()

void soempp::Slave::logRxPdoMappedParameters ( )

Logs all mapped RxPDO parameters with their current values.

This function iterates through the RxPDO mappings, retrieves the corresponding parameter values, and logs them in the format parameterId=value, all in one line.

The log entry contains the device position, the number of RxPDO mappings, and the list of parameter IDs and their values. The output is formatted as:

Device [position]: RxPDO mapped parameters ([size]): [parameterId1=value1] [parameterId2=value2] ...

Note: The log output is a single line, with parameters separated by spaces.

◆ logTxPdoMappedParameters()

void soempp::Slave::logTxPdoMappedParameters ( )

Logs all mapped TxPDO parameters with their current values.

This function iterates through the TxPDO mappings, retrieves the corresponding parameter values, and logs them in the format parameterId=value, all in one line.

The log entry contains the device position, the number of TxPDO mappings, and the list of parameter IDs and their values. The output is formatted as:

Device [position]: TxPDO mapped parameters ([size]): [parameterId1=value1] [parameterId2=value2] ...

Note: The log output is a single line, with parameters separated by spaces.

◆ readPdoMappings()

common::PdoMappings soempp::Slave::readPdoMappings ( ) const

Reads the PDO mappings from the slave device.

This function logs the operation, reads the PDO mappings, and returns the retrieved mappings.

Returns: The PDO mappings of the slave device.

◆ setState()

bool soempp::Slave::setState	(	int	targetState,
		int	timeoutMs = `0`,
		int	intervalMs = `100`
	)

Attempts to set the slave to the specified EtherCAT state and optionally waits until it is reached.

This function first sends a request to change the slave's state to targetState. If timeoutMs is greater than 0, it repeatedly checks the current state at intervals of intervalMs milliseconds, up to the specified timeout.

Parameters

targetState	The desired EtherCAT state to set (e.g., EC_STATE_OPERATIONAL).
timeoutMs	Maximum time to wait (in milliseconds) for the slave to reach the target state. Default is 0 (no waiting).
intervalMs	Interval (in milliseconds) between state checks when waiting. Default is 100.

Returns: true if the slave state was successfully set and (if waiting) confirmed, false otherwise.

◆ updateOutputs()

void soempp::Slave::updateOutputs ( )

Updates the outputs for the slave device.

This function iterates through the received PDO (Process Data Object) mappings and updates the output data based on the corresponding parameters from the slave's context. The data is copied from the parameters to the output buffer in the slave's context. The size of each data entry is determined based on the bitlength of the PDO mapping, and the data is copied into the output buffer using std::memcpy.

The function works by calculating the size of each PDO mapping, finding the corresponding parameter in the slave's context, and copying the parameter's data into the appropriate location in the output buffer.

Note: The function assumes that the pdoMappings_.rxPdos is properly initialized and that the slave's context contains valid parameters for each entry in the mappings.

See also: findParameter

Returns: void

◆ updateParametersFromInputs()

void soempp::Slave::updateParametersFromInputs ( )

Updates parameters from the received input data.

This function iterates through the transmitted PDO (Process Data Object) mappings and updates the parameters with the corresponding data from the slave's input buffer. The data is copied from the input buffer into the parameters using std::memcpy. The size of each entry is determined based on the bitlength of the PDO mapping.

The function works by calculating the size of each PDO mapping, finding the corresponding parameter in the slave's context, and copying the data from the input buffer into the parameter's data structure.

Note: The function assumes that the pdoMappings_.txPdos is properly initialized and that the slave's context contains valid parameters for each entry in the mappings.

See also: findParameter

Returns: void

◆ updatePdoMappings()

void soempp::Slave::updatePdoMappings ( )

Updates the PDO mapping entries for the slave.

This function reads the current PDO mappings using readPdoMappings() and replaces the contents of the existing rxPdos and txPdos vectors in the referenced pdoMappings_ object. The reference itself remains unchanged, ensuring consistency for other components that may rely on it.

◆ upload()

template<typename T = std::vector<uint8_t>>

T soempp::Slave::upload	(	uint16_t	index,
		uint8_t	subindex,
		bool	refresh = `true`
	)

inline

Uploads a parameter value from the device's object dictionary.

This function reads the value of the specified parameter identified by its index and subindex from the EtherCAT slave device. If refresh is set to true, an SDO read will be issued to obtain the most recent value from the device. The parameter is returned either as its raw byte representation (std::vector<uint8_t>) or converted to a requested type T if supported by the parameter's variant.

Template Parameters

T	The expected return type. Defaults to `std::vector<uint8_t>`. If a different type is specified, the internal variant value is extracted and cast to `T`. A `std::bad_variant_access` exception is thrown if the types are incompatible.

Parameters

index	The index of the object in the object dictionary.
subindex	The subindex of the object in the object dictionary.
refresh	If true (default), refreshes the parameter by performing an SDO read from the device.

Returns: The parameter value as type T.

Exceptions

std::runtime_error	if the device is in an invalid state.
std::runtime_error	if the SDO read fails.
std::bad_variant_access	if the parameter cannot be cast to type `T`.

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

libs/soempp/soempp.h
libs/soempp/soempp.cc

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Slave()

Member Function Documentation

◆ clearParameters()

◆ download()

◆ findParameter()

◆ getParametersMap()

◆ getPdoMappings()

◆ getPosition()

◆ getProductCode()

◆ getRevisionNumber()

◆ getState()

◆ getVendorId()

◆ loadParameters()

◆ logParameters()

◆ logPdoMappings()

◆ logRxPdoMappedParameters()

◆ logTxPdoMappedParameters()

◆ readPdoMappings()

◆ setState()

◆ updateOutputs()

◆ updateParametersFromInputs()

◆ updatePdoMappings()

◆ upload()