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 if successful
EC_E_INVALIDSTATE if master isn’t initialized
EC_E_INVALIDPARM if dwInstanceID is out of range, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
EC_E_SLAVE_NOT_PRESENT if slave not present
EC_E_NOTFOUND if no slave matching dwSlaveId can be found
EC_E_NO_MBX_SUPPORT if slave has no mailbox support
EC_E_ADS_IS_RUNNING if ADS server is running

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

EC_E_NOERROR
EC_E_AOE_VENDOR_SPECIFIC: will be returned in case the AoE device has responded with an user defined error code
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

See also

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

EC_E_NOERROR
EC_E_AOE_VENDOR_SPECIFIC: will be returned in case the AoE device has responded with an user defined error code
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

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

EC_E_NOERROR
EC_E_AOE_VENDOR_SPECIFIC: will be returned in case the AoE device has responded with an user defined error code
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

See also

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

EC_E_NOERROR
EC_E_AOE_VENDOR_SPECIFIC: will be returned in case the AoE device has responded with an user defined error code
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

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

EC_E_NOERROR
EC_E_AOE_VENDOR_SPECIFIC: will be returned in case the AoE device has responded with an user defined error code
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

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

EC_E_NOERROR
EC_E_AOE_VENDOR_SPECIFIC: will be returned in case the AoE device has responded with an user defined error code
EC_E_MASTER_RED_STATE_INACTIVE if Master Redundancy is configured and master is inactive

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