6.10. Automation Device Specification over EtherCAT (AoE)

The AoE protocol is used to access the Object dictionary of slave devices of underlying field-buses, e.g. for a CAN application protocol Slave connected to a EtherCAT-CANopen gateway device. It is also used in relation with the EtherCAT Automation Protocol (EAP).

Reference:

  • ETG.1020 -> AoE

Current limitations

  • Fragmented AoE access is not yet implemented

6.10.1. emAoeGetSlaveNetId

static EC_T_DWORD ecatAoeGetSlaveNetId(EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poAoeNetId)
EC_T_DWORD emAoeGetSlaveNetId(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poAoeNetId)

Retrieve the NetID of a specific EtherCAT device.

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

  • dwSlaveId – [in] Slave ID

  • poAoeNetId – [out] AoE NetID of the corresponding slave

Returns

EC_E_NOERROR or error code

struct EC_T_AOE_NETID

Public Members

EC_T_BYTE aby[6]

AoE net id

See also

emGetSlaveId()

6.10.2. emAoeRead

static EC_T_DWORD ecatAoeRead(EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwDataLen, EC_T_BYTE *pbyData, EC_T_DWORD *pdwDataOutLen, EC_T_DWORD *pdwErrorCode, EC_T_DWORD *pdwCmdResult, EC_T_DWORD dwTimeout)
EC_T_DWORD emAoeRead(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwDataLen, EC_T_BYTE *pbyData, EC_T_DWORD *pdwDataOutLen, EC_T_DWORD *pdwErrorCode, EC_T_DWORD *pdwCmdResult, EC_T_DWORD dwTimeout)

Execute a AoE mailbox read request to an EtherCAT slave device.

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

  • poTargetNetId – [in] Target NetID.

  • wTargetPort – [in] Target port.

  • dwIndexGroup – [in] AoE read command index group.

  • dwIndexOffset – [in] AoE read command index offset

  • dwDataLen – [in] Buffer length [bytes]

  • pbyData – [out] Buffer receiving transfered data

  • pdwDataOutLen – [out] Number of bytes read from the target device

  • pdwErrorCode – [out] AoE response error code

  • pdwCmdResult – [out] AoE read command result code

  • dwTimeout – [in] Timeout [ms] The function will block at most for this time.

Returns

6.10.3. emAoeReadReq

static EC_T_DWORD ecatAoeReadReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwTimeout)
EC_T_DWORD emAoeReadReq(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwTimeout)

Execute a non-blocking AoE mailbox read request to an EtherCAT slave device.

If the functions returns EC_E_AOE_DEVICE_XXXX (well known device errors) or EC_E_AOE_VENDOR_SPECIFIC the original ADS error can be retrieved from the mailbox transfer object at EC_T_MBXTFER.MbxData.AoE_Response. A unique transfer ID must be written into EC_T_MBXTFER.dwTferId.

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

  • pMbxTfer – [in] Mailbox transfer object

  • dwSlaveId – [in] Slave ID

  • poTargetNetId – [in] Target NetID.

  • wTargetPort – [in] Target port.

  • dwIndexGroup – [in] AoE read command index group

  • dwIndexOffset – [in] AoE read command index offset

  • dwTimeout – [in] Timeout [ms]

Returns

struct EC_T_AOE_CMD_RESPONSE

Public Members

EC_T_DWORD dwErrorCode

AoE response error code

EC_T_DWORD dwCmdResult

AoE command result code

See also

emGetSlaveId()

6.10.4. emNotify - eMbxTferType_AOE_READ

emNotify - eMbxTferType_AOE_READ
Parameter
  • pbyInBuf: [in] pMbxTfer - Pointer to a structure of type EC_T_MBXTFER, this structure contains the used mailbox transfer object. This mailbox transfer object also contains AoE device error codes in case of an AoE access error.

  • dwInBufSize: [in] Size of the transfer object.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

See also

emAoeReadReq()

6.10.5. emAoeWrite

static EC_T_DWORD ecatAoeWrite(EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwDataLen, EC_T_BYTE *pbyData, EC_T_DWORD *pdwErrorCode, EC_T_DWORD *pdwCmdResult, EC_T_DWORD dwTimeout)
EC_T_DWORD emAoeWrite(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwDataLen, EC_T_BYTE *pbyData, EC_T_DWORD *pdwErrorCode, EC_T_DWORD *pdwCmdResult, EC_T_DWORD dwTimeout)

Execute a AoE mailbox write request to an EtherCAT slave device.

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

  • poTargetNetId – [in] Target NetID.

  • wTargetPort – [in] Target port.

  • dwIndexGroup – [in] AoE write command index group.

  • dwIndexOffset – [in] AoE write command index offset

  • dwDataLen – [in] Buffer length [bytes]

  • pbyData – [in] Buffer containing transfered data

  • pdwErrorCode – [out] Pointer to AoE response error code.

  • pdwCmdResult – [out] Pointer to AoE write command result code.

  • dwTimeout – [in] Timeout [ms] The function will block at most for this time.

Returns

6.10.6. emAoeWriteReq

static EC_T_DWORD ecatAoeWriteReq(EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwTimeout)
EC_T_DWORD emAoeWriteReq(EC_T_DWORD dwInstanceID, EC_T_MBXTFER *pMbxTfer, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwTimeout)

Execute a non-blocking AoE mailbox write request to an EtherCAT slave device.

If the functions returns EC_E_AOE_DEVICE_XXXX (well known device errors) or EC_E_AOE_VENDOR_SPECIFIC the original ADS error can be retrieved from the mailbox transfer object at EC_T_MBXTFER.MbxData.AoE_Response. A unique transfer ID must be written into EC_T_MBXTFER.dwTferId.

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

  • pMbxTfer – [in] Mailbox transfer object

  • dwSlaveId – [in] Slave ID

  • poTargetNetId – [in] Target NetID.

  • wTargetPort – [in] Target port.

  • dwIndexGroup – [in] AoE write command index group.

  • dwIndexOffset – [in] AoE write command index offset

  • dwTimeout – [in] Timeout [ms]

Returns

See also

emGetSlaveId()

6.10.7. emNotify - eMbxTferType_AOE_WRITE

emNotify - eMbxTferType_AOE_WRITE
Parameter
  • pbyInBuf: [in] pMbxTfer - Pointer to a structure of type EC_T_MBXTFER, this structure contains the used mailbox transfer object. This mailbox transfer object also contains AoE device error codes in case of an AoE access error.

  • dwInBufSize: [in] Size of the transfer object.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

See also

emAoeWriteReq()

6.10.8. emAoeReadWrite

static EC_T_DWORD ecatAoeReadWrite(EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwReadDataLen, EC_T_DWORD dwWriteDataLen, EC_T_BYTE *pbyData, EC_T_DWORD *pdwDataOutLen, EC_T_DWORD *pdwErrorCode, EC_T_DWORD *pdwCmdResult, EC_T_DWORD dwTimeout)
EC_T_DWORD emAoeReadWrite(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_DWORD dwIndexGroup, EC_T_DWORD dwIndexOffset, EC_T_DWORD dwReadDataLen, EC_T_DWORD dwWriteDataLen, EC_T_BYTE *pbyData, EC_T_DWORD *pdwDataOutLen, EC_T_DWORD *pdwErrorCode, EC_T_DWORD *pdwCmdResult, EC_T_DWORD dwTimeout)

Execute a AoE mailbox read/write request to an EtherCAT slave device.

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

  • dwSlaveId – [in] Slave ID

  • poTargetNetId – [in] Target NetID.

  • wTargetPort – [in] Target port.

  • dwIndexGroup – [in] AoE read/write command index group.

  • dwIndexOffset – [in] AoE read/write command index offset

  • dwReadDataLen – [in] Number of bytes to read from the target device.

  • dwWriteDataLen – [in] Number of bytes to read from the target device.

  • pbyData – [in, out] Buffer containing and receiving transfered data

  • pdwDataOutLen – [out] Number of bytes read from the target device

  • pdwErrorCode – [out] Pointer to AoE response error code.

  • pdwCmdResult – [out] Pointer to AoE write command result code.

  • dwTimeout – [in] Timeout [ms] The function will block at most for this time. EC_NOWAIT is not valid.

Returns

See also

emGetSlaveId()

6.10.9. emAoeWriteControl

static EC_T_DWORD ecatAoeWriteControl(EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_WORD wAoEState, EC_T_WORD wDeviceState, EC_T_DWORD dwDataLen, EC_T_BYTE *pbyData, EC_T_DWORD *pdwErrorCode, EC_T_DWORD *pdwCmdResult, EC_T_DWORD dwTimeout)
EC_T_DWORD emAoeWriteControl(EC_T_DWORD dwInstanceID, EC_T_DWORD dwSlaveId, EC_T_AOE_NETID *poTargetNetId, EC_T_WORD wTargetPort, EC_T_WORD wAoEState, EC_T_WORD wDeviceState, EC_T_DWORD dwDataLen, EC_T_BYTE *pbyData, EC_T_DWORD *pdwErrorCode, EC_T_DWORD *pdwCmdResult, EC_T_DWORD dwTimeout)

Execute a AoE mailbox write control request to an EtherCAT slave device.

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

  • dwSlaveId – [in] Slave ID

  • poTargetNetId – [in] Target NetID. The Target NetID of a AoE slave device can be retrieved by ecatAoeGetSlaveNetId()..

  • wTargetPort – [in] Target port.

  • wAoEState – [in] AoE state

  • wDeviceState – [in] Device specific state

  • dwDataLen – [in] Buffer length [bytes]

  • pbyData – [in] Buffer containing transfered data

  • pdwErrorCode – [out] Pointer to AoE response error code.

  • pdwCmdResult – [out] Pointer to AoE write command result code.

  • dwTimeout – [in] Timeout [ms] The function will block at most for this time. EC_NOWAIT is not valid.

Returns

See also

emGetSlaveId()

6.10.10. emConvertEcErrorToAdsError

EC_T_DWORD ecatConvertEcErrorToAdsError(EC_T_DWORD dwErrorCode)
EC_T_DWORD emConvertEcErrorToAdsError(EC_T_DWORD dwInstanceID, EC_T_DWORD dwErrorCode)

Convert master error code to AoE error code.

Returns

AoE error code