# Raw command transfer

## emTferSingleRawCmd

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatTferSingleRawCmd([EC_T_CMD](#_CPPv48EC_T_CMD) eCmd, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMemoryAddress, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emTferSingleRawCmd([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_CMD](#_CPPv48EC_T_CMD) eCmd, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMemoryAddress, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Transfers a single raw EtherCAT command to one or multiple slaves and waits for the result. 

Using this function it is possible to exchange arbitrary data between the master and the slaves. When the master receives the response to the queued frame it raises EC_NOTIFY_RAWCMD_DONE to all clients. This function blocks until the command is completely processed. In case of read commands the slave data will be written back into the given memory area. If a timeout occurs (e.g. due to a bad line quality) the corresponding frame will be sent again. The timeout value and retry counter can be set using the master configuration parameters dwEcatCmdTimeout and dwEcatCmdMaxRetries. The call will return in any case (without waiting for the number of retries specified in dwEcatCmdMaxRetries) if the time determined with the dwTimeout parameter elapsed. Caveat: Using auto increment addressing (APRD, APWR, APRW) may lead to unexpected results in case the selected slave does not increment the working counter. In such cases the EtherCAT command would be handled by the slave directly behind the selected one. This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **eCmd** – [in] EtherCAT command type. See EC_T_CMD 
  * **dwMemoryAddress** – [in] Slave memory address, depending on the command to be sent this is either a physical or a logical address 
  * **pbyData** – [in, out] Buffer containing or receiving transferred data 
  * **wLen** – [in] Number of bytes to transfer 
  * **dwTimeout** – [in] Timeout [ms] 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the command is not supported or the timeout value is set to EC_NOWAIT
  * [EC_E_TIMEOUT](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2d09527654c655e159d26d36143674cb) if dwTimeout elapsed during the API call
  * [EC_E_BUSY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7c1a3a6dafef1469c97b8e6c4f3868a5) if another transfer request is already pending or the master or the corresponding slave is currently changing its operational state
  * [EC_E_NOTREADY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga4033f6f3b33aa2550d6e46e808a92f37) if the working counter was not set when sending the command (slave may not be connected or did not respond)
  * [EC_E_INVALIDSIZE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gacd9f0baea7a294f85c3f5bde1543d1d0) if the size of the complete command does not fit into a single Ethernet frame. The maximum amount of data to transfer must not exceed 1486 bytes.
  * [EC_E_MASTER_RED_STATE_INACTIVE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive 

The following EtherCAT® commands are supported:

- `eRawCmd_APRD`        Auto Increment Physical Read (avoid to use, see below)
- `eRawCmd_APWR`        Auto Increment Physical Write (avoid to use, see below)
- `eRawCmd_APRW`        Auto Increment Physical Read/Write (avoid to use, see below)
- `eRawCmd_FPRD`        Fixed addressed Physical Read
- `eRawCmd_FPWR`        Fixed addressed Physical Write
- `eRawCmd_FPRW`        Fixed addressed Physical Read/Write
- `eRawCmd_BRD` Broadcast (wire or’ed) Read
- `eRawCmd_BWR` Broadcast Write
- `eRawCmd_BRW` Broadcast Read/Write
- `eRawCmd_LRD` Logical Read
- `eRawCmd_LWR` Logical Write
- `eRawCmd_LRW` Logical Read/Write
- `eRawCmd_ARMW`        Auto Increment Physical Read, multiple Write

## emClntSendRawMbx

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatClntSendRawMbx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClntId, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyMbxCmd, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxCmdLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emClntSendRawMbx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClntId, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyMbxCmd, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxCmdLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Send a raw mailbox command. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwClntId** – [in] Client ID 
  * **pbyMbxCmd** – [in] Buffer containing the raw mailbox command starting with mailbox header 
  * **dwMbxCmdLen** – [in] Length of pbyMbxCmd buffer 
  * **dwTimeout** – [in] Timeout [ms] 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emClntQueueRawCmd

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatClntQueueRawCmd([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClntId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wInvokeId, [EC_T_CMD](#_CPPv48EC_T_CMD) eCmd, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMemoryAddress, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emClntQueueRawCmd([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClntId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wInvokeId, [EC_T_CMD](#_CPPv48EC_T_CMD) eCmd, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMemoryAddress, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen)

Transfers a raw EtherCAT command to one or multiple slaves. 

Using this function it is possible to exchange data between the master and the slaves. When the response to the queued frame is received, the notification EC_NOTIFY_RAWCMD_DONE is given for the appropriate client. This function queues a single EtherCAT command. Queued raw commands will be sent after sending cyclic process data values. If a timeout occurs the corresponding frame will be sent again, the timeout value and retry counter can be set using the master configuration parameters [EC_T_INIT_MASTER_PARMS.dwEcatCmdTimeout](api_general_functions.html.md#dc/dcc/struct_e_c___t___i_n_i_t___m_a_s_t_e_r___p_a_r_m_s_1ac53b5f0ab983baef942bcbfa4c17f7eb) and [EC_T_INIT_MASTER_PARMS.dwEcatCmdMaxRetries](api_general_functions.html.md#dc/dcc/struct_e_c___t___i_n_i_t___m_a_s_t_e_r___p_a_r_m_s_1a705d8cfa755a7e864038c8884ca0111d)

.

Using auto increment addressing (APRD, APWR, APRW) may lead to unexpected results in case the selected slave does not increment the working counter. In such cases the EtherCAT command would be handled by the slave directly behind the selected one. This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwClntId** – [in] Client ID to be notified (0 if all registered clients shall be notified) 
  * **wInvokeId** – [in] Invoke ID to reassign the results to the sent CMD 
  * **eCmd** – [in] EtherCAT command 
  * **dwMemoryAddress** – [in] Slave memory address, depending on the command to be sent this is either a physical or a logical address 
  * **pbyData** – [in, out] Buffer containing or receiving transferred data. In case a read-only command is queued (e.g. APRD) this pointer should be set to a value of EC_NULL. 
  * **wLen** – [in] Number of bytes to transfer 
* **Returns:**
  * [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful
  * [EC_E_INVALIDSTATE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or the command is not supported
  * [EC_E_BUSY](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga7c1a3a6dafef1469c97b8e6c4f3868a5) if the master or the corresponding slave is currently changing its operational state
  * [EC_E_INVALIDSIZE](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1gacd9f0baea7a294f85c3f5bde1543d1d0) if the size of the complete command does not fit into a single Ethernet frame. The maximum amount of data to transfer must not exceed 1486 bytes. 

The following EtherCAT® commands are supported:

### enum EC_T_CMD

*Values:*

### enumerator eEcatCmd_NOP

No operation 

### enumerator eEcatCmd_APRD

Auto increment physical read 

### enumerator eEcatCmd_APWR

Auto increment physical write 

### enumerator eEcatCmd_APRW

Auto increment physical read write 

### enumerator eEcatCmd_FPRD

Configured address physical read 

### enumerator eEcatCmd_FPWR

Configured address physical write 

### enumerator eEcatCmd_FPRW

Configured address physical read write 

### enumerator eEcatCmd_BRD

Broadcast read 

### enumerator eEcatCmd_BWR

Broadcast write 

### enumerator eEcatCmd_BRW

Broadcast read write 

### enumerator eEcatCmd_LRD

Logical memory read 

### enumerator eEcatCmd_LWR

Logical memory write 

### enumerator eEcatCmd_LRW

Logical memory read write 

### enumerator eEcatCmd_ARMW

Auto increment physical read multiple write 

### enumerator eEcatCmd_FRMW

Configured address physical read multiple write 

### enumerator eEcatCmd_EXT

## emQueueRawCmd

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatQueueRawCmd([EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wInvokeId, [EC_T_CMD](#_CPPv48EC_T_CMD) eCmd, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMemoryAddress, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emQueueRawCmd([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wInvokeId, [EC_T_CMD](#_CPPv48EC_T_CMD) eCmd, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMemoryAddress, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen)

Transfers a raw EtherCAT command to one or multiple slaves. 

All registered clients will be notified. This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **wInvokeId** – [in] Invoke ID to reassign the results to the sent CMD 
  * **eCmd** – [in] EtherCAT command 
  * **dwMemoryAddress** – [in] Slave memory address, depending on the command to be sent this is either a physical or a logical address 
  * **pbyData** – [in, out] Buffer containing or receiving transferred data. In case a read-only command is queued (e.g. APRD) this pointer should be set to a value of EC_NULL. 
  * **wLen** – [in] Number of bytes to transfer 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`emClntQueueRawCmd()`](#_CPPv417emClntQueueRawCmd10EC_T_DWORD10EC_T_DWORD9EC_T_WORD8EC_T_CMD10EC_T_DWORDP9EC_T_BYTE9EC_T_WORD)

## emNotify - EC_NOTIFY_RAWCMD_DONE

This notification is given when the response to an [`emTferSingleRawCmd()`](#_CPPv418emTferSingleRawCmd10EC_T_DWORD8EC_T_CMD10EC_T_DWORDP9EC_T_BYTE9EC_T_WORD10EC_T_DWORD) or [`emClntQueueRawCmd()`](#_CPPv417emClntQueueRawCmd10EC_T_DWORD10EC_T_DWORD9EC_T_WORD8EC_T_CMD10EC_T_DWORDP9EC_T_BYTE9EC_T_WORD) is received.

**emNotify - EC_NOTIFY_RAWCMD_DONE**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_RAWCMDRESPONSE_NTFY_DESC
    * `dwInBufSize`: [in] Size of the input buffer provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

### struct EC_T_RAWCMDRESPONSE_NTFY_DESC

### Public Members

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInvokeId

[in] Invoke Id from callee. Only lower 16 bits are relevant 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwResult

[in] EC_E_NOERROR on success, error code otherwise 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwWkc

[in] Received working counter 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCmdIdx

[in] Command Index Field 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwAddr

[in] Address Field 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLength

[in] Length of data portion (11 relevant bits) 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData

[in] Pointer to data portion within a PDU. The callback function has to store the data into application memory, the data pointer will be invalid after returning from the callback.