4.4. Process Data Access Functions

4.4.1. esGetProcessImageInputPtr

EC_T_BYTE *esGetProcessImageInputPtr(EC_T_DWORD dwInstanceID)

Gets the process data input image pointer.

Parameters

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

Returns

Process data input image pointer

See also

4.4.2. esGetProcessImageOutputPtr

EC_T_BYTE *esGetProcessImageOutputPtr(EC_T_DWORD dwInstanceID)

Gets the process data output image pointer.

Parameters

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

Returns

Process data output image pointer

See also

4.4.3. EC_COPYBITS

EC_COPYBITS(pbyDst, nDstBitOffs, pbySrc, nSrcBitOffs, nBitSize)

Copies a block of bits from a source buffer to a destination buffer.

Note

The memory buffers must be allocated before. The buffers must be big enough to hold the block starting at the given offsets! The buffers are not checked for overrun.

Parameters
  • pbyDst – [out] Destination buffer

  • nDstBitOffs – [in] Bit offset within destination buffer

  • pbySrc – [in] Source buffer

  • nSrcBitOffs – [in] Bit offset within source buffer

  • nBitSize – [in] Block size in bits

EC_T_BYTE pbySrc[] = {0xF4, 0xED, 0x69, 0xA5};
EC_T_BYTE pbyDst[] = {0x00, 0x00, 0x00, 0x00};
EC_COPYBITS(pbyDst, 3, pbySrc, 6, 22);

/* pbyDst now contains 0xB8 0x3C 0xAC 0x00 */

4.4.4. EC_GET_FRM_WORD

EC_GET_FRM_WORD(ptr)

Reads a value of type EC_T_WORD (16 bit) at given pointer. The value is swapped on big endian systems.

Parameters
  • ptr – [in] Source buffer

Returns

EC_T_WORD value (16 bit) from buffer.

EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_WORD wResult = 0;

wResult = EC_GET_FRM_WORD(byFrame);
/* wResult is 0xF401 on little endian systems */

wResult = EC_GET_FRM_WORD(byFrame + 5);
/* wResult is 0x6000 on little endian systems */

wResult = EC_GET_FRM_WORD(byFrame + 2);
/* wResult is 0x85DD on little endian systems */

4.4.5. EC_GET_FRM_DWORD

EC_GET_FRM_DWORD(ptr)

Reads a value of type EC_T_DWORD (32 bit) at given pointer. The value is swapped on big endian systems.

Parameters
  • ptr – [in] Source buffer

Returns

EC_T_DWORD value (32 bit) from buffer.

EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_DWORD dwResult = 0;

dwResult = EC_GET_FRM_DWORD(byFrame);
/* dwResult is 0x85DDF401 on little endian systems */

dwResult = EC_GET_FRM_DWORD(byFrame + 5);
/* dwResult is 0x00C16000 on little endian systems */

dwResult = EC_GET_FRM_DWORD(byFrame + 2);
/* dwResult is 0x000385DD on little endian systems */

4.4.6. EC_GET_FRM_QWORD

EC_GET_FRM_QWORD(ptr)

Reads a value of type EC_T_QWORD (64 bit) at given pointer. The value is swapped on big endian systems.

Parameters
  • ptr – [in] Source buffer

Returns

EC_T_QWORD value (64 bit) from buffer.

EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_UINT64 ui64Result = 0;

ui64Result = EC_GET_FRM_QWORD(byFrame + 1);
/* wResult is 0x00C160000385DDF4 on little endian systems */

4.4.7. EC_SET_FRM_WORD

EC_SET_FRM_WORD(ptr, w)

Writes a value of type EC_T_WORD (16 bit) at given pointer. The value is swapped on big endian systems.

Parameters
  • ptr – [in] Destination buffer

  • w – [in] 16 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_WORD(byFrame + 1, 0x1234);
/* byFrame = FF 34 12 FF FF FF ... */

4.4.8. EC_SET_FRM_DWORD

EC_SET_FRM_DWORD(ptr, dw)

Writes a value of type EC_T_DWORD (32 bit) at given pointer. The value is swapped on big endian systems.

Parameters
  • ptr – [in] Destination buffer

  • dw – [in] 32 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_DWORD(byFrame + 1, 0x12345678);
/* byFrame = FF 78 56 34 12 FF ... */

4.4.9. EC_SET_FRM_QWORD

EC_SET_FRM_QWORD(ptr, qw)

Writes a value of type EC_T_QWORD (64 bit) at given pointer. The value is swapped on big endian systems.

Parameters
  • ptr – [in] Destination buffer

  • qw – [in] 64 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_QWORD(byFrame + 1, 0xFEDCBA9876543210);
/* byFrame = FF 10 32 54 76 98 BA DC FE FF FF ... */

4.4.10. EC_GETBITS

EC_GETBITS(pbySrcBuf, pbyDstData, nSrcBitOffs, nBitSize)

Reads a given number of bits from source buffer starting at given bit offset to destination buffer.

Note

This function should be only used to get bit-aligned data. For byte-aligned data the corresponding functions should be used.

Parameters
  • pbySrcBuf – [in] Source buffer to be copied

  • pbyDstData – [out] Destination buffer where data is copied to

  • nSrcBitOffs – [in] Source bit offset where data is copied from

  • nBitSize – [in] Bit count to be copied

4.4.11. EC_SETBITS

EC_SETBITS(pbyDstBuf, pbySrcData, nDstBitOffs, nBitSize)

Writes a given number of bits from source data starting at first bit to destination buffer at given bit offset.

Note

This function should be only used to set bit-aligned data. For byte-aligned data the corresponding functions should be used.

Parameters
  • pbyDstBuf – [out] Destination buffer where data is copied to

  • pbySrcData – [in] Source buffer to be copied, starting with first bit

  • nDstBitOffs – [in] Destination bit offset where data is copied to

  • nBitSize – [in] Bit count to be copied

4.4.12. esGetProcessData

EC_T_DWORD esGetProcessData(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)

Retrieve Process data synchronized.

If process data are required outside the cyclic master job task (which is calling ecatExecJob), direct access to the process data is not recommended as data consistency cannot be guaranteed. A call to this function will send a data read request to the master stack and then check every millisecond whether new data are provided. The master stack will provide new data after calling ecatExecJob(eUsrJob_ MasterTimer) within the job task. This function is usually only called remotely (using the Remote API).

Note

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

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

  • bOutputData – [in] EC_TRUE: read output data, EC_FALSE: read input data.

  • dwOffset – [in] Byte offset in Process data to read from.

  • pbyData – [out] Buffer receiving transfered data

  • dwDataLen – [in] Buffer length [bytes]

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

4.4.13. esSetProcessData

EC_T_DWORD esSetProcessData(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)

Write Process data synchronized.

If process data shall be set outside the cyclic master job task (which is calling ecatExecJob), direct access to the process data is not recommended as data consistency cannot be guaranteed. A call to this function will send a data write request to the master stack and then check every millisecond whether new data is written. The master stack will copy the data after calling ecatExecJob(eUsrJob_ MasterTimer) within the job task. This function is usually only called remotely (using the Remote API).

Note

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

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

  • bOutputData – [in] EC_TRUE: write output data, EC_FALSE: write input data.

  • dwOffset – [in] Byte offset in Process data to write to.

  • pbyData – [in] Buffer containing transfered data

  • dwDataLen – [in] Buffer length [bytes]

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

4.4.14. esSetProcessDataBits

EC_T_DWORD esSetProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyData, EC_T_DWORD dwDataBitLen, EC_T_DWORD dwTimeout)

Writes a specific number of bits from a given buffer to the process image with a bit offset (synchronized).

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

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

  • bOutputData – [in] EC_TRUE: write output data, EC_FALSE: write input data.

  • dwBitOffsetPd – [in] Bit offset in Process data image.

  • pbyData – [in] Buffer containing transfered data

  • dwDataBitLen – [in] Buffer length [bit]

  • dwTimeout – [in] Timeout [ms] The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

4.4.15. esGetProcessDataBits

EC_T_DWORD esGetProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyData, EC_T_DWORD dwDataBitLen, EC_T_DWORD dwTimeout)

Reads a specific number of bits from the process image to the given buffer with a bit offset (synchronized).

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

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

  • bOutputData – [in] EC_TRUE: read output data, EC_FALSE: write input data.

  • dwBitOffsetPd – [in] Bit offset in Process data image.

  • pbyData – [out] Buffer receiving transfered data

  • dwDataBitLen – [in] Buffer length [bit]

  • dwTimeout – [in] Timeout [ms] The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code