Control and Status Ports

Control Port

The realtime port ecat-control-port provides control commands as RPC services.

The following services are available:

Service	Request	Response	Description
Restart	-	-	Request a restart (in case of error)
ContinueWithError	-		Continue with error (recovery mode)
RequestMasterState	requestedState (uint32)	-	Request an EtherCAT state

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.

See State Machine for more details about the commands.

Status Port

The realtime 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	uint32	Current EtherCAT master state (INIT, PREOP, …).
CycleCount	uint64	Number of status port updates since startup.
CycleStartTime	uint64	Cycle start timestamp in nanoseconds (since realtime-port timestamp clock epoch).
SystemState	enum/uint32	Current system state. See State Machine for details.

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 realtime 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

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).