6.13. Servo Drive Profil according to IEC61491 over EtherCAT (SoE)

The SoE Service Channel (SSC) is equivalent to the IEC61491 Service Channel used for non-cyclic data exchange. The SSC uses the EtherCAT mailbox mechanism. It allows accessing IDNs and their elements.

For extended informations about SoE see the IEC IEC61800-7-300 document 22G185eFDIS.

Following services are available:

  • Write IDN:

    With emSoeWrite() the data and elements of an IDN which are writeable can be written.

  • Read IDN:

    With emSoeRead() the data and elements of an IDN can be read.

  • Procedure command Execution:

    With emSoeWrite() also procedure commands can be started. Procedure commands are special IDNs, which invokes fixed functional processes. When proceeding is finished, a notification will be received. To abort a running command execution emSoeAbortProcCmd() has to be called.

  • Notification:

    In case of an notification all registered clients will get this notification. A notification will be received when proceeding of a command has finished. To register a client emRegisterClient() must be called.

  • Emergency:

    The main purpose of this service is to provide additional information about the slave for debugging and maintenance. In case of an emergency, all registered clients will get notified. To register a client emRegisterClient() must be called.

Abbreviations:

  • IDN:

    identification number: Designation of operating data under which a data block is preserved with its attribute, name, unit, minimum and maximum input values, and the data.

  • SoE:

    IEC 61491 Servo drive profile over EtherCAT (SoE)

  • SSC:

    SoE Service Channel (non-cyclic data exchange)

6.13.1. SoE ElementFlags

With the ElementFlags each element of an IDN can be addressed. The ElementFlags indicating which elements of an IDN are read or written. The ElementFlags indicating which data will be transmitted in the SoE data buffer.

SOE_BM_ELEMENTFLAG_DATATSTATE

Shall be set in case of Notify SoE Service Channel Command Execution

SOE_BM_ELEMENTFLAG_NAME

Name of operation data. The name consist of 64 octets maximum

SOE_BM_ELEMENTFLAG_ATTRIBUTE

Attribute of operation data. The attribute contain all information which is needed to display operation data intelligibly

SOE_BM_ELEMENTFLAG_UNIT

Unit of operation data

SOE_BM_ELEMENTFLAG_MIN

The IDN minimum input value shall be the smallest numerical value for the operation data which the slave is able to process

SOE_BM_ELEMENTFLAG_MAX

The IDN maximum input value shall be the largest numerical value for the operation data which the slave is able to process

SOE_BM_ELEMENTFLAG_VALUE

Operation data

SOE_BM_ELEMENTFLAG_DEFAULT

The IDN default value

6.13.2. SoE IDN coding

The parameter addressing area consist of 4096 different standard IDNs, each with 8 parameter sets and 4096 manufacturer specific IDNs, each with 8 parameter sets.

The Control unit cycle time (TNcyc) which is an standard IDN S-0-0001 equates to wIDN = 0x1 The first manufacturer specific IDN P-0-0001 equates to wIDN = 0x8001

6.13.3. emSoeWrite

static EC_T_DWORD ecatSoeWrite(EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIDN, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)
EC_T_DWORD emSoeWrite(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIdn, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)

Execute a SoE SSC Write service which download data to an EtherCAT slave device.

The function returns after timeout expired or download is completed successfully (Write response is received). It can also perform a SoE SSC Procedure Command. After a procedure command has started, the slave generates a normal SSC Write Response, and the function returns. If the data to be sent with the write service exceeds the mailbox size, the data will be sent fragmented. The fragmented write operation consists of several Write SSC Fragment Services. Therefore the selected Timeout should be increasing with the count of fragments. This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • dwSlaveId – [in] Slave ID

  • byDriveNo – [in] Drive number to address inside slave device

  • pbyElementFlags – [in/out] SoE ElementFlags. Flag indicating elements to address

  • wIdn – [in] IDN of the object to address

  • pbyData – [in] Buffer containing transfered data

  • dwDataLen – [in] Buffer length [byte]

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

emGetSlaveId()

6.13.4. emSoeWriteReq

Requests an SoE SSC Write and returns immediately.

static EC_T_DWORD ecatSoeWriteReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIDN, EC_T_DWORD dwTimeout)
EC_T_DWORD emSoeWriteReq(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIdn, EC_T_DWORD dwTimeout)

Requests an SoE SSC Write and returns immediately.

This function may be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • pMbxTfer – [in] Mailbox transfer object

  • dwSlaveId – [in] Slave ID

  • byDriveNo – [in] Drive number to address inside slave device

  • pbyElementFlags – [in/out] SoE ElementFlags. Flag indicating elements to address

  • wIdn – [in] IDN of the object to address

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

6.13.5. emSoeRead

static EC_T_DWORD ecatSoeRead(EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIDN, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD *pdwOutDataLen, EC_T_DWORD dwTimeout)
EC_T_DWORD emSoeRead(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIdn, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD *pdwOutDataLen, EC_T_DWORD dwTimeout)

Execute a SoE SCC Read service which upload data from an EtherCAT SoE slave device.

The received data can resist of several fragments. The reserved data buffer (pbyData) must have space for all received data segments and the selected Timeout should be increasing with the count of fragments.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • dwSlaveId – [in] Slave ID

  • byDriveNo – [in] Drive number to address inside slave device

  • pbyElementFlags – [in/out] SoE ElementFlags. Flag indicating elements to address

  • wIdn – [in] IDN of the object to address

  • pbyData – [out] Buffer receiving transfered data

  • dwDataLen – [in] Buffer length [byte]

  • pdwOutDataLen – [out] Length of received data [byte]

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

emGetSlaveId()

6.13.6. emSoeReadReq

static EC_T_DWORD ecatSoeReadReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIDN, EC_T_DWORD dwTimeout)
EC_T_DWORD emSoeReadReq(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIdn, EC_T_DWORD dwTimeout)

Requests an SoE SSC Read and returns immediately.

This function may be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • pMbxTfer – [in] Mailbox transfer object

  • dwSlaveId – [in] Slave ID

  • byDriveNo – [in] Drive number to address inside slave device

  • pbyElementFlags – [in/out] SoE ElementFlags. Flag indicating elements to address

  • wIdn – [in] IDN of the object to address

  • dwTimeout – [in] Timeout [ms] Must not be set to EC_NOWAIT

Returns

EC_E_NOERROR or error code

See also

6.13.7. emSoeAbortProcCmd

static EC_T_DWORD ecatSoeAbortProcCmd(EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIDN, EC_T_DWORD dwTimeout)
EC_T_DWORD emSoeAbortProcCmd(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_BYTE byDriveNo, EC_T_BYTE *pbyElementFlags, EC_T_WORD wIdn, EC_T_DWORD dwTimeout)

Abort SSC Procedure Command sequence.

A Procedure Command take up some time. After a procedure command has started, the slave generates a normal SSC Write Response. The end of a procedure command is indicated by the Notify SSC Command Execution Service.

Note

This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • dwSlaveId – [in] Slave ID

  • byDriveNo – [in] Drive number to address inside slave device

  • pbyElementFlags – [in/out] SoE ElementFlags. Flag indicating elements to address

  • wIdn – [in] IDN of the object to address

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

See also

emGetSlaveId()

6.13.8. emConvertEcErrorToSoeError

EC_T_DWORD ecatConvertEcErrorToSoeError(EC_T_DWORD dwErrorCode)
EC_T_DWORD emConvertEcErrorToSoeError(EC_T_DWORD dwInstanceID, EC_T_DWORD dwErrorCode)

Convert master error code to SoE error code.

Returns

SoE error code

6.13.9. emNotify - EC_NOTIFY_SOE_MBXSND_WKC_ERROR

This error will be indicated in case the working counter of a SoE mailbox write command was not set to the expected value of 1. Detailed error information is stored in structure EC_T_WKCERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.

6.13.10. emNotify - EC_NOTIFY_SOE_WRITE_ERROR

This error will be indicated in case SoE mailbox write command responded with an error. Detailed error information is stored in structure EC_T_INITCMD_ERR_DESC of EC_T_ERROR_NOTIFICATION_DESC.