Control and Status Ports

Control Port

The real-time port ecat-control-port provides control commands as RPC services.

The following services are available:

Service	Request	Response	Description
Reset	-		Acknowledge the error and return to CONFIG. See Reset for details.
RequestMasterState	requestedState (enum/uint32)	-	Request an EtherCAT state (INIT, PREOP, SAFEOP or OP). See RequestMasterState for details.

The following response codes may be returned by the services:

Code	Name	Description
0	SUCCESS	The request was successful.
100	INVALID_REQUEST	The requested EtherCAT Master state is invalid.
101	INVALID_STATE	The request is not possible/allowed in the current state.
202	INTERNAL_ERROR	An unexpected error occurred in the service implementation.
1000	COMMUNICATION_FAULTS_STILL_PRESENT	The reset was refused because the communication fault counter is not zero.

See State Machine for more details about the commands.

EtherCAT States

Values of requestedState and of the status variable MasterState. NONE is only published, it cannot be requested. BOOT exists only for slaves, the master never reports or accepts it.

Value	Name
0	NONE
1	INIT
2	PREOP
3	BOOT
4	SAFEOP
8	OP

Status Port

The real-time port ecat-status-port provides current system and master status information as output variables. The following variables are available:

Name	Type	Description
ErrorNumber	uint32	Current error number (0 = no error).
ErrorMessage	string (max 256)	Human-readable error message corresponding to ErrorNumber.
MasterState	enum/uint32	Current EtherCAT master state, see EtherCAT States.
CycleCount	uint64	Number of status port updates since startup.
CycleStartTime	uint64	Cycle start timestamp in nanoseconds (since the voraus Real-Time Port timestamp clock epoch).
SystemState	enum/uint32	Current system state. See State Machine for details.
CyclicFaultIndicator	uint32	Indicator for cyclic communication faults, see Cyclic Communication Faults.

Note: the status port will always be updated last (after all PDO ports were updated) and will emit a notification in each cycle. Therefore the status port’s notifications can be used to synchronize user applications to the EtherCAT cycle.

SDO Port

The real-time port ecat-sdo-port provides acyclic SDO read/write access as RPC services. Multiple read/write request can be processed concurrently. The responses will be buffered until polled.

The following services are available:

Service	Request	Response	Description
StartSdoWrite	StartSdoWriteRequest	StartSdoWriteResponse	Start an SDO download
PollSdoWrite	PollSdoWriteRequest	PollSdoWriteResponse	Poll SDO download status
StartSdoRead	StartSdoReadRequest	StartSdoReadResponse	Start an SDO upload
PollSdoRead	PollSdoReadRequest	PollSdoReadResponse	Poll SDO upload status

Slave indices are 0-based. Start requests for a slaveIndex that is not part of the ENI configuration are rejected with INVALID_REQUEST.

The request/response structs contain the following members:

StartSdoWriteRequest

Member	Type	Description
slaveIndex	uint32	Target slave index in the EtherCAT network.
index	uint16	SDO object index.
subIndex	uint8	SDO object subindex.
timeoutMs	uint32	Request timeout in milliseconds.
dataLength	uint32	Number of payload bytes to write from data.
data	uint8[]	Write payload buffer.

StartSdoWriteResponse

Member	Type	Description
requestId	uint64	Identifier of the started write request.

PollSdoWriteRequest

Member	Type	Description
requestId	uint64	Identifier returned by start call.

PollSdoWriteResponse

Member	Type	Description
done	bool	True when the write request has finished.
success	bool	True when the write finished without SDO error.
abortCode	uint32	SDO abort code (valid when success is false).

StartSdoReadRequest

Member	Type	Description
slaveIndex	uint32	Target slave index in the EtherCAT network.
index	uint16	SDO object index.
subIndex	uint8	SDO object subindex.
size	uint32	Maximum number of bytes to read.
timeoutMs	uint32	Request timeout in milliseconds.

StartSdoReadResponse

Member	Type	Description
requestId	uint64	Identifier of the started read request.

PollSdoReadRequest

Member	Type	Description
requestId	uint64	Identifier returned by start call.

PollSdoReadResponse

Member	Type	Description
done	bool	True when the read request has finished.
success	bool	True when the read finished without SDO error.
abortCode	uint32	SDO abort code (valid when success is false).
dataLength	uint32	Number of valid bytes in data.
data	uint8[]	Read payload buffer.

The data array capacity is configured via the sdo-max-payload-size application option.

Note: the SDO port is updated from the acyclic EtherCAT thread (non-RT).