# index.html.md
# EtherCAT® Master Stack Class B
# api_busscan.html.md
# EtherCAT® Bus Scan
The acontis EtherCAT® MainDevice stack supports scanning the EtherCAT® Bus to determine which SubDevices are available. If a configuration was provided the connected SubDevices are validated against the given ENI.
#### SEE ALSO
[`emScanBus()`](api_general_functions.html.md#_CPPv49emScanBus10EC_T_DWORD10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SB_ENABLE
### EC_IOCTL_SB_ENABLE
Enables Busscan support.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to Timeout Parameter Value [ms] (EC_T_DWORD). Timeout Parameter is used for timeout during Bus Topology determination.
* **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
* **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
The bus scan support is enabled by default.
## emIoCtl - EC_IOCTL_SB_RESTART
### EC_IOCTL_SB_RESTART
Start scanning the network (again). On completion the Notfication EC_NOTIFY_SB_STATUS is given.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
The timeout value given by [emIoCtl - EC_IOCTL_SB_ENABLE](api_busscan.html.md#emioctl-ec-ioctl-sb-enable) will be used.
This function may be called prior to running [`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD). In such a case a first bus scan will be executed before MainDevice configuration. This feature may be used to dynamically create or adjust the XML configuration file. When issuing this IoCtl, the application has to take care [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) is called cyclically to trigger MainDevice state machines, timers, send acyclic and receive frames accordingly.
## emIoCtl - EC_IOCTL_SB_STATUS_GET
### EC_IOCTL_SB_STATUS_GET
Get the status of the last bus scan.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Pointer to [EC_T_SB_STATUS_NTFY_DESC](api_busscan.html.md#d1/d72/struct_e_c___t___s_b___s_t_a_t_u_s___n_t_f_y___d_e_s_c)
* **dwOutBufSize** – [in] Size of the output buffer in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
[emNotify - EC_NOTIFY_SB_STATUS](api_busscan.html.md#emnotify-ec-notify-sb-status)
## emIoCtl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAY
### EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAY
Set the topology changed delay value. The master will wait this duration [ms] to react on appearing links in topology. The default value is 1000 ms.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_DWORD containing the delay information [ms]
* **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
* **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
## emIoCtl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAYS
### EC_IOCTL_SB_SET_TOPOLOGY_CHANGED_DELAYS
Set the topology changed delay values individually. The master will wait individual durations [ms] (0 ms: disabled) for slave ports, main link and red link to react on appearing links in topology. The default value is 1000 ms.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to [EC_T_TOPOLOGY_CHANGED_DELAYS](api_busscan.html.md#d8/d5c/struct_e_c___t___t_o_p_o_l_o_g_y___c_h_a_n_g_e_d___d_e_l_a_y_s) containing the delay durations [ms]
* **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
* **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
### struct EC_T_TOPOLOGY_CHANGED_DELAYS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlavePort
[in] Delay before opening slave port after link connection detected
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMainLine
[in] Delay before sending frames at main line after link connection detected
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRedLine
[in] Delay before sending frames at red line after link connection detected
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) adwReserved[5]
reserved
## emIoCtl - EC_IOCTL_SB_SET_ERROR_ON_CROSSED_LINES
### EC_IOCTL_SB_SET_ERROR_ON_CROSSED_LINES
Enable or disable bus mismatch if IN and OUT connectors are swapped. If enabled the swapped IN and OUT connectors will lead to bus mismatch. By default swapped IN and OUT connectors will lead to bus mismatch.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE swapped IN and OUT connectors will lead to bus mismatch, if set to EC_FALSE swapped IN and OUT connectors are tolerated.
* **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
* **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
## emIoCtl - EC_IOCTL_SB_SET_ERROR_ON_LINE_BREAK
### EC_IOCTL_SB_SET_ERROR_ON_LINE_BREAK
Enable or disable bus mismatch if a line is broken in a redundant network. If enabled, line breaks in cable or junction redundant networks will lead to bus mismatch.
#### NOTE
[EC_E_REDLINEBREAK](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_1gaccf988b91722079a5b6be82dc2e0beec): Line break in a cable redundant network.
#### NOTE
[EC_E_JUNCTION_RED_LINE_BREAK](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_1gaa5458e142909815b607221dda2bb018e): Line break in a junction redundant network.
#### NOTE
See EC_NOTIFY_SB_MISMATCH, EC_NOTIFY_SB_STATUS.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_BOOL: EC_TRUE: Enable, EC_FALSE: Disable. Default: Enabled.
* **dwInBufSize** – [in] Should be set to sizeof(EC_T_BOOL)
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
## emIoCtl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGE_AUTO_MODE
#### WARNING
This documentation is preliminary and is subject to change
### EC_IOCTL_SB_SET_TOPOLOGY_CHANGE_AUTO_MODE
Enable or disable the automatic topology change mode. By default the automatic mode is enabled.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE the automatic mode is enabled.
* **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
* **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
In automatic mode, new SubDevices will be discovered automatically. In manual mode, after new SubDevices have been connected, an [emNotify - EC_NOTIFY_HC_TOPOCHGDONE](api_busscan.html.md#emnotify-ec-notify-hc-topochgdone) notification will be given without opening the ports of the SubDevices on the bus. When the application is able to handle the new SubDevices, it should call [emIoCtl - EC_IOCTL_SB_ACCEPT_TOPOLOGY_CHANGE](api_busscan.html.md#emioctl-ec-ioctl-sb-accept-topology-change).
## emIoCtl - EC_IOCTL_SB_ACCEPT_TOPOLOGY_CHANGE
#### WARNING
This documentation is preliminary and is subject to change
### EC_IOCTL_SB_ACCEPT_TOPOLOGY_CHANGE
This call will trigger a scan bus for accept topology change (manual mode). On completion the Notfication EC_NOTIFY_SB_STATUS is given.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
This function may be called after an [emNotify - EC_NOTIFY_HC_TOPOCHGDONE](api_busscan.html.md#emnotify-ec-notify-hc-topochgdone) notification was given if the automatic topology change mode was previously disabled using [emIoCtl - EC_IOCTL_SB_SET_TOPOLOGY_CHANGE_AUTO_MODE](api_busscan.html.md#emioctl-ec-ioctl-sb-set-topology-change-auto-mode).
During this bus scan the ports of the SubDevices will (re)open and new SubDevices can be detected.
The timeout value given by [emIoCtl - EC_IOCTL_SB_ENABLE](api_busscan.html.md#emioctl-ec-ioctl-sb-enable) will be used. When issuing this IoCtl, the application has to take care [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) is called cyclically to trigger MainDevice state machines, timers, send acyc and receive frames accordingly.
## emNotify - EC_NOTIFY_SB_STATUS
Bus scan status notification.
This notification is enabled by default.
**emNotify - EC_NOTIFY_SB_STATUS**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SB_STATUS_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_SB_STATUS_NTFY_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwResultCode
[in] [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): success, [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): no bus scan executed, [EC_E_BUSCONFIG_MISMATCH](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_1ga613dd4e3b8cac7ac5193993f1afeaae6): bus configuration mismatch result of scanbus
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveCount
[in] Number of slaves connected to the bus
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
## emNotify - EC_NOTIFY_SB_MISMATCH
This notification will be initiated if a bus scan detects a mismatch of connected SubDevices and configuration, due to unexpected SubDevices or missing mandatory SubDevices.
**emNotify - EC_NOTIFY_SB_MISMATCH**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SB_MISMATCH_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
This notification is enabled by default. In case of permanent frame loss no SubDevices can be found although the SubDevices are connected.
### struct EC_T_SB_MISMATCH_DESC
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPrevFixedAddress
[in] Previous slave station address
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPrevPort
[in] Previous slave station address
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPrevAIncAddress
[in] Previous slave auto-increment address
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wBusAIncAddress
[in] Unexpected slave (bus) auto-inc address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBusVendorId
[in] Unexpected slave (bus) vendor ID
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBusProdCode
[in] Unexpected slave (bus) product code
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBusRevisionNo
[in] Unexpected slave (bus) revision number
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBusSerialNo
[in] Unexpected slave (bus) serial number
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wBusFixedAddress
[in] Unexpected slave (bus) station address
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIdentificationError
[in] Identification command sent to slave but failed
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIdentificationAdo
[in] Identification register
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIdentificationVal
[in] Last identification value read from slave according to the last used identification method
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIdentificationValExpected
[in] Identification expected value
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wCfgFixedAddress
[in] Missing slave (config) station Address
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wCfgAIncAddress
[in] Missing slave (config) Auto-Increment Address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCfgVendorId
[in] Missing slave (config) Vendor ID
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCfgProdCode
[in] Missing slave (config) Product code
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCfgRevisionNo
[in] Missing slave (config) Revision Number
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCfgSerialNo
[in] Missing slave (config) Serial Number
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
## emNotify - EC_NOTIFY_SB_DUPLICATE_HC_NODE
A bus mismatch was detected during the scan due to duplicated SubDevice(s).
The application receives this notification if there are two SubDevices on the network with the same product code, vendor ID and identification value (alias address or switch id).
**emNotify - EC_NOTIFY_SB_DUPLICATE_HC_NODE**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SB_MISMATCH_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
The members of [`EC_T_SB_MISMATCH_DESC`](api_busscan.html.md#_CPPv421EC_T_SB_MISMATCH_DESC) have the following meaning:
- [`EC_T_SB_MISMATCH_DESC::wCfgFixedAddress`](api_busscan.html.md#_CPPv4N21EC_T_SB_MISMATCH_DESC16wCfgFixedAddressE) Duplicated SubDevice (config) station Address
- [`EC_T_SB_MISMATCH_DESC::wCfgAIncAddress`](api_busscan.html.md#_CPPv4N21EC_T_SB_MISMATCH_DESC15wCfgAIncAddressE) Duplicated SubDevice (config) Auto-Increment Address.
- [`EC_T_SB_MISMATCH_DESC::dwCfgVendorId`](api_busscan.html.md#_CPPv4N21EC_T_SB_MISMATCH_DESC13dwCfgVendorIdE) Duplicated SubDevice (config) Vendor ID
- [`EC_T_SB_MISMATCH_DESC::dwCfgProdCode`](api_busscan.html.md#_CPPv4N21EC_T_SB_MISMATCH_DESC13dwCfgProdCodeE) Duplicated SubDevice (config) Product code
- [`EC_T_SB_MISMATCH_DESC::dwCfgRevisionNo`](api_busscan.html.md#_CPPv4N21EC_T_SB_MISMATCH_DESC15dwCfgRevisionNoE) Duplicated SubDevice (config) Revision Number
- [`EC_T_SB_MISMATCH_DESC::dwCfgSerialNo`](api_busscan.html.md#_CPPv4N21EC_T_SB_MISMATCH_DESC13dwCfgSerialNoE) Duplicated SubDevice (config) Serial Number
## emNotify - EC_NOTIFY_SLAVE_PRESENCE
This notification is given when a SubDevice appears or disappears from the network.
This notification is enabled by default.
**emNotify - EC_NOTIFY_SLAVE_PRESENCE**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SLAVE_PRESENCE_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
Disconnecting the SubDevice from the network, powering it off or a bad connection can produce this notification.
### struct EC_T_SLAVE_PRESENCE_NTFY_DESC
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress
Slave station address
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) bPresent
EC_TRUE: present, EC_FALSE: absent
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
## emNotify - EC_NOTIFY_SLAVES_PRESENCE
This notification collects notifications of the type [emNotify - EC_NOTIFY_SLAVE_PRESENCE](api_busscan.html.md#emnotify-ec-notify-slave-presence).
Notification is given either upon completion or when the MainDevice status is changed, whichever comes first.
Disconnecting SubDevices from the network, turning them off, or having a bad connection can lead to this notification.
This notification is disabled by default.
**emNotify - EC_NOTIFY_SLAVES_PRESENCE**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SLAVES_PRESENCE_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_SLAVES_PRESENCE_NTFY_DESC
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wCount
Number of slave presence notifications
### [EC_T_SLAVE_PRESENCE_NTFY_DESC](api_busscan.html.md#_CPPv429EC_T_SLAVE_PRESENCE_NTFY_DESC) SlavePresence[MAX_SLAVES_PRESENCE_NTFY_ENTRIES]
Slave presence descriptions
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled)
## emNotify - EC_NOTIFY_LINE_CROSSED
Cable swapping detected. All SubDevice’s port 0 must lead to MainDevice.
**emNotify - EC_NOTIFY_LINE_CROSSED**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_LINE_CROSSED_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_LINE_CROSSED_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wInputPort
Port where frame was received
## emNotify - EC_NOTIFY_SLAVE_NOTSUPPORTED
Is currently generated during Bus Scan if [`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD) (GenOp/Preop) and a wrong category type is detected in the EEPROM. This notification should only print a log message or be ignored (EC-Master print log message itself).
**emNotify - EC_NOTIFY_SLAVE_NOTSUPPORTED**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_ERROR_NOTIFICATION_DESC containing EC_T_SLAVE_NOTSUPPORTED_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_SLAVE_NOTSUPPORTED_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
## emNotify - EC_NOTIFY_FRAMELOSS_AFTER_SLAVE
Is currently generated and automatically handled during [`emRescueScan()`](api_general_functions.html.md#_CPPv412emRescueScan10EC_T_DWORD10EC_T_DWORD) if opening a port would lead to frame loss. This notification should only print a log message.
**emNotify - EC_NOTIFY_FRAMELOSS_AFTER_SLAVE**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_ERROR_NOTIFICATION_DESC containing EC_T_FRAMELOSS_AFTER_SLAVE_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_FRAMELOSS_AFTER_SLAVE_NTFY_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPort
Port
## emNotify - Bus Scan notifications for Feature Packs
The notifications `EC_NOTIFY_RED_LINEBRK`, `EC_NOTIFY_RED_LINEFIXED` belong to the Feature Pack Redundancy.
The notifications `EC_NOTIFY_HC_DETECTADDGROUPS`, `EC_NOTIFY_HC_PROBEALLGROUPS` belong to the Feature Pack Hot Connect.
## emIoCtl - EC_IOCTL_SB_NOTIFY_UNEXPECTED_BUS_SLAVES
### EC_IOCTL_SB_NOTIFY_UNEXPECTED_BUS_SLAVES
Enable or disable unexpected bus slaves notification.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE unexpected bus slaves on the network will be notified by EC_NOTIFY_SB_MISMATCH.
* **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
* **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
## emIsTopologyChangeDetected
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatIsTopologyChangeDetected([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*pbTopologyChangeDetected)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emIsTopologyChangeDetected([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*pbTopologyChangeDetected)
Returns whether topology change detected.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pbTopologyChangeDetected** – [out] Pointer to EC_T_BOOL value: EC_TRUE if Topology Change Detected, EC_FALSE if not
* **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
* [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
## emNotify - EC_NOTIFY_HC_TOPOCHGDONE
This notification is raised when a topology change was completely processed.
**emNotify - EC_NOTIFY_HC_TOPOCHGDONE**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_DWORD (EC_E_NOERROR on success, Error code otherwise)
* `dwInBufSize`: [in] sizeof(EC_T_DWORD)
* `pbyOutBuf`: [out] Should be set to EC_NULL
* `dwOutBufSize`: [in] Should be set to 0
* `pdwNumOutData`: [out] Should be set to EC_NULL
The notification is raised when the SubDevices have been detected and DC initialized.
## emIoCtl - EC_IOCTL_SB_SET_NO_DC_SLAVES_AFTER_JUNCTION
### EC_IOCTL_SB_SET_NO_DC_SLAVES_AFTER_JUNCTION
Declares that no DC slaves are located after junction.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE the hidden slave detection and the junction redundancy specific propagation delay measurement are not executed.
* **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
* **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
Calling this IOCTL if DC SubDevices are located in or after a junction redundancy segment will generate an undefined behavior.
# api_diagnosis.html.md
# Diagnosis, error detection, error notifications
In case of errors on the bus or in one or multiple SubDevices the EtherCAT® MainDevice stack will notify the application about such an event. The MainDevice automatically detects unexpected SubDevice states by evaluating the AL Status event interrupt. If the interrupt is set, the MainDevice reads the state of each SubDevice and compares it to the expected (required) state. In case of a state mismatch the MainDevice generates the notification [emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE](api_diagnosis.html.md#emnotify-ec-notify-slave-unexpected-state). The application will then have to enter an error handling procedure.
The error notifications can be separated into two classes:
1. SubDevice unrelated errors
2. SubDevice related errors
A SubDevice related error notification will also contain the information about which SubDevice has generated an error. If for example a SubDevice could not be set into the requested state the application will get the [emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-slave-initcmd-response-error) error notification including SubDevice related information. A SubDevice unrelated error does not contain this information even if one specific SubDevice caused the error. For example if one or multiple SubDevices are powered off the working counter of the cyclic commands would be wrong. In that case the [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) error notification will be generated.
**Example Error Scenario**
SubDevice is powered off or disconnected while bus is operational
If the MainDevice is operational it cyclically sends EtherCAT® commands to read and write the SubDevice’s process data. It expects the working counter to be incremented to the appropriate value. If one SubDevice is powered off the MainDevice will generate the [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) to indicate such an event. Also the MainDevice detects a DL status event and performs a bus scan as reaction on this. For the not reachable SubDevices (powered off or disconnected) the MainDevice generates the notification [emNotify - EC_NOTIFY_SLAVE_PRESENCE](api_busscan.html.md#emnotify-ec-notify-slave-presence).
A possible error recovery scenario would be to stay operational and in parallel wait until the SubDevice is powered on again. The next step would be to determine the SubDevice’s state and set it operational again:
MainDevice calls [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error)
: - Application gets informed
- WKC State in Diagnosis Image changes
#### SEE ALSO
[Working Counter (WKC) State in Diagnosis Image](software-integration_error-detection.html.md#working-counter-wkc-state-in-diagnosis-image)
**Use cases**
1. SubDevice is disconnected or powered off:
: - MainDevice detects a DL status event interrupt and performs a bus scan.
- MainDevice calls [emNotify - EC_NOTIFY_SLAVE_PRESENCE](api_busscan.html.md#emnotify-ec-notify-slave-presence).
- Application gets informed and could set the MainDevice including all SubDevices into a lower state, e.g. [`eEcatState_INIT`](api_general_functions.html.md#_CPPv4N10EC_T_STATE15eEcatState_INITE).
2. SubDevice state is not OPERATIONAL anymore
: - MainDevice calls [emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE](api_diagnosis.html.md#emnotify-ec-notify-slave-unexpected-state).
- Application gets informed and could either set the MainDevice including all SubDevices into a lower state (e.g. [`eEcatState_PREOP`](api_general_functions.html.md#_CPPv4N10EC_T_STATE16eEcatState_PREOPE)) or call [`emSetSlaveState()`](api_slave_control.html.md#_CPPv415emSetSlaveState10EC_T_DWORD10EC_T_DWORD9EC_T_WORD10EC_T_DWORD) to repair the failed SubDevice.
3. SubDevice is re-connected or powered on:
: - MainDevice detects a DL status event interrupt and performs a bus scan.
- MainDevice calls [emNotify - EC_NOTIFY_SLAVE_PRESENCE](api_busscan.html.md#emnotify-ec-notify-slave-presence).
- Application could wait until all SubDevices are re-connected by calling the functions [`emGetNumConnectedSlaves()`](api_slave_control.html.md#_CPPv423emGetNumConnectedSlaves10EC_T_DWORD) and [`emGetNumConfiguredSlaves()`](api_slave_control.html.md#_CPPv424emGetNumConfiguredSlaves10EC_T_DWORD).
- After all SubDevices are re-connected the application could either set the MainDevice including all SubDevices to [`eEcatState_INIT`](api_general_functions.html.md#_CPPv4N10EC_T_STATE15eEcatState_INITE) and afterwards to [`eEcatState_OP`](api_general_functions.html.md#_CPPv4N10EC_T_STATE13eEcatState_OPE), or the application uses [`emSetSlaveState()`](api_slave_control.html.md#_CPPv415emSetSlaveState10EC_T_DWORD10EC_T_DWORD9EC_T_WORD10EC_T_DWORD) to repair only the failed SubDevices.
## emSetLogParms
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetLogParms([EC_T_LOG_PARMS](api_general_functions.html.md#_CPPv414EC_T_LOG_PARMS) \*pLogParms)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetLogParms([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_LOG_PARMS](api_general_functions.html.md#_CPPv414EC_T_LOG_PARMS) \*pLogParms)
Sets log parameters. Used to change the parameters provided by [emInitMaster()](api_general_functions.html.md#db/d74/_ec_master_api_8cpp_1a20396c6311952930b2a5c10c2baf2131).
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pLogParms** – [in] New Log parameters
## emEthDbgMsg
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatEthDbgMsg([EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byEthTypeByte0, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byEthTypeByte1, [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szMsg)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emEthDbgMsg([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byEthTypeByte0, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byEthTypeByte1, [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szMsg)
Send a debug message to the EtherCAT Link Layer.
This feature can be used for debugging purposes.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **byEthTypeByte0** – [in] Ethernet type byte 0
* **byEthTypeByte1** – [in] Ethernet type byte 1
* **szMsg** – [in] Message to send to link layer
* **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
### **emEthDbgMsg() Example**
```cpp
EC_T_CHAR* szMsg = (EC_T_CHAR*)"Hello World";
EC_T_BYTE byEthTypeByte0 = 6;
EC_T_BYTE byEthTypeByte1 = 6;
/* send message as frame, validate given EtherType:
>= 1536: EtherType (supported as parameter),
<= 1500: size of payload (not supported as parameter),
1501-1535: undefined */
/* send debug message to EtherCAT Link Layer */
dwRes = emEthDbgMsg(dwInstanceId, byEthTypeByte0, byEthTypeByte1, szMsg);
```
## emIoCtl - EC_IOCTL_GET_SLVSTATISTICS
### EC_IOCTL_GET_SLVSTATISTICS
Get slave statistics showing errors on Ethernet layer for slave id. Statistics are read on a regular basis (default: off).
#### NOTE
See also EC_IOCTL_SET_SLVSTAT_PERIOD, EC_IOCTL_FORCE_SLVSTAT_COLLECTION, EC_IOCTL_GET_SLVSTAT_PERIOD
* **Parameters:**
* **pbyInBuf** – [in] Pointer to an EC_T_DWORD type variable containing the slave id
* **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes
* **pbyOutBuf** – [out] Pointer to struct [EC_T_SLVSTATISTICS_DESC](api_diagnosis.html.md#d6/dee/struct_e_c___t___s_l_v_s_t_a_t_i_s_t_i_c_s___d_e_s_c)
* **dwOutBufSize** – [in] Size of the output buffer provided at pbyOutBuf in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
### struct EC_T_SLVSTATISTICS_DESC
### Public Members
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyInvalidFrameCnt[ESC_PORT_COUNT]
[out] Invalid Frame Counters per Slave Port
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyRxErrorCnt[ESC_PORT_COUNT]
[out] RX Error Counters per Slave Port
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyFwdRxErrorCnt[ESC_PORT_COUNT]
[out] Forwarded RX Error Counters per Slave Port
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byProcessingUnitErrorCnt
[out] Processing Unit Error Counter
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byPdiErrorCnt
[out] PDI Error Counter
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAlStatusCode
[out] AL Status Code
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyLostLinkCnt[ESC_PORT_COUNT]
[out] Lost Link Counters per Slave Port
### EC_T_UINT64 qwReadTime
[out] Timestamp of the last read [ns]
### EC_T_UINT64 qwChangeTime
[out] Timestamp of the last counter change [ns]
#### SEE ALSO
- [emIoCtl - EC_IOCTL_SET_SLVSTAT_PERIOD](api_diagnosis.html.md#emioctl-ec-ioctl-set-slvstat-period)
- [emIoCtl - EC_IOCTL_CLR_SLVSTATISTICS](api_diagnosis.html.md#emioctl-ec-ioctl-clr-slvstatistics)
## emGetSlaveStatistics
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveStatistics([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_SLVSTATISTICS_DESC](api_diagnosis.html.md#_CPPv423EC_T_SLVSTATISTICS_DESC) \*pSlaveStatisticsDesc)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveStatistics([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_SLVSTATISTICS_DESC](api_diagnosis.html.md#_CPPv423EC_T_SLVSTATISTICS_DESC) \*pSlaveStatisticsDesc)
Get Slave’s statistics counter.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave id
* **pSlaveStatisticsDesc** – [out] Pointer to structure [EC_T_SLVSTATISTICS_DESC](api_diagnosis.html.md#d6/dee/struct_e_c___t___s_l_v_s_t_a_t_i_s_t_i_c_s___d_e_s_c)
* **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
### **emGetSlaveStatistics() Example**
```cpp
/* get slave's statistics counters */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_SLVSTATISTICS_DESC oSlaveStatisticsDesc;
OsMemset(&oSlaveStatisticsDesc, 0, sizeof(EC_T_SLVSTATISTICS_DESC));
dwRes = dwSlaveId;
dwRes = emGetSlaveStatistics(dwInstanceId, dwSlaveId, &oSlaveStatisticsDesc);
```
#### SEE ALSO
- [emIoCtl - EC_IOCTL_GET_SLVSTATISTICS](api_diagnosis.html.md#emioctl-ec-ioctl-get-slvstatistics)
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emIoCtl - EC_IOCTL_CLR_SLVSTATISTICS
### EC_IOCTL_CLR_SLVSTATISTICS
Clear slave statistics in slaves.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
## emClearSlaveStatistics
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatClearSlaveStatistics([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emClearSlaveStatistics([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId)
Clears all error registers of a slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave Id, INVALID_SLAVE_ID clears all slaves
* **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
### **emClearSlaveStatistics() Example**
```cpp
/* clear all error counters at slave */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
dwRes = emClearSlaveStatistics(dwInstanceId, dwSlaveId);
```
#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emIoCtl - EC_IOCTL_GET_SLVSTAT_PERIOD
### EC_IOCTL_GET_SLVSTAT_PERIOD
Get Slave Statistics read period [ms] (EC_T_DWORD). 0: disable.
#### NOTE
See EC_IOCTL_SET_SLVSTAT_PERIOD.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Slave Statistics read period [ms] (EC_T_DWORD)
* **dwOutBufSize** – [in] Size of the output buffer provided at pbyOutBuf in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
## emIoCtl - EC_IOCTL_SET_SLVSTAT_PERIOD
### EC_IOCTL_SET_SLVSTAT_PERIOD
Set Slave Statistics read period [ms] (EC_T_DWORD). 0: disable.
#### NOTE
Triggers an immediate read.
* **Parameters:**
* **pbyInBuf** – [in] Slave Statistics read period [ms] (EC_T_DWORD)
* **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
* **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
## emIoCtl - EC_IOCTL_FORCE_SLVSTAT_COLLECTION
### EC_IOCTL_FORCE_SLVSTAT_COLLECTION
Trigger slave statistics read.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
### **Checking RX Error / Lost Link Counters Example**
```cpp
/* check RX Error / Lost Link Counters of a slave's ports to spot a degrading cable or connector */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_SLVSTATISTICS_DESC oSlaveStatisticsDesc;
EC_T_DWORD dwPeriodMs = 1000;
EC_T_WORD wPort = 0;
/* enable cyclic background collection (or use EC_IOCTL_FORCE_SLVSTAT_COLLECTION for a one-shot read) */
dwRes = emIoCtl(dwInstanceId, EC_IOCTL_SET_SLVSTAT_PERIOD, &dwPeriodMs, sizeof(EC_T_DWORD), EC_NULL, 0, EC_NULL);
/* read the counters collected in background */
OsMemset(&oSlaveStatisticsDesc, 0, sizeof(EC_T_SLVSTATISTICS_DESC));
dwRes = emGetSlaveStatistics(dwInstanceId, dwSlaveId, &oSlaveStatisticsDesc);
/* inspect RX Error Counter and Lost Link Counter per SubDevice port */
for (wPort = 0; wPort < ESC_PORT_COUNT; wPort++)
{
if ((0 != oSlaveStatisticsDesc.abyRxErrorCnt[wPort]) || (0 != oSlaveStatisticsDesc.abyLostLinkCnt[wPort]))
{
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
"Slave 0x%08X, Port %d: RX Error Cnt = %d, Lost Link Cnt = %d\n",
dwSlaveId, wPort, oSlaveStatisticsDesc.abyRxErrorCnt[wPort], oSlaveStatisticsDesc.abyLostLinkCnt[wPort]));
}
}
/* clear counters so the next period reflects only new events */
dwRes = emClearSlaveStatistics(dwInstanceId, dwSlaveId);
```
#### SEE ALSO
- [emIoCtl - EC_IOCTL_GET_SLVSTATISTICS](api_diagnosis.html.md#emioctl-ec-ioctl-get-slvstatistics)
- [emIoCtl - EC_IOCTL_SET_SLVSTAT_PERIOD](api_diagnosis.html.md#emioctl-ec-ioctl-set-slvstat-period)
- [emIoCtl - EC_IOCTL_CLR_SLVSTATISTICS](api_diagnosis.html.md#emioctl-ec-ioctl-clr-slvstatistics)
## emIoCtl - EC_IOCTL_CLEAR_MASTER_INFO_COUNTERS
### EC_IOCTL_CLEAR_MASTER_INFO_COUNTERS
Reset Master Info Counters according to given bit masks.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to a value of [EC_T_CLEAR_MASTER_INFO_COUNTERS_PARMS](api_diagnosis.html.md#d6/dbd/struct_e_c___t___c_l_e_a_r___m_a_s_t_e_r___i_n_f_o___c_o_u_n_t_e_r_s___p_a_r_m_s)
* **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
* **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
### struct EC_T_CLEAR_MASTER_INFO_COUNTERS_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClearBusDiagnosisCounters
[in] Bit 0..7: Clear corresponding Counter ID:
* Bit 0: Clear all Counters
* Bit 1: Clear Tx Frame Counter
* Bit 2: Clear Rx Frame Counter
* Bit 3: Clear Lost Frame Counter
* Bit 4: Clear Cyclic Frame Counter
* Bit 5: Clear Cyclic Datagram Counter
* Bit 6: Clear Acyclic Frame Counter
* Bit 7: Clear Acyclic DataGram Counter
* Bit 8: Clear Cyclic Lost Frame Counter
* Bit 9: Clear Acyclic Lost Frame Counter
### EC_T_UINT64 qwMailboxStatisticsClearCounters
[in] Bit 0..56: Clear corresponding Counter ID.
* Bit 0..7: Clear AoE statistics
* Bit 0: Total Read Transfer Count
* Bit 1: Read Transfer Count Last Second
* Bit 2: Total Bytes Read
* Bit 3: Bytes Read Last Second
* Bit 4: Total Write Transfer Count
* Bit 5: Write Transfer Count Last Second
* Bit 6: Total Bytes Write
* Bit 7: Bytes Write Last Second
* Bit 8..15: Clear CoE statistics (same ordering as Bit 0..7, AoE)
* Bit 16..23: Clear EoE statistics (same ordering as Bit 0..7, AoE)
* Bit 24..31: Clear FoE statistics (same ordering as Bit 0..7, AoE)
* Bit 32..39: Clear SoE statistics (same ordering as Bit 0..7, AoE)
* Bit 40..47: Clear VoE statistics (same ordering as Bit 0..7, AoE)
* Bit 48..55: Clear RawMbx statistics (same ordering as Bit 0..7, AoE)
```cpp
qwMailboxStatisticsClearCounters = 0x0000000100; //Clear CoE Total Read Transfer Count.
```
## emIoCtl - EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK
### EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK
Enable or disable EC_NOTIFY_FRAME_RESPONSE_ERROR for specific errors.
#### NOTE
[EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_DEFAULT](api_diagnosis.html.md#d8/d77/group___e_c___f_r_a_m_e___r_e_s_p_o_n_s_e___e_r_r_o_r___n_o_t_i_f_y___m_a_s_k_s_1ga24dcc551c672dc8babeed5647677a582): all errors except [EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_NON_ECAT_FRAME](api_diagnosis.html.md#d8/d77/group___e_c___f_r_a_m_e___r_e_s_p_o_n_s_e___e_r_r_o_r___n_o_t_i_f_y___m_a_s_k_s_1ga00caa46266a61a51973a57a57c808119) enabled.
* **Parameters:**
* **pbyInBuf** – [in] Error enable bit mask (EC_T_DWORD)
* **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
* **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
The following frame response error notification mask values exist:
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_UNDEFINED
Mask for eRspErr_UNDEFINED notifications
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_NO_RESPONSE
Mask for eRspErr_NO_RESPONSE notifications
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_WRONG_IDX
Mask for eRspErr_WRONG_IDX notifications
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_UNEXPECTED
Mask for eRspErr_UNEXPECTED notifications
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_FRAME_RETRY
Mask for eRspErr_FRAME_RETRY notifications
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_RETRY_FAIL
Mask for eRspErr_RETRY_FAIL notifications
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_FOREIGN_SRC_MAC
Mask for eRspErr_FOREIGN_SRC_MAC notifications
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_NON_ECAT_FRAME
Mask for eRspErr_NON_ECAT_FRAME notifications
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_ALL
Mask for all notifications enabled except eRspErr_NON_ECAT_FRAME
### EC_FRAME_RESPONSE_ERROR_NOTIFY_MASK_DEFAULT
Mask for all frame response error notifications
#### SEE ALSO
[emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-frame-response-error)
## emIoCtl - EC_IOCTL_SET_FRAME_LOSS_SIMULATION
#### IMPORTANT
Do not activate this on shipped releases. Frameloss has significant influence on performance and reliablility of the application!
### EC_IOCTL_SET_FRAME_LOSS_SIMULATION
This IO Control enables the application to simulate the loss of sent and/or received EtherCAT frames for testing purposes. Three modes of operation are possible: Random, periodic or random periodic frame loss simulation.
* Random frame loss simulation: For each frame the dwFrameLossLikelihoodPpm parameter determines whether the frame will be discarded.
* Periodic frame loss simulation: After dwFixedLossNumLostFrames discarded frames, dwFixedLossNumGoodFrames frames will be processed.
* Random periodic frame loss simulation: The dwFrameLossLikelihoodPpm parameter determines whether a periodic frame loss sequence is triggered.
* **Parameters:**
* **pbyInBuf** – [in] Array of four EC_T_DWORDs (arrDword)
* **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
* **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
The parameters configurable are :
- arrDword [0] -> dwNumGoodFramesAfterStart
: Number of good frames before frame loss simulation starts
- arrDword [1] -> dwFrameLossLikelihoodPpm
: Random loss simulation: frame loss likelihood (ppm)
- arrDword [2] -> dwFixedLossNumGoodFrames
: Fixed loss simulation: number of good frames before frame loss
- arrDword [3] -> dwFixedLossNumLostFrames
: Fixed loss simulation: number of lost frames after processing the good ones
## emIoCtl - EC_IOCTL_SET_RXFRAME_LOSS_SIMULATION
### EC_IOCTL_SET_RXFRAME_LOSS_SIMULATION
Same as [EC_IOCTL_SET_FRAME_LOSS_SIMULATION](api_diagnosis.html.md#d0/d35/_ec_io_ctl_8h_1a990e775bb36e3e295e129858de970220) but only enables receive direction frame losses.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
## emIoCtl - EC_IOCTL_SET_TXFRAME_LOSS_SIMULATION
### EC_IOCTL_SET_TXFRAME_LOSS_SIMULATION
Same as [EC_IOCTL_SET_FRAME_LOSS_SIMULATION](api_diagnosis.html.md#d0/d35/_ec_io_ctl_8h_1a990e775bb36e3e295e129858de970220) but only enables transmit direction frame losses.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
## Error notifications - general information
For each error an error ID (error code) will be defined. This error ID will be used as the notification code when `emNotify()` is called. In addition to this notification code the second parameter given to `emNotify()` contains a pointer to an error notification descriptor of type [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC). This error notification descriptor contains detailed information about the error.
### struct EC_T_ERROR_NOTIFICATION_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNotifyErrorCode
Error ID (same value as the notification code)
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) achErrorInfo[MAX_ERRINFO_STRLEN]
Additional error string (may be empty)
### union \_EC_T_ERROR_NOTIFICATION_PARM
### Public Members
### [EC_T_WKCERR_DESC](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC) WkcErrDesc
WKC error descriptor
### [EC_T_FRAME_RSPERR_DESC](api_diagnosis.html.md#_CPPv422EC_T_FRAME_RSPERR_DESC) FrameRspErrDesc
Frame response error descriptor
### [EC_T_INITCMD_ERR_DESC](api_diagnosis.html.md#_CPPv421EC_T_INITCMD_ERR_DESC) InitCmdErrDesc
Master/Slave init command error descriptor
### [EC_T_SLAVE_ERROR_INFO_DESC](api_diagnosis.html.md#_CPPv426EC_T_SLAVE_ERROR_INFO_DESC) SlaveErrInfoDesc
Slave Error Info Descriptor
### [EC_T_SLAVES_ERROR_DESC](api_diagnosis.html.md#_CPPv422EC_T_SLAVES_ERROR_DESC) SlavesErrDesc
Slaves Error Descriptor
### [EC_T_MBOX_SDO_ABORT_DESC](mbx_coe.html.md#_CPPv424EC_T_MBOX_SDO_ABORT_DESC) SdoAbortDesc
SDO Abort
### EC_T_RED_CHANGE_DESC RedChangeDesc
Redundancy Descriptor
### [EC_T_MBOX_FOE_ABORT_DESC](mbx_foe.html.md#_CPPv424EC_T_MBOX_FOE_ABORT_DESC) FoeErrorDesc
FoE error code and string
### [EC_T_MBXRCV_INVALID_DATA_DESC](api_diagnosis.html.md#_CPPv429EC_T_MBXRCV_INVALID_DATA_DESC) MbxRcvInvalidDataDesc
Invalid mailbox data received descriptor
### [EC_T_PDIWATCHDOG_DESC](api_diagnosis.html.md#_CPPv421EC_T_PDIWATCHDOG_DESC) PdiWatchdogDesc
PDI watchdog expired
### [EC_T_SLAVE_NOTSUPPORTED_DESC](api_busscan.html.md#_CPPv428EC_T_SLAVE_NOTSUPPORTED_DESC) SlaveNotSupportedDesc
Slave not supported
### [EC_T_SLAVE_UNEXPECTED_STATE_DESC](api_diagnosis.html.md#_CPPv432EC_T_SLAVE_UNEXPECTED_STATE_DESC) SlaveUnexpectedStateDesc
Slave in unexpected state
### [EC_T_SLAVES_UNEXPECTED_STATE_DESC](api_diagnosis.html.md#_CPPv433EC_T_SLAVES_UNEXPECTED_STATE_DESC) SlavesUnexpectedStateDesc
Slaves in unexpected state
### [EC_T_EEPROM_CHECKSUM_ERROR_DESC](api_diagnosis.html.md#_CPPv431EC_T_EEPROM_CHECKSUM_ERROR_DESC) EEPROMChecksumErrorDesc
EEPROM checksum error
### EC_T_JUNCTION_RED_CHANGE_DESC JunctionRedChangeDesc
Junction redundancy change descriptor
### [EC_T_FRAMELOSS_AFTER_SLAVE_NTFY_DESC](api_busscan.html.md#_CPPv436EC_T_FRAMELOSS_AFTER_SLAVE_NTFY_DESC) FramelossAfterSlaveDesc
Frameloss after Slave descriptor
### EC_T_S2SMBX_ERROR_DESC S2SMbxErrorDesc
S2S Mailbox Error descriptor
### [EC_T_BAD_CONNECTION_NTFY_DESC](api_diagnosis.html.md#_CPPv429EC_T_BAD_CONNECTION_NTFY_DESC) BadConnectionDesc
Bad connection descriptor
### EC_T_COMMUNICATION_TIMEOUT_NTFY_DESC CommunicationTimeoutDesc
Communication timeout descriptor
### EC_T_TAP_LINK_STATUS_NTFY_DESC TapLinkStatusDesc
Tap link status
If the pointer to this descriptor exists (is not set to `EC_NULL`) the detailed error information (e.g. information about the SubDevice) is stored in the appropriate structure of a union. These error information structures are described in the following sections.
The EtherCAT® MainDevice will call `emNotify()` every time an error is detected. In some cases this will lead to calling this function in every EtherCAT® cycle (e.g. if there is no physical connection to a SubDevice). Using the control interface [emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) it is possible to determine which errors shall be signalled and which not.
## emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR
To update the process data some EtherCAT® commands will be sent cyclically by the MainDevice. These commands will address one or multiple SubDevices. These EtherCAT® commands contain a working counter which has to be incremented by each SubDevice that is addressed. The working counter will be checked after the EtherCAT® command is received by the MainDevice.
If the expected working counter does not match the working counter of the received command the error [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) will be indicated. The working counter value expected by the MainDevice is determined by the EtherCAT® configuration (XML) file for each cyclic EtherCAT® command (section Config/Cyclic/Frame/Cmd/Cnt).
Detailed error information is stored in the structure [`EC_T_WKCERR_DESC`](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).
This notification is enabled by default.
### struct EC_T_WKCERR_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties, content is undefined in case of cyclic WKC_ERROR
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byCmd
EtherCAT command type
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwAddr
Logical address or physical address (ADP/ADO)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkcSet
Working counter set value
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkcAct
Working counter actual value
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId
Cyclic Task ID (ENI: Cyclic/TaskId)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMsuId
Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd)
### struct EC_T_SLAVE_PROP
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress
Configured station address or INVALID_FIXED_ADDR
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAutoIncAddr
Configured auto increment address or INVALID_AUTO_INC_ADDR
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) achName[MAX_STD_STRLEN]
Configured name of the slave device (NULL terminated string)
#### SEE ALSO
- [emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation.
- [Cyclic cmd WKC validation and Frame Loss](software-integration_error-detection.html.md#cyclic-cmd-wkc-validation-and-frame-loss)
- [Working Counter (WKC) State in Diagnosis Image](software-integration_error-detection.html.md#working-counter-wkc-state-in-diagnosis-image)
- [emIoCtl - EC_IOCTL_SET_AUTO_ADJUST_CYCCMD_WKC_ENABLED](api_slave_control.html.md#emioctl-ec-ioctl-set-auto-adjust-cyccmd-wkc-enabled)
## emNotify - EC_NOTIFY_MASTER_INITCMD_WKC_ERROR
This error will be indicated in case of a working counter mismatch when sending MainDevice init commands. The working counter value expected by the MainDevice is determined by the EtherCAT® configuration (XML) file for each MainDevice init command (section Config/Master/InitCmds/InitCmd/Cnt). In case there is no “Cnt” entry in the XML file for this init command there will be no working counter verification. The working counter has to be incremented by all SubDevices which have to process this init command.
Detailed error information is stored in the structure [`EC_T_WKCERR_DESC`](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).
## emNotify - EC_NOTIFY_SLAVE_INITCMD_WKC_ERROR
This error will be indicated in case of a working counter mismatch when sending SubDevice init commands. The working counter value expected by the MainDevice is determined by the EtherCAT® configuration (XML) file for each SubDevice init command (section Config/Slave/InitCmds/InitCmd/Cnt). In case there is no “Cnt” entry in the XML file for this init command there will be no working counter verification.
Detailed error information is stored in the structure [`EC_T_WKCERR_DESC`](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC). The structure member SlaveProp contains information about the corresponding SubDevice.
## emNotify - EC_NOTIFY_FOE_MBSLAVE_ERROR
This error will be indicated in case a SubDevice notifies an error over FoE.
## emNotify - EC_NOTIFY_EOE_MBXSND_WKC_ERROR
This error will be indicated in case the working counter of an EoE mailbox write command was not set to the expected value of 1.
Detailed error information is stored in the structure [`EC_T_WKCERR_DESC`](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC). The structure member SlaveProp contains information about the corresponding SubDevice.
## emNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR
This error will be indicated in case the working counter of a CoE mailbox write command was not set to the expected value of 1.
Detailed error information is stored in the structure [`EC_T_WKCERR_DESC`](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC). The structure member SlaveProp contains information about the corresponding SubDevice.
## emNotify - EC_NOTIFY_FOE_MBXSND_WKC_ERROR
This error will be indicated in case the working counter of an FoE mailbox write command was not set to the expected value of 1.
## emNotify - EC_NOTIFY_VOE_MBXSND_WKC_ERROR
This error will be indicated in case the working counter of a VoE mailbox write command was not set to the expected value of 1.
Detailed error information is stored in the structure [`EC_T_WKCERR_DESC`](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC). The structure member SlaveProp contains information about the corresponding SubDevice.
## emNotify - EC_NOTIFY_S2SMBX_ERROR
This error will be indicated in case a SubDevice-To-SubDevice mailbox transfer fails.
#### SEE ALSO
[`EC_E_S2SMBX_NOT_CONFIGURED`](error-codes_generic.html.md#c.EC_E_S2SMBX_NOT_CONFIGURED)
## emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR
This error will be indicated if the received Ethernet frame does not match the frame expected or if an expected frame was not received.
This notification is enabled by default.
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation.
Missing response (timeout, [`eRspErr_NO_RESPONSE`](api_diagnosis.html.md#_CPPv4N22EC_T_FRAME_RSPERR_TYPE19eRspErr_NO_RESPONSEE)/ [`eRspErr_FRAME_RETRY`](api_diagnosis.html.md#_CPPv4N22EC_T_FRAME_RSPERR_TYPE19eRspErr_FRAME_RETRYE)) acyclic frames:
Acyclic Ethernet frames are internally queued by the MainDevice and sent to the SubDevices at a later time (usually after sending cyclic frames).
The MainDevice will monitor the time between queueing such a frame and receiving the result. If a maximum time is exceeded then this error will be indicated. This maximum time will be determined by the parameter dwEcatCmdTimeout when the MainDevice is initialized.
#### SEE ALSO
[`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS)
The MainDevice will retry sending the frame if the MainDevice configuration parameter dwEcatCmdMaxRetries is set to a value greater than 1. In case of a retry the [`eRspErr_FRAME_RETRY`](api_diagnosis.html.md#_CPPv4N22EC_T_FRAME_RSPERR_TYPE19eRspErr_FRAME_RETRYE) error is signalled, if the number of retries has elapsed the [`eRspErr_NO_RESPONSE`](api_diagnosis.html.md#_CPPv4N22EC_T_FRAME_RSPERR_TYPE19eRspErr_NO_RESPONSEE) error is signalled.
Possible reasons:
1. the frame was not received at all (due to bus problems)
: In this case the achErrorInfo member of the error notification descriptor will contain the string “L”.
2. the frame was sent too late by the MainDevice due to an improper configuration.
: In this case the achErrorInfo member of the error notification descriptor will contain the string “T”.
To avoid this error the configuration may be changed as follows:
-> higher value for MainDevice configuration parameter dwMaxAcycCmdsPerCycle
-> shorter MainDevice timer cycle, i.e. shorter period between two calls to
```cpp
emExecJob(eUsrJob_MasterTimer)
```
-> higher timeout value (MainDevice configuration parameter dwEcatCmdTimeout)
If the frame was sent too late by the MainDevice (due to improper configuration values) it will also be received too late and the MainDevice then signals an [`eRspErr_WRONG_IDX`](api_diagnosis.html.md#_CPPv4N22EC_T_FRAME_RSPERR_TYPE17eRspErr_WRONG_IDXE) or [`eRspErr_UNEXPECTED`](api_diagnosis.html.md#_CPPv4N22EC_T_FRAME_RSPERR_TYPE18eRspErr_UNEXPECTEDE) error (as the MainDevice then doesn’t expect to receive this frame).
Missing response (timeout, [`eRspErr_NO_RESPONSE`](api_diagnosis.html.md#_CPPv4N22EC_T_FRAME_RSPERR_TYPE19eRspErr_NO_RESPONSEE)) cyclic frames:
A response to all cyclic frames must occur until the next cycle starts. If the first cyclic frame is sent the MainDevice checks whether all cyclic frames of the last cycle were received. If there is one frame missing this error is indicated.
Possible reasons:
1. the frame was not received (due to bus problems)
2. too many or too long acyclic frames are sent in between sending cyclic frames by the MainDevice due to an improper configuration, to avoid these error notifications the configuration may be changed as follows:
: - lower value for MainDevice configuration parameter dwMaxAcycCmdsPerCycle
- higher cyclic timer period, i.e. less calls to [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) ( [`eUsrJob_SendAllCycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB24eUsrJob_SendAllCycFramesE))
3. non-deterministic sending of acyclic frames.
: Sending acyclic frames by calling [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) ( [`eUsrJob_SendAcycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB22eUsrJob_SendAcycFramesE)) has to be properly scheduled with sending cyclic frames by calling [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) ( [`eUsrJob_SendAllCycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB24eUsrJob_SendAllCycFramesE)).
Using the control interface [emIoCtl - EC_IOCTL_SET_FRAME_RESPONSE_ERROR_NOTIFY_MASK](api_diagnosis.html.md#emioctl-ec-ioctl-set-frame-response-error-notify-mask) it is possible to determine which response errors shall be signalled and which not.
Detailed error information is stored in the structure [`EC_T_FRAME_RSPERR_DESC`](api_diagnosis.html.md#_CPPv422EC_T_FRAME_RSPERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).
### struct EC_T_FRAME_RSPERR_DESC
### Public Members
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIsCyclicFrame
Indicates whether the lost frame was a cyclic frame
### [EC_T_FRAME_RSPERR_TYPE](api_diagnosis.html.md#_CPPv422EC_T_FRAME_RSPERR_TYPE) EErrorType
Frame response error type
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byEcCmdHeaderIdxSet
Expected IDX value, this value is valid only for acyclic frames in case EErrorType is not equal to eRspErr_UNEXPECTED
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byEcCmdHeaderIdxAct
Actually received IDX value, this value is only valid for acyclic frames in case of EErrorType is equal to: eRspErr_WRONG_IDX and eRspErr_UNEXPECTED
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wCycFrameNum
Number of the lost cyclic frame from the ENI
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId
Cyclic Task ID (ENI: Cyclic/TaskId). Only valid if bIsCyclicFrame is set
### enum EC_T_FRAME_RSPERR_TYPE
*Values:*
### enumerator eRspErr_UNDEFINED
Undefined
### enumerator eRspErr_NO_RESPONSE
No Ethernet frame received (timeout, frame loss)
### enumerator eRspErr_WRONG_IDX
Wrong IDX value in acyclic frame
### enumerator eRspErr_UNEXPECTED
Unexpected frame was received
### enumerator eRspErr_FRAME_RETRY
Ethernet frame will be re-sent (timeout, frame loss)
### enumerator eRspErr_RETRY_FAIL
All retry mechanism fails to re-sent acyclic frames
### enumerator eRspErr_FOREIGN_SRC_MAC
Frame with MAC from other Master received
### enumerator eRspErr_NON_ECAT_FRAME
Non EtherCAT frame received
### enumerator eRspErr_CRC
Ethernet frame with CRC error received
### enumerator eRspErr_ETHERNET_PAUSE_FRAME
Ethernet pause frame (flow control) received
## emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR
This error code will be indicated if a SubDevice does not respond appropriately while sending SubDevice init commands. The SubDevice init commands are defined in the EtherCAT® configuration (XML) file (`Config/Slave/InitCmds/InitCmd`). A timeout value for these commands may also be defined in the configuration file (`Config/Slave/InitCmds/InitCmd/Timeout`). If there is no timeout value defined here the frame response is expected within one single cycle.
This notification is enabled by default.
Detailed error information is stored in the structure [`EC_T_INITCMD_ERR_DESC`](api_diagnosis.html.md#_CPPv421EC_T_INITCMD_ERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).
### struct EC_T_INITCMD_ERR_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) achStateChangeName[MAX_SHORT_STRLEN]
State change description when the error occurred
### [EC_T_INITCMD_ERR_TYPE](api_diagnosis.html.md#_CPPv421EC_T_INITCMD_ERR_TYPE) EErrorType
Init command error type
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szComment[MAX_STD_STRLEN]
Comment (ENI)
### enum EC_T_INITCMD_ERR_TYPE
*Values:*
### enumerator eInitCmdErr_NO_ERROR
No error
### enumerator eInitCmdErr_NO_RESPONSE
No Ethernet frame received (timeout)
### enumerator eInitCmdErr_VALIDATION_ERR
Validation error (invalid slave command response)
### enumerator eInitCmdErr_FAILED
Init commands failed (state could not be reached)
### enumerator eInitCmdErr_NOT_PRESENT
Slave not present on the bus
### enumerator eInitCmdErr_ALSTATUS_ERROR
Error in AL Status Register
### enumerator eInitCmdErr_MBXSLAVE_ERROR
Error at Mailbox Init Command
### enumerator eInitCmdErr_PDI_WATCHDOG
PDI watchdog has been detected
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
## emNotify - EC_NOTIFY_MBSLAVE_INITCMD_TIMEOUT
This error is identical to error code [emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-slave-initcmd-response-error) but it will be indicated in case of timeouts when processing mailbox init commands.
The timeout value used for CoE mailbox SubDevice is defined in the EtherCAT® configuration (XML) file (`Config/Slave/Mailbox/CoE/InitCmds/InitCmd/Timeout`). In case this value is set to 0 a fixed timeout value of 500 ms will be used by the EtherCAT® MainDevice. The timeout value used for EoE mailbox SubDevices will be set to a fixed value of 5000 ms.
## emNotify - EC_NOTIFY_MASTER_INITCMD_RESPONSE_ERROR
This error code will be indicated if a missing or wrong command response was detected while sending MainDevice init commands. The MainDevice init commands are defined in the EtherCAT® configuration (XML) file (`Config/Master/InitCmds/InitCmd`). A timeout value for these commands may also be defined in the configuration file (`Config/Master/InitCmds/InitCmd/Timeout`). If there is no timeout value defined here the frame response is expected within one single cycle.
Detailed error information is stored in the structure [`EC_T_INITCMD_ERR_DESC`](api_diagnosis.html.md#_CPPv421EC_T_INITCMD_ERR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).
## emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL
When processing cyclic frames the EtherCAT® MainDevice checks whether all SubDevices are still in OPERATIONAL state. If at least one SubDevice is not OPERATIONAL this error will be indicated.
## emNotify - EC_NOTIFY_ALL_DEVICES_OPERATIONAL
When processing cyclic frames the EtherCAT® MainDevice checks whether all SubDevices are still in OPERATIONAL state. This will be notified after [emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL](api_diagnosis.html.md#emnotify-ec-notify-not-all-devices-operational) and all the SubDevices are back in OPERATIONAL state.
## emNotify - EC_NOTIFY_STATUS_SLAVE_ERROR
When processing cyclic frames the EtherCAT® MainDevice checks if at least one SubDevice has the ERROR bit in the AL-STATUS register set. In that case this error will be indicated. The MainDevice will then automatically determine detailed error information of the SubDevice(s) indicating an error and acknowledge the error status. The application will get an [emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO](api_diagnosis.html.md#emnotify-ec-notify-slave-error-status-info) notification for each such SubDevice. Usually those SubDevices will enter safe-operational state in this case. It is the application’s response how to further handle such error cases.
This notification is enabled by default.
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
## emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO
Every time the MainDevice detects a SubDevice error, the Error bit on the specific SubDevice is cleared and this error code will be signalled to the application. Detailed error information is stored in the structure [`EC_T_SLAVE_ERROR_INFO_DESC`](api_diagnosis.html.md#_CPPv426EC_T_SLAVE_ERROR_INFO_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC). This notification is enabled by default.
### struct EC_T_SLAVE_ERROR_INFO_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStatus
Slave Status (AL Status)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStatusCode
Error status code (AL STATUS CODE)
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
## emNotify - EC_NOTIFY_SLAVES_ERROR_STATUS
This notification collects notifications of type [emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO](api_diagnosis.html.md#emnotify-ec-notify-slave-error-status-info).
Notification is given on either collection full or MainDevice state changed whatever comes first.
This notification is disabled by default.
### struct EC_T_SLAVES_ERROR_DESC
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wCount
Number of slave errors
### [EC_T_SLAVES_ERROR_DESC_ENTRY](api_diagnosis.html.md#_CPPv428EC_T_SLAVES_ERROR_DESC_ENTRY) SlaveError[MAX_SLAVES_ERROR_NTFY_ENTRIES]
Slave error descriptions
### struct EC_T_SLAVES_ERROR_DESC_ENTRY
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress
Slave station address
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStatus
Slave status (AL Status)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStatusCode
Slave status code (AL Control Status)
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the activation
## emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE
This error is signalized every time a SubDevice changes into an unexpected state. Detailed error information is stored in the structure [`EC_T_SLAVE_UNEXPECTED_STATE_DESC`](api_diagnosis.html.md#_CPPv432EC_T_SLAVE_UNEXPECTED_STATE_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC). This notification is enabled by default.
### struct EC_T_SLAVE_UNEXPECTED_STATE_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) curState
Current state
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) expState
Expected state
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
## emNotify - EC_NOTIFY_SLAVES_UNEXPECTED_STATE
This notification collects notifications of type [emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE](api_diagnosis.html.md#emnotify-ec-notify-slave-unexpected-state). Notification is given on either collection full or MainDevice state changed whatever comes first. This notification is disabled by default.
### struct EC_T_SLAVES_UNEXPECTED_STATE_DESC
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wCount
Number of unexpected slave state changes
### [EC_T_SLAVES_UNEXPECTED_STATE_DESC_ENTRY](api_diagnosis.html.md#_CPPv439EC_T_SLAVES_UNEXPECTED_STATE_DESC_ENTRY) SlaveStates[MAX_SLAVES_UNEXPECTED_STATE_NTFY_ENTRIES]
Slave state change descriptions
### struct EC_T_SLAVES_UNEXPECTED_STATE_DESC_ENTRY
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress
Slave station address
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) curState
Current state
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) expState
Expected state
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the activation
## emNotify - EC_NOTIFY_ETH_LINK_NOT_CONNECTED
This notification will be indicated if the Ethernet link is disconnected. This error is never indicated if the Real-time Ethernet Driver does not support detection of a missing link cable.
In case of permanent frame loss no SubDevices can be found although the SubDevices are connected. This does not affect link connection detection, therefore this notification will not be indicated on permanent frame loss.
## emNotify - EC_NOTIFY_ETH_LINK_CONNECTED
This notification will be indicated if the Ethernet link is reconnected after a disconnect. This notification is never indicated if the Real-time Ethernet Driver does not support detection of a missing link cable.
## emNotify - EC_NOTIFY_CLIENTREGISTRATION_DROPPED
This notification will be indicated if the client registration was dropped because [`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD) was called by another thread. The notification has the following parameter:
```cpp
EC_T_DWORD dwDeinitForConfiguration; /* 0 = terminating MainDevice, 1 = restarting MainDevice */
```
## emNotify - EC_NOTIFY_EEPROM_CHECKSUM_ERROR
This error is signalized every time an EEPROM checksum error is detected.
Detailed error information is stored in the structure [`EC_T_EEPROM_CHECKSUM_ERROR_DESC`](api_diagnosis.html.md#_CPPv431EC_T_EEPROM_CHECKSUM_ERROR_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).
### struct EC_T_EEPROM_CHECKSUM_ERROR_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
## emNotify - EC_NOTIFY_MBXRCV_INVALID_DATA
This error is signalized when invalid mailbox data have been received from SubDevice. Detailed error information is stored in structure [`EC_T_MBXRCV_INVALID_DATA_DESC`](api_diagnosis.html.md#_CPPv429EC_T_MBXRCV_INVALID_DATA_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).
### struct EC_T_MBXRCV_INVALID_DATA_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
## emNotify - EC_NOTIFY_PDIWATCHDOG
This error is signalized every time a PDI watchdog error is detected. Detailed error information is stored in the structure [`EC_T_PDIWATCHDOG_DESC`](api_diagnosis.html.md#_CPPv421EC_T_PDIWATCHDOG_DESC) of [`EC_T_ERROR_NOTIFICATION_DESC`](api_diagnosis.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).
### struct EC_T_PDIWATCHDOG_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
## ecatGetText
### const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*ecatGetText([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTextId)
## emLogFrameEnable
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatLogFrameEnable([EC_T_PFLOGFRAME_CB](api_diagnosis.html.md#_CPPv418EC_T_PFLOGFRAME_CB) pvLogFrameCallBack, EC_T_VOID \*pvContext)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emLogFrameEnable([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_PFLOGFRAME_CB](api_diagnosis.html.md#_CPPv418EC_T_PFLOGFRAME_CB) pvLogFrameCallBack, EC_T_VOID \*pvContext)
Setup a callback function to log the EtherCAT network traffic.
The callback function is called by the cyclic task. Therefore the code inside the callback has to be fast and non-blocking. The callback parameter dwLogFlags can be used as a filter to log just specific frames. The master discards the frame if the callback function modifies the Ethernet frame type at byte offset 12.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pvLogFrameCallBack** – [in] Pointer to frame logging callback function
* **pvContext** – [in] Pointer to function specific context
* **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
### typedef EC_T_VOID (\*EC_T_PFLOGFRAME_CB)(EC_T_VOID \*pvContext, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLogFlags, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFrameSize, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyFrame)
#### NOTE
The master discards the frame if the callback function modifies the Ethernet frame type at byte offset 12.
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
* **Param dwLogFlags:**
**[in]** Frame logging flags, EC_LOG_FRAME_FLAG_…
* **Param dwFrameSize:**
**[in]** Size of frame in bytes
* **Param pbyFrame:**
**[in]** Pointer to frame data
### EC_LOG_FRAME_FLAG_MASTERSTATE_MASK
Bit 0 to 15: Master state mask
### EC_LOG_FRAME_FLAG_ACYC_FRAME
Bit 16 (0x00010000): 0=cyclic frame, 1=acyclic frame
### EC_LOG_FRAME_FLAG_DBG_FRAME
Bit 17 (0x00020000): 0=EtherCAT frame, 1=debug frame
### EC_LOG_FRAME_FLAG_RED_FRAME
Bit 18 (0x00040000): 0=main frame, 1=red frame
### EC_LOG_FRAME_FLAG_RX_FRAME
Bit 19 (0x00080000): 0=TX frame, 1=RX frame
### EC_LOG_FRAME_FLAG_MASTER_RED_FRAME
Bit 20 (0x00100000): 0=slave frame, 1=MasterMaster frame
```cpp
/********************************************************************************/
/** \brief Handler to log frames.
*
* CAUTION: Called by cyclic task!!! Do not consume to much CPU time!!!
*/
EC_T_VOID LogFrameHandler(EC_T_VOID* pvContext, EC_T_DWORD dwLogFlags, EC_T_DWORD dwFrameSize, EC_T_BYTE* pbyFrame)
{
EC_T_STATE eMasterState;
/* get MainDevice state */
eMasterState = (EC_T_STATE)(dwLogFlags & EC_LOG_FRAME_FLAG_MASTERSTATE_MASK);
/* skip tx frame */
if ((S_dwLogFrameLevel == 3) && !(dwLogFlags & EC_LOG_FRAME_FLAG_RX_FRAME))
return;
/* skip cyclic frame */
if ((S_dwLogFrameLevel == 2) && !(dwLogFlags & EC_LOG_FRAME_FLAG_ACYC_FRAME))
return;
/* skip red frame */
if (dwLogFlags & EC_LOG_FRAME_FLAG_RED_FRAME)
return;
/* do something with pbyFrame ... */
}
```
## emLogFrameDisable
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatLogFrameDisable(EC_T_VOID)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emLogFrameDisable([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Disable the frame logging callback.
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **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
## emGetMasterInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetMasterInfo([EC_T_MASTER_INFO](api_diagnosis.html.md#_CPPv416EC_T_MASTER_INFO) \*pMasterInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetMasterInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MASTER_INFO](api_diagnosis.html.md#_CPPv416EC_T_MASTER_INFO) \*pMasterInfo)
Get generic information about the Master.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pMasterInfo** – [out] Master information
* **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 pParms is NULL or contains values out of range
* [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
### struct EC_T_MASTER_INFO
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMasterVersion
Master version
### [EC_T_BUS_DIAGNOSIS_INFO](api_diagnosis.html.md#_CPPv423EC_T_BUS_DIAGNOSIS_INFO) BusDiagnosisInfo
Bus diagnostics
### [EC_T_MAILBOX_STATISTICS](api_diagnosis.html.md#_CPPv423EC_T_MAILBOX_STATISTICS) MailboxStatistics
Mailbox statistics
### EC_T_REDUNDANCY_DIAGNOSIS_INFO RedundancyDiagnosisInfo
Redundancy diagnosis info
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMasterStateSummary
Master state summary
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMasterVersionType
Master version type. See [EC_VERSION_TYPE](api_general_functions.html.md#d2-d96-group-e-c-v-e-r-s-i-o-n-t-y-p-e-s)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMasterStateSummaryDiagBitOffset
Bit offset of Master state summary in diagnosis image
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMasterStateSummaryDiagBitSize
Bit offset size of Master state summary in diagnosis image
### struct EC_T_BUS_DIAGNOSIS_INFO
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCRC32ConfigCheckSum
CRC32 checksum of the loaded configuration
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumSlavesFound
Number of slaves connected
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumDCSlavesFound
Number of slaves with DC enabled connected
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumCfgSlaves
Number of slaves in ENI
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumMbxSlaves
Number of slaves in ENI with mailbox support
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTXFrames
Number of frames sent
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRXFrames
Number of frames received
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLostFrames
Number of lost frames
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCyclicFrames
Number of cyclic frames sent
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCyclicDatagrams
Number of cyclic datagrams / EtherCAT commands sent
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwAcyclicFrames
Number of acyclic frames sent
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwAcyclicDatagrams
Number of acyclic datagrams / EtherCAT commands sent
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClearCounters
Clear frame / datagram counter bit field
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCyclicLostFrames
Number of cyclic lost frames
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwAcyclicLostFrames
Number of acyclic lost frames
### struct EC_T_MAILBOX_STATISTICS
### Public Members
### [EC_T_STATISTIC_TRANSFER_DUPLEX](api_diagnosis.html.md#_CPPv430EC_T_STATISTIC_TRANSFER_DUPLEX) Aoe
AoE mailbox transfer statistics
### [EC_T_STATISTIC_TRANSFER_DUPLEX](api_diagnosis.html.md#_CPPv430EC_T_STATISTIC_TRANSFER_DUPLEX) Coe
CoE mailbox transfer statistics
### [EC_T_STATISTIC_TRANSFER_DUPLEX](api_diagnosis.html.md#_CPPv430EC_T_STATISTIC_TRANSFER_DUPLEX) Eoe
EoE mailbox transfer statistics
### [EC_T_STATISTIC_TRANSFER_DUPLEX](api_diagnosis.html.md#_CPPv430EC_T_STATISTIC_TRANSFER_DUPLEX) Foe
FoE mailbox transfer statistics
### [EC_T_STATISTIC_TRANSFER_DUPLEX](api_diagnosis.html.md#_CPPv430EC_T_STATISTIC_TRANSFER_DUPLEX) Soe
SoE mailbox transfer statistics
### [EC_T_STATISTIC_TRANSFER_DUPLEX](api_diagnosis.html.md#_CPPv430EC_T_STATISTIC_TRANSFER_DUPLEX) Voe
VoE mailbox transfer statistics
### [EC_T_STATISTIC_TRANSFER_DUPLEX](api_diagnosis.html.md#_CPPv430EC_T_STATISTIC_TRANSFER_DUPLEX) RawMbx
Raw mailbox transfer statistics
### struct EC_T_STATISTIC_TRANSFER_DUPLEX
### Public Members
### [EC_T_STATISTIC_TRANSFER](api_diagnosis.html.md#_CPPv423EC_T_STATISTIC_TRANSFER) Read
Number of read transfers
### [EC_T_STATISTIC_TRANSFER](api_diagnosis.html.md#_CPPv423EC_T_STATISTIC_TRANSFER) Write
Number of write transfers
### struct EC_T_STATISTIC_TRANSFER
### Public Members
### [EC_T_STATISTIC](api_diagnosis.html.md#_CPPv414EC_T_STATISTIC) Cnt
Number of transfers
### [EC_T_STATISTIC](api_diagnosis.html.md#_CPPv414EC_T_STATISTIC) Bytes
Number of bytes transferred
### struct EC_T_STATISTIC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTotal
Total
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLast
Last
### **emGetMasterInfo() Example**
```cpp
EC_T_MASTER_INFO oMasterInfo;
OsMemset(&oMasterInfo, 0, sizeof(EC_T_MASTER_INFO));
dwRes = emGetMasterInfo(dwInstanceId, &oMasterInfo);
```
## emGetMemoryUsage
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetMemoryUsage([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwCurrentUsage, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwMaxUsage)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetMemoryUsage([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwCurrentUsage, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwMaxUsage)
Returns information about memory usage.
All calls to malloc/free and new/delete are monitored.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pdwCurrentUsage** – [out] Current memory usage in Bytes at the time where this function is called
* **pdwMaxUsage** – [out] Maximum memory usage in Bytes since initialization at the time where this function is called
* **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
### **emGetMemoryUsage() Example**
```cpp
EC_T_DWORD dwCurrentUsage = EC_NULL;
EC_T_DWORD dwMaxUsage = EC_NULL;
dwRes = emGetMemoryUsage(dwInstanceId, &dwCurrentUsage, &dwMaxUsage);
```
## emGetMasterDump
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetMasterDump([EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyBuffer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBufferSize, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwDumpSize)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetMasterDump([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyBuffer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBufferSize, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwDumpSize)
The dump contains relevant information about the master and slave status.
The dump is only intended for internal troubleshooting at acontis. Amongst others it contains the following descriptors:
* [EC_T_INIT_MASTER_PARMS](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)
* [EC_T_BUS_DIAGNOSIS_INFO](api_diagnosis.html.md#d6/d66/struct_e_c___t___b_u_s___d_i_a_g_n_o_s_i_s___i_n_f_o)
* [EC_T_MAILBOX_STATISTICS](api_diagnosis.html.md#d2/ddb/struct_e_c___t___m_a_i_l_b_o_x___s_t_a_t_i_s_t_i_c_s)
* [EC_T_CFG_SLAVE_INFO](api_slave_control.html.md#d5/dca/struct_e_c___t___c_f_g___s_l_a_v_e___i_n_f_o)
* [EC_T_BUS_SLAVE_INFO](api_slave_control.html.md#d3/d12/struct_e_c___t___b_u_s___s_l_a_v_e___i_n_f_o)
* [EC_T_SLVSTATISTICS_DESC](api_diagnosis.html.md#d6/dee/struct_e_c___t___s_l_v_s_t_a_t_i_s_t_i_c_s___d_e_s_c)
The buffer is written until all relevant data have been dumped or the buffer size has been exceeded.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pbyBuffer** – [in] Preallocated buffer to dump log data
* **dwBufferSize** – [in] Size of preallocated buffer
* **pdwDumpSize** – [out] Size of master dump
* **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)
* [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if buffer too small
### **emGetMasterDump() Example**
```cpp
EC_T_DWORD dwBufferSize = 8192;
EC_T_BYTE* byBuffer = (EC_T_BYTE*)OsMalloc(dwBufferSize);
EC_T_DWORD dwDumpSize = dwBufferSize;
dwRes = emGetMasterDump(dwInstanceId, byBuffer, dwBufferSize, &dwDumpSize);
```
## emGetMasterSyncUnitInfoNumOf
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetMasterSyncUnitInfoNumOf(EC_T_VOID)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetMasterSyncUnitInfoNumOf([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Get number of Master Sync Units info entries.
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **Returns:**
Number of Master Sync Units info entries
### **emGetMasterSyncUnitInfoNumOf() Example**
```cpp
/* get Master Sync Units info entries count */
EC_T_DWORD dwSyncedUnitsCount = emGetMasterSyncUnitInfoNumOf(dwInstanceId);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
"Units count: %d", dwSyncedUnitsCount));
```
## emGetMasterSyncUnitInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetMasterSyncUnitInfo([EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMsuId, [EC_T_MSU_INFO](api_diagnosis.html.md#_CPPv413EC_T_MSU_INFO) \*pMsuInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetMasterSyncUnitInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMsuId, [EC_T_MSU_INFO](api_diagnosis.html.md#_CPPv413EC_T_MSU_INFO) \*pMsuInfo)
Get information about a specific Master Sync Unit.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **wMsuId** – [in] Master Sync Unit to get the information from
* **pMsuInfo** – [out] Pointer to an [EC_T_MSU_INFO](api_diagnosis.html.md#d4/dfc/struct_e_c___t___m_s_u___i_n_f_o) structure receiving the Master Sync Unit information
* **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
`MSU_ID_ALL_INFO_ENTRIES` retrieves the information from all MainDevice sync units at once. The application must ensure that pMsuInfo is capable for all entries.
### struct EC_T_MSU_INFO
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMsuId
[out] Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsIn
[out] Process Data Image INPUTs bit offset
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitSizeIn
[out] Process Data Image INPUTs bit length
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsOut
[out] Process Data Image OUTPUTs bit offset
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitSizeOut
[out] Process Data Image OUTPUTs bit length
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffsIn
[out] INPUTs WkcState bit offset in Diagnosis Image. (Bit values: 0 = Process Data valid, 1 = Process Data invalid)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffsOut
[out] OUTPUTs WkcState bit offset in Diagnosis Image. (Bit values: 0 = Process Data valid, 1 = Process Data invalid)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) adwReserved[16]
reserved
### **emGetMasterSyncUnitInfo() Example**
```cpp
/* get information about specific Master Sync Unit */
EC_T_WORD wMsuId = 0;
EC_T_MSU_INFO oMsuInfo;
OsMemset(&oMsuInfo, 0, sizeof(EC_T_MSU_INFO));
dwRes = emGetMasterSyncUnitInfo(dwInstanceId, wMsuId, &oMsuInfo);
```
#### SEE ALSO
[`emGetMasterSyncUnitInfoNumOf()`](api_diagnosis.html.md#_CPPv428emGetMasterSyncUnitInfoNumOf10EC_T_DWORD)
## emBadConnectionsDetect
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatBadConnectionsDetect([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bRefreshSlaveStatistics, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emBadConnectionsDetect([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bRefreshSlaveStatistics, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Detects bad connections.
Analyzes the slave ESC error counters:
* Invalid Frame Counter (0x0300),
* RX Error Counter (0x0301),
* Lost Link Counter (0x0310),
whether there is a problem in the area PHY - connector - cable - connector - PHY. If one of the above error counters shows a value not equal to zero, an EC_NOTIFY_BAD_CONNECTION is generated, which contains the exact position of the faulty connection.
It is recommended to call emBadConnectionsReset() on startup of EC-Master to ensure that all error counters of all slaves are in a defined state.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bRefreshSlaveStatistics** – [in] EC_TRUE: refresh ESC error counters, EC_FALSE: process current ESC error counters
* **dwTimeout** – [in] Timeout [ms]. May not be EC_NOWAIT!
* **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
### **emBadConnectionsDetect() Example**
```cpp
dwRes = emBadConnectionsDetect(dwInstanceId, EC_TRUE, 5000 /* timeout */);
```
#### SEE ALSO
[`emBadConnectionsReset()`](api_diagnosis.html.md#_CPPv421emBadConnectionsReset10EC_T_DWORD)
## emBadConnectionsReset
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatBadConnectionsReset(EC_T_VOID)
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emBadConnectionsReset([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Clears all error counters (0x0300 - 0x0313) of all slaves.
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
### **emBadConnectionsReset() Example**
```cpp
dwRes = emBadConnectionsReset(dwInstanceId);
```
## emNotify - EC_NOTIFY_BAD_CONNECTION
This error is signalized every time a bad connection is detected within the call of [`emBadConnectionsDetect()`](api_diagnosis.html.md#_CPPv422emBadConnectionsDetect10EC_T_DWORD9EC_T_BOOL10EC_T_DWORD) or [`emSelfTestScan()`](api_diagnosis.html.md#_CPPv414emSelfTestScan10EC_T_DWORDP23EC_T_SELFTESTSCAN_PARMS). It contains the exact location of the bad connection between two SubDevices. This notification is enabled by default.
### struct EC_T_BAD_CONNECTION_NTFY_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlavePropParent
Slave properties of parent slave
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPortAtParent
Port at parent slave
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlavePropChild
Slave properties of child slave
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPortAtChild
Port at child slave
#### SEE ALSO
- [emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
- ETG.1600 Guideline for Planning, Assembling and Commissioning of EtherCAT Networks
## emSelfTestScan
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSelfTestScan([EC_T_SELFTESTSCAN_PARMS](api_diagnosis.html.md#_CPPv423EC_T_SELFTESTSCAN_PARMS) \*pParms)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSelfTestScan([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_SELFTESTSCAN_PARMS](api_diagnosis.html.md#_CPPv423EC_T_SELFTESTSCAN_PARMS) \*pParms)
Self test scan.
Send a burst of numerous frames and analyze the slave connections. After deactivating the job task, frames will be sent as fast as the LinkLayer can send them. The size of the frames increases and decreases between the defined limits. Dependent on the parameters the BadConnectionsDetect API will analyze the slave connections.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pParms** – [in] Self-test scan parameters
* **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 pParms is NULL or contains values out of range
* [EC_E_BAD_CONNECTION](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_1ga7fdc3e2f6bde054363693840df3004ee) if bad connection was detected
* [EC_E_FRAME_LOST](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_1gab14020342304e6737c85b43977721c07) if frame(s) lost during self-test
* [EC_E_NOTSUPPORTED](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_1ga11f77305fb1d3868539a735298cc7864) if not in polling mode
* [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
### struct EC_T_SELFTESTSCAN_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSize
[in] Set to sizeof(EC_T_SELFTESTSCAN_PARMS)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout
[in] Timeout [ms], 0 or EC_NOWAIT defaults to 500ms
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFrameCount
[in] Total number of frames sent during the self-test. Default value is 1500. A value of 0 sets the default value.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFrameSizeMin
[in] Min frame size [bytes]. Default value is 60. A value of 0 sets the default value.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFrameSizeMax
[in] Max frame size [bytes]. Default value is 1514. A value of 0 sets the default value.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFrameSizeStep
[in] Size [bytes] by which the frame increases or decreases continuously during the self-test. Default value is 1. A value of 0 sets the default value.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDetectBadConnections
[in] Execute the bad connection detection after self-test
### EC_T_UINT64 qwFrameRoundtripTimeAvg
[out] Roundtrip time average [us]. Time taken from sending to receiving the frame (master application level).
### EC_T_UINT64 qwFrameRoundtripTimeMin
[out] Roundtrip time minimum [us]. Time taken from sending to receiving the frame (master application level).
### EC_T_UINT64 qwFrameRoundtripTimeMax
[out] Roundtrip time maximum [us]. Time taken from sending to receiving the frame (master application level).
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMeasureRoundtripTimeForSingleFrame
[in] Execute roundtrip time calculation for single frame
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bClearSlaveErrorCounters
[in] Clear all slaves’ error counters before running the self-test
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDuration
[in] Desired duration to run the self-test scan [s]. Stops as soon as dwDuration is reached. A value of 0 means no duration limit. If dwDuration is not zero, dwFrameCount is ignored.
### **emSelfTestScan() Example**
```cpp
EC_T_SELFTESTSCAN_PARMS oParms;
OsMemset(&oParms, 0, sizeof(EC_T_SELFTESTSCAN_PARMS));
oParms.dwSize = sizeof(EC_T_SELFTESTSCAN_PARMS);
oParms.dwTimeout = 5000;
oParms.dwFrameCount = 1500;
oParms.dwFrameSizeMin = 60;
oParms.dwFrameSizeMax = 1514;
oParms.dwFrameSizeStep = 1;
oParms.bDetectBadConnections = EC_FALSE;
oParms.bClearSlaveErrorCounters = EC_FALSE;
dwRes = emSelfTestScan(dwInstanceId, &oParms);
```
#### SEE ALSO
[`emBadConnectionsDetect()`](api_diagnosis.html.md#_CPPv422emBadConnectionsDetect10EC_T_DWORD9EC_T_BOOL10EC_T_DWORD)
# api_general_functions.html.md
# General functions
## emInitMaster
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatInitMaster(const [EC_T_INIT_MASTER_PARMS](api_general_functions.html.md#_CPPv422EC_T_INIT_MASTER_PARMS) \*pParms)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emInitMaster([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_INIT_MASTER_PARMS](api_general_functions.html.md#_CPPv422EC_T_INIT_MASTER_PARMS) \*pParms)
Initialize EC-Master.
This function has to be called prior to calling any other function of EC-Master.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pParms** – [in] Pointer to parameter definitions
* **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 is already 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 pParms is EC_NULL or contains some values out of range
* [EC_E_SIGNATURE_MISMATCH](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_1gac700561c04c9d81a7c088e13d104cf36) if [EC_T_INIT_MASTER_PARMS.dwSignature](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_1af0642e281f06ad3914f05c31b1cc311e) mismatch
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if the link layer cannot be found
* [EC_E_FEATURE_DISABLED](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_1gab1113b4cdd40bec6cddbd07d8780ff8a) if a configured feature is not included in the license key
* [EC_E_NOTSUPPORTED](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_1ga11f77305fb1d3868539a735298cc7864) if a configured feature is not supported (e.g not compiled in the library)
* [EC_E_LOCK_CREATE_FAILED](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_1ga1f28e665d82dadd8fd062e38ee7b4ea0) if some lock (e.g mutex) cannot be created
* [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if some memory cannot be allocated
### struct EC_T_INIT_MASTER_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSignature
[in] Set to ATECAT_SIGNATURE
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSize
[in] Set to sizeof(EC_T_INIT_MASTER_PARMS)
### [EC_T_LOG_PARMS](api_general_functions.html.md#_CPPv414EC_T_LOG_PARMS) LogParms
[in] Logging parameters
### [EC_T_OS_PARMS](api_general_functions.html.md#_CPPv413EC_T_OS_PARMS) \*pOsParms
[in] OS layer parameters
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) \*pLinkParms
[in] Link layer parameters
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) \*pLinkParmsRed
[in] Link layer parameters for red device (cable redundancy)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBusCycleTimeNsec
[in] Bus cycle time [ns]
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxBusSlaves
[in] Maximum pre-allocated bus slave objects ( default: 256 )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxAcycFramesQueued
[in] Maximum queued acyclic frames
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwAdditionalEoEEndpoints
[in] Additional EoE endpoints
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxAcycBytesPerCycle
[in] Maximum bytes sent during eUsrJob_SendAcycFrames per cycle ( default: 4096 )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxAcycFramesPerCycle
[in] Maximum frames sent during eUsrJob_SendAcycFrames per cycle ( default: 32 )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxAcycCmdsPerCycle
[in] Maximum commands sent during eUsrJob_SendAcycFrames per cycle ( default: 124 )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxSlavesProcessedPerCycle
[in] Maximum slave-related state machine calls per cycle (default = all)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwEcatCmdMaxRetries
[in] Maximum retries to send pending EtherCAT command frames ( default: 3 )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwEcatCmdTimeout
[in] Timeout [ms] to send pending EtherCAT command frames ( default: 3 \* bus cycle time, at least 2 ms )
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bReserved
[in] bVLANEnable: obsolete
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wReserved
[in] wVLANId: obsolete
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byReserved
[in] byVLANPrio: obsolete
### EC_T_MASTER_RED_PARMS MasterRedParms
[in] Master Redundancy parameters
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxS2SMbxSize
[in] Size of the queued S2S mailbox in bytes ( default: 0 )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxQueuedS2SMbxTfer
[in] S2S Fifo number of entries ( default: 0 )
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMaxSlavesProcessedPerBusScanStep
[in] Maximum slave-related calls per cycle during bus scans (default = all)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bApiLockByApp
[in] Lock pending API against [emDeinitMaster()](api_general_functions.html.md#db/d74/_ec_master_api_8cpp_1a5e90f588405100ab8fb8ff552982ae18). EC_FALSE (default): locked internally. EC_TRUE: application is responsible for locking.
### [EC_T_PERF_MEAS_INTERNAL_PARMS](api_general_functions.html.md#_CPPv429EC_T_PERF_MEAS_INTERNAL_PARMS) PerfMeasInternalParms
[in] Internal performance measurement parameters
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoConsecutiveAcycFrames
[in] [EC_FALSE(default)](toc_api.html.md#d3/d07/_ec_type_8h_1a149503ff82608125e305c77d12d46d1b) : no restriction. EC_TRUE : Don’t process and send acyclic frames in the same cycle to reduce CPU load.
### struct EC_T_OS_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSignature
[in] Set to EC_OS_PARMS_SIGNATURE
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSize
[in] Set to sizeof(EC_T_OS_PARMS)
### [EC_T_LOG_PARMS](api_general_functions.html.md#_CPPv414EC_T_LOG_PARMS) \*pLogParms
[in] Pointer to logging parameters
### EC_PF_SYSTIME pfSystemTimeGet
[in] Function to get host time in nanoseconds since 1st January 2000. Used as time base for DC Initialization.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSupportedFeatures
[in/out] Reserved
### EC_PF_QUERY_MSEC_COUNT pfSystemQueryMsecCount
[in] Function to get system’s ms count
### struct EC_T_LOG_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLogLevel
[in] Log level. See [EC_LOG_LEVEL…](api_general_functions.html.md#d3-d63-group-e-c-l-o-g-l-e-v-e-l-s)
### [EC_PF_LOGMSGHK](api_general_functions.html.md#_CPPv414EC_PF_LOGMSGHK) pfLogMsg
[in] Log callback function called on every message
### EC_T_LOG_CONTEXT \*pLogContext
[in] Log context to be passed to log callback
EC_LOG_LEVEL…
The following log levels are defined:
### EC_LOG_LEVEL_SILENT
### EC_LOG_LEVEL_ANY
### EC_LOG_LEVEL_CRITICAL
### EC_LOG_LEVEL_ERROR
### EC_LOG_LEVEL_WARNING
### EC_LOG_LEVEL_INFO
### EC_LOG_LEVEL_INFO_API
### EC_LOG_LEVEL_VERBOSE
### EC_LOG_LEVEL_VERBOSE_ACYC
### EC_LOG_LEVEL_VERBOSE_CYC
### EC_LOG_LEVEL_UNDEFINED
### typedef [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_LOGMSGHK)(EC_T_LOG_CONTEXT \*pContext, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLogMsgSeverity, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szFormat, ...)
* **Param pContext:**
[in] Context pointer. This pointer is used as parameter when the callback function is called.
* **Param dwLogMsgSeverity:**
[in] Log message severity, EC_LOG_LEVEL_…
* **Param szFormat:**
[in] String that contains the text to be written. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested.
* **Return:**
[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
Log messages are passed from the EC-Master to the callback given at [`EC_T_LOG_PARMS::pfLogMsg`](api_general_functions.html.md#_CPPv4N14EC_T_LOG_PARMS8pfLogMsgE). EcLogging.cpp demonstrates how messages can be handled by the application.
For performance reasons the EC-Master automatically filters log messages according to [`EC_T_LOG_PARMS::dwLogLevel`](api_general_functions.html.md#_CPPv4N14EC_T_LOG_PARMS10dwLogLevelE). E.g. messages of severity [`EC_LOG_LEVEL_WARNING`](api_general_functions.html.md#c.EC_LOG_LEVEL_WARNING) are not passed to the application if [`EC_T_LOG_PARMS::dwLogLevel`](api_general_functions.html.md#_CPPv4N14EC_T_LOG_PARMS10dwLogLevelE) is set to [`EC_LOG_LEVEL_ERROR`](api_general_functions.html.md#c.EC_LOG_LEVEL_ERROR).
The application can provide customized log message handlers of type [`EC_PF_LOGMSGHK`](api_general_functions.html.md#_CPPv414EC_PF_LOGMSGHK) if the default handler in EcLogging.cpp does not fulfill the application’s needs. Note: The callback is typically called from the Job Task’s context and should return as fast as possible.
### struct EC_T_PERF_MEAS_INTERNAL_PARMS
### Public Members
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bEnabled
[in] Enable/disable internal performance counters
### [EC_T_PERF_MEAS_COUNTER_PARMS](api_general_functions.html.md#_CPPv428EC_T_PERF_MEAS_COUNTER_PARMS) CounterParms
[in] Timer function settings. When not provided OsMeasGetCounterTicks is used.
### [EC_T_PERF_MEAS_HISTOGRAM_PARMS](api_general_functions.html.md#_CPPv430EC_T_PERF_MEAS_HISTOGRAM_PARMS) HistogramParms
[in] Histogram settings. When not provided the histogram is disabled.
### struct EC_T_PERF_MEAS_COUNTER_PARMS
### Public Members
### [EC_PF_PERF_MEAS_GETCOUNTERTICKS](api_general_functions.html.md#_CPPv431EC_PF_PERF_MEAS_GETCOUNTERTICKS) pfGetCounterTicks
[in] Function returning the current counter ticks
### EC_T_VOID \*pvGetCounterTicksContext
[in] Context passed into GetCounterTicks
### EC_T_UINT64 qwFrequency
[in] Frequency in Hz used by the timer in GetCounterTicks
### typedef EC_T_UINT64 (\*EC_PF_PERF_MEAS_GETCOUNTERTICKS)(EC_T_VOID \*pvContext)
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
### struct EC_T_PERF_MEAS_HISTOGRAM_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBinCount
[in] Amount of bins to use for the histogram
### EC_T_UINT64 qwMinTicks
[in] Results below qwMinTicks are stored in the first bin
### EC_T_UINT64 qwMaxTicks
[in] Results above qwMaxTicks are stored in the last bin
## emDeinitMaster
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatDeinitMaster(EC_T_VOID)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emDeinitMaster([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Deinitialize EC-Master.
Waits for pending API calls if [emInitMaster()](api_general_functions.html.md#db/d74/_ec_master_api_8cpp_1a20396c6311952930b2a5c10c2baf2131) was called with [EC_T_INIT_MASTER_PARMS::bApiLockByApp](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_1a547ddca9ee542c4373ddbb2adc436fc3) = EC_FALSE (default).
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **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
## emGetMasterParms
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetMasterParms([EC_T_INIT_MASTER_PARMS](api_general_functions.html.md#_CPPv422EC_T_INIT_MASTER_PARMS) \*pParms, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwParmsBufSize)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetMasterParms([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_INIT_MASTER_PARMS](api_general_functions.html.md#_CPPv422EC_T_INIT_MASTER_PARMS) \*pParms, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwParmsBufSize)
Get current Master initialization parameters.
If the given buffer is larger than the actual size of the structure [EC_T_INIT_MASTER_PARMS](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), the parameters of [EC_T_INIT_MASTER_PARMS.pOsParms](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_1ab6f3eca95a1ef491d761cb66b882dd8b), [EC_T_INIT_MASTER_PARMS.pLinkParms](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_1a7391b4950b7bc41ae8000ace06400d64) and [EC_T_INIT_MASTER_PARMS.pLinkParmsRed](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_1aeb5abd3b1c6fcce37d7c667100ccc644) are appended.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pParms** – [out] Buffer to store Master parameters
* **dwParmsBufSize** – [in] Size of Master parameters buffer
* **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 output pointer is EC_NULL or dwParmsBufSize is too small
### **emGetMasterParms() Example**
```cpp
EC_T_BYTE abyBuffer[sizeof(EC_T_INIT_MASTER_PARMS)
+ sizeof(EC_T_OS_PARMS) + 512 /* LinkLayer parameters */];
EC_T_INIT_MASTER_PARMS* pParms = (EC_T_INIT_MASTER_PARMS*)abyBuffer;
dwRes = emGetMasterParms(dwInstanceId, pParms, sizeof(abyBuffer));
```
#### SEE ALSO
[`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS)
## emSetMasterParms
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetMasterParms(const [EC_T_INIT_MASTER_PARMS](api_general_functions.html.md#_CPPv422EC_T_INIT_MASTER_PARMS) \*pParms)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetMasterParms([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_INIT_MASTER_PARMS](api_general_functions.html.md#_CPPv422EC_T_INIT_MASTER_PARMS) \*pParms)
Change Master initialization parameters.
Currently the following parameters cannot be changed:
* [EC_T_INIT_MASTER_PARMS.pOsParms](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_1ab6f3eca95a1ef491d761cb66b882dd8b)
* [EC_T_INIT_MASTER_PARMS.pLinkParms](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_1a7391b4950b7bc41ae8000ace06400d64)
* [EC_T_INIT_MASTER_PARMS.pLinkParmsRed](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_1aeb5abd3b1c6fcce37d7c667100ccc644)
* [EC_T_INIT_MASTER_PARMS.dwMaxBusSlaves](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_1a26c3f1f2a5c46af4ad8cc8aa955cebb8)
* [EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesQueued](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_1ae90efbf60aa12acbd95ab39a3f0b10a0)
* [EC_T_INIT_MASTER_PARMS.dwAdditionalEoEEndpoints](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_1aba26f467698dcc9d3a69545512918300)
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pParms** – [in] New Master parameters
* **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
### **emSetMasterParms() Example**
```cpp
EC_T_BYTE abyBuffer[sizeof(EC_T_INIT_MASTER_PARMS) + sizeof(EC_T_OS_PARMS)
+ 512 /* LinkLayer parameters */];
EC_T_INIT_MASTER_PARMS* pParms = (EC_T_INIT_MASTER_PARMS*)abyBuffer;
dwRes = emGetMasterParms(dwInstanceId, pParms, sizeof(abyBuffer));
pParms->wReserved = 1;
/* change Master initialization parameters */
dwRes = emSetMasterParms(dwInstanceId, pParms);
```
#### SEE ALSO
[`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS)
## emScanBus
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatScanBus([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emScanBus([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Scans all connected slaves.
Scans all connected slaves connected to EC-Master. If a configuration has been loaded, a validation between the configuration and the connected slaves is done. This function should not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **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
* [EC_E_LINK_DISCONNECTED](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_1ga8dac899f16df522b9c6754c7d8d0fb72) if link is disconnected
* [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_BUSCONFIG_MISMATCH](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_1ga613dd4e3b8cac7ac5193993f1afeaae6) if the slaves found do not match the configured ones
* [EC_E_LINE_CROSSED](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_1ga83c05b7bdc82fe8c2b664fae4156b995) if a line crossed (cabling wrong) condition has been detected
* [EC_E_REDLINEBREAK](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_1gaccf988b91722079a5b6be82dc2e0beec) if cable redundancy is configured and a line break condition has been detected
* [EC_E_JUNCTION_RED_LINE_BREAK](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_1gaa5458e142909815b607221dda2bb018e) if junction redundancy is configured and a line break condition has been detected
* [EC_E_MAX_BUS_SLAVES_EXCEEDED](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_1ga0cc0e975f6f44f48a70ac7c9eedfd331) if the amount of slaves found exceeds [EC_T_INIT_MASTER_PARMS.dwMaxBusSlaves](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_1a26c3f1f2a5c46af4ad8cc8aa955cebb8)
* [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
* [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running
### **emScanBus() Example**
```cpp
dwRes = emScanBus(dwInstanceId, 5000 /* timeout */);
```
#### SEE ALSO
- [EtherCAT® Bus Scan](api_busscan.html.md#ethercat-r-bus-scan)
## emRescueScan
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatRescueScan([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emRescueScan([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Recovers the bus from permanent frame loss situations.
Scans all connected slaves. Closes and opens ports on the network to rule out slaves which permanently discard frames. The Master notifies every slave port which permanently discards frames with EC_NOTIFY_FRAMELOSS_AFTER_SLAVE. Due to port opening and closing the scanning time is increased about 2 seconds per slave. The Master will not automatically re-open this port. The application can force to open the port again. This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **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
### **emRescueScan() Example**
```cpp
dwRes = emRescueScan(dwInstanceId, 5000 /* timeout */);
```
#### SEE ALSO
- [`emSetSlavePortState()`](api_slave_control.html.md#_CPPv419emSetSlavePortState10EC_T_DWORD10EC_T_DWORD9EC_T_WORD9EC_T_BOOL9EC_T_BOOL10EC_T_DWORD)
- [emNotify - EC_NOTIFY_FRAMELOSS_AFTER_SLAVE](api_busscan.html.md#emnotify-ec-notify-frameloss-after-slave)
## emConfigureNetwork
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatConfigureNetwork([EC_T_CNF_TYPE](api_general_functions.html.md#_CPPv413EC_T_CNF_TYPE) eCnfType, [EC_T_PBYTE](toc_api.html.md#_CPPv410EC_T_PBYTE) pbyCnfData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCnfDataLen)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emConfigureNetwork([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_CNF_TYPE](api_general_functions.html.md#_CPPv413EC_T_CNF_TYPE) eCnfType, [EC_T_PBYTE](toc_api.html.md#_CPPv410EC_T_PBYTE) pbyCnfData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCnfDataLen)
Configure the Network.
This function must be called after the initialization. Among others the EtherCAT topology defined in the given XML configuration file will be stored internally.
Analyzing the network including mailbox communication can be done without specifying an ENI file using eCnfType_GenPreopENI.
#### NOTE
A client must not be registered prior to calling this function. Existing client registrations will be dropped.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **eCnfType** – [in] Type of configuration data provided
* **pbyCnfData** – [in] Filename / configuration data, or EC_NULL if eCnfType is eCnfType_GenPreopENI
* **dwCnfDataLen** – [in] Length of configuration data in byte, or zero if eCnfType is eCnfType_GenPreopENI
* **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 or eCnfType is eCnfType_GenPreopENI or eCnfType_GenOpENI and link is disconnected
* [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 pParms is EC_NULL contains some values out of range
* [EC_E_LINK_DISCONNECTED](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_1ga8dac899f16df522b9c6754c7d8d0fb72) if link is disconnected
* [EC_E_FEATURE_DISABLED](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_1gab1113b4cdd40bec6cddbd07d8780ff8a) if a configured feature is not included in the license key
* [EC_E_NOTSUPPORTED](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_1ga11f77305fb1d3868539a735298cc7864) if a configured feature is not supported (e.g not compiled in the library)
* [EC_E_CFGFILENOTFOUND](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_1ga7da2ce5dd71f5dbc9c5b37ced65de133) if the ENI file cannot be found
* [EC_E_WRONG_FORMAT](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_1ga7ef775b882e22c0ac3ff95e8f0b5fb53) if format errors have been detected in the ENI or EEPROM in case of eCnfType_GenPreopENI or eCnfType_GenOpENI
* [EC_E_OEM_SIGNATURE_MISMATCH](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_1gaa9c0e78be6f5d34aa079232c84a9f796) if the OEM signature in the ENI file doesn’t match the used OEM key
* [EC_E_ENI_ENCRYPTION_WRONG_VERSION](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_1ga5c1f9e38352dc3ac3d458c30be5fa064) if the ENI encryption version is not supported (e.g. the library is too old)
* [EC_E_ENI_ENCRYPTED](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_1gae95f45d1e8937074725ff7fe77cbaf12) if the ENI is encrypted and no OEM key has been set
* [EC_E_XML_CYCCMDS_MISSING](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_1gaefee0a6b4f7097cc1ccdab22e2efccca) if the ENI doesn’t contain cyclic commands
* [EC_E_XML_ALSTATUS_READ_MISSING](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_1ga570d575d0d3bf5ee8e3a11cdd9e09eb2) if the ENI doesn’t contain any read AL status command
* [EC_E_XML_CYCCMDS_SIZEMISMATCH](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_1ga057e7cdfe426e792a7ab60830d2b3cf7) if the size of the cyclic commands in the ENI mismatch
* [EC_E_XML_INVALID_INP_OFF](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_1ga26f2972ae26bb55a653adbb40a8fefa0) if some input offsets in the ENI are invalid
* [EC_E_XML_INVALID_OUT_OFF](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_1gad32f71e9d681cba85774d28f4416ee00) if some output offsets in the ENI are invalid
* [EC_E_XML_INVALID_CMD_WITH_RED](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_1ga6bdb2349373a8e935d23521806c4462b) if the ENI contains LRW commands and cable redundancy is configured
* [EC_E_XML_PREV_PORT_MISSING](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_1ga9ad1388e4ca96dcc4cef15851b09b654) if some previous port information are missing in the ENI
* [EC_E_XML_DC_CYCCMDS_MISSING](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_1ga6aa2d4a50dde9e285f7c0f936edbb1d0) if the DC related cyclic commands are missing in the ENI
* [EC_E_XML_AOE_NETID_INVALID](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_1ga11c2ea29d41ed1e850c4c0e76a0f3b89) if the ENI contains some invalid NetID
### enum EC_T_CNF_TYPE
*Values:*
### enumerator eCnfType_Unknown
### enumerator eCnfType_Filename
pbyCnfData: ENI filename to read
### enumerator eCnfType_Data
pbyCnfData: ENI data
### enumerator eCnfType_Datadiag
pbyCnfData: ENI data for diagnosis
### enumerator eCnfType_GenPreopENI
Generate ENI based on bus-scan result to get into PREOP state
### enumerator eCnfType_GenPreopENIWithCRC
Same as eCnfType_GenPreopENI with CRC protection
### enumerator eCnfType_GenOpENI
Generate ENI based on bus-scan result to get into OP state. The default PDO mapping read from the slaves is activated. See ETG2010 “SII Specification”, Table 14 “Structure Category TXPDO and RXPDO for each PDO”.
### enumerator eCnfType_None
Reset configuration
### enumerator eCnfType_ConfigData
pbyCnfData: Binary structured configuration
### enumerator eCnfType_GenOpENINoStrings
Generate ENI based on bus-scan result to get into OP state, does not read strings from EEPROM
### enumerator eCnfType_FileByApp
File access provided by user application, See [EC_T_CNF_FILEBYAPP_DESC](api_general_functions.html.md#d0/d80/struct_e_c___t___c_n_f___f_i_l_e_b_y_a_p_p___d_e_s_c)
### enumerator eCnfType_GenEBI
Generate EBI based on bus-scan result
Depending on this enum pbyCnfData is interpreted differently. This function may not be called from within the JobTask’s context.
### struct EC_T_CNF_FILEBYAPP_DESC
### Public Members
### EC_T_VOID \*pvContext
[in] Arbitrarily application-defined parameter passed to callbacks
### [EC_PF_CNF_OPEN](api_general_functions.html.md#_CPPv414EC_PF_CNF_OPEN) pfnFileOpen
[in] Function pointer called instead of OsCfgFileOpen()
### [EC_PF_CNF_CLOSE](api_general_functions.html.md#_CPPv415EC_PF_CNF_CLOSE) pfnFileClose
[in] Function pointer called instead of OsCfgFileClose()
### [EC_PF_CNF_READ](api_general_functions.html.md#_CPPv414EC_PF_CNF_READ) pfnFileRead
[in] Function pointer called instead of OsCfgFileRead()
### [EC_PF_CNF_ERROR](api_general_functions.html.md#_CPPv415EC_PF_CNF_ERROR) pfnFileError
[in] Function pointer called instead of OsCfgFileError()
### [EC_PF_CNF_EOF](api_general_functions.html.md#_CPPv413EC_PF_CNF_EOF) pfnFileEof
[in] Function pointer called instead of OsCfgFileEof()
### typedef [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_CNF_OPEN)(EC_T_VOID \*pvContext)
Called by the EtherCAT stack instead of OsCfgFileOpen() within emConfigureNetwork(eCnfType_FileByApp)
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
* **Return:**
[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
### typedef [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_CNF_CLOSE)(EC_T_VOID \*pvContext)
Called by the EtherCAT stack instead of OsCfgFileClose() within emConfigureNetwork(eCnfType_FileByApp)
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
* **Return:**
[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
### typedef [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_CNF_READ)(EC_T_VOID \*pvContext, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyReadData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReadLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOutData)
Called by the EtherCAT stack instead of OsCfgFileRead() within emConfigureNetwork(eCnfType_FileByApp)
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
* **Param pbyReadData:**
**[out]** Pointer to the data read
* **Param dwReadLen:**
**[in]** Amount of bytes to be read by the EtherCAT stack (next part of the configuration file)
* **Param pdwNumOutData:**
**[out]** Amount of bytes written to pbyReadData by callback
* **Return:**
[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
### typedef [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_CNF_ERROR)(EC_T_VOID \*pvContext)
Called by the EtherCAT stack instead of OsCfgFileError() within emConfigureNetwork(eCnfType_FileByApp)
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
* **Return:**
[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
### typedef [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_CNF_EOF)(EC_T_VOID \*pvContext, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*bEof)
Called by the EtherCAT stack instead of OsCfgFileEof() within emConfigureNetwork(eCnfType_FileByApp)
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
* **Param bEof:**
**[out]** Indicates whether the end of the file has been reached (EC_TRUE if EOF, EC_FALSE otherwise).
* **Return:**
[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
### **emConfigureNetwork() Example**
```cpp
/* load ENI */
const EC_T_CHAR* szFileName = "eni.xml";
dwRes = emConfigureNetwork(dwInstanceId, eCnfType_Filename,
(EC_T_BYTE*)szFileName, (EC_T_DWORD)OsStrlen(szFileName));
```
## emConfigGet
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatConfigGet([EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*\*ppbyCnfData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwCnfDataLen)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emConfigGet([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*\*ppbyCnfData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwCnfDataLen)
Get the master configuration.
This function returns the result of ENI parsing in binary format. This data can be stored at a different location (e.g. read only flash). Later on, the Master can be configured without ENI using the type EC_T_CNF_TYPE::eCnfType_ConfigData.
#### NOTE
The binary format is not version independent and the data becomes invalid when used with a different version. The returned pointer is valid as long as the Master is initialized and no other configuration was loaded.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **ppbyCnfData** – [out] Configuration data
* **pdwCnfDataLen** – [out] Length of configuration data in byte
* **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
### **emConfigGet() Example**
```cpp
EC_T_BYTE* pbyConfigData = EC_NULL;
EC_T_DWORD dwConfigDataSize = 0;
/* set config data memory pool */
EC_IOCTL_SET_CONFIGDATA_MEMORY_POOL_DESC oPoolDesc;
oPoolDesc.dwSize = 100000; /* max config file size */
oPoolDesc.pbyStart = (EC_T_BYTE*)OsMalloc(oPoolDesc.dwSize);
dwRes = emIoCtl(dwInstanceId, EC_IOCTL_SET_CONFIGDATA_MEMORY_POOL,
&oPoolDesc, sizeof(EC_IOCTL_SET_CONFIGDATA_MEMORY_POOL_DESC),
EC_NULL, 0, EC_NULL);
if (dwRes != EC_E_NOERROR)
{
dwRetVal = dwRes;
goto Exit;
}
/* load config */
dwRes = emConfigLoad(dwInstanceId, eCnfType_Filename,
(EC_T_BYTE*)szFileName, (EC_T_DWORD)OsStrlen(szFileName));
if (dwRes != EC_E_NOERROR)
{
dwRetVal = dwRes;
goto Exit;
}
/* get config */
dwRes = emConfigGet(dwInstanceId, &pbyConfigData, &dwConfigDataSize);
if (dwRes != EC_E_NOERROR)
{
dwRetVal = dwRes;
goto Exit;
}
```
#### SEE ALSO
[`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)
## emConfigExtend
#### WARNING
Before using this function, please check if the following patents have to be taken into consideration for your application and use case:
**JP5212509:ADDRESS SETTING METHOD IN NETWORK SYSTEM**
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatConfigExtend([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bResetConfig, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emConfigExtend([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bResetConfig, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Extends the existing network configuration.
This function extends the existing configuration described in the ENI to allow mailbox communication with unexpected slaves. After this function was called, unexpected slaves can reach PREOP state. After the configuration was extended, disconnecting any slave will generate a bus mismatch, because all the slaves are part of the configuration. Recalling this function with bResetConfig set to EC_FALSE will extend the configuration again by any new connected unexpected slaves. The previous extension is not deleted. Calling the function with bResetConfig set to EC_TRUE will reset all the previous extensions.
#### NOTE
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bResetConfig** – [in] EC_TRUE: Extended configuration will be removed
* **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
### **emConfigExtend() Example**
```cpp
dwRes = emConfigExtend(dwInstanceId, EC_TRUE, 5000 /* timeout */);
```
## emRegisterClient
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatRegisterClient([EC_PF_NOTIFY](api_general_functions.html.md#_CPPv412EC_PF_NOTIFY) pfnNotify, EC_T_VOID \*pCallerData, [EC_T_REGISTERRESULTS](api_general_functions.html.md#_CPPv420EC_T_REGISTERRESULTS) \*pRegResults)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emRegisterClient([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_PF_NOTIFY](api_general_functions.html.md#_CPPv412EC_PF_NOTIFY) pfnNotify, EC_T_VOID \*pCallerData, [EC_T_REGISTERRESULTS](api_general_functions.html.md#_CPPv420EC_T_REGISTERRESULTS) \*pRegResults)
Registers a client on the EC-Master.
It must be called after configuration, otherwise the registration handle is lost. This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pfnNotify** – [in] Notification callback function. This function will be called every time a state change occurs, an error occurs or a mailbox transfer terminates.
* **pCallerData** – [in] Pointer to a caller data area which will be passed to the client on every notification callback
* **pRegResults** – [out] Registration results, a pointer to a structure of type [EC_T_REGISTERRESULTS](api_general_functions.html.md#dc/d06/struct_e_c___t___r_e_g_i_s_t_e_r_r_e_s_u_l_t_s)
* **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 output pointer is EC_NULL
* [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if some memory cannot be allocated
### typedef [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) (\*EC_PF_NOTIFY)([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](api_notifications.html.md#_CPPv416EC_T_NOTIFYPARMS) \*pParms)
* **Param dwCode:**
**[in]** Notification code, see EC_NOTIFY_…
* **Param pParms:**
**[in]** Notification code depending data
### struct EC_T_REGISTERRESULTS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClntId
[out] Client ID
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyPDIn
[out] Pointer to process data input memory
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPDInSize
[out] Size of process data input memory (in bytes)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyPDOut
[out] Pointer to process data output memory
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPDOutSize
[out] Size of process data output memory (in bytes)
### **emRegisterClient() Example**
```cpp
EC_T_REGISTERRESULTS oRegResults;
OsMemset(&oRegResults, 0, sizeof(EC_T_REGISTERRESULTS));
dwRes = emRegisterClient(dwInstanceId, myAppNotify, pvMyAppContext, &oRegResults);
```
## emUnregisterClient
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatUnregisterClient([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClntId)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emUnregisterClient([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClntId)
Unregister a client from the EtherCAT master.
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 determined when registering with the master
* **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
## emGetSrcMacAddress
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSrcMacAddress(ETHERNET_ADDRESS \*pMacSrc)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSrcMacAddress([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, ETHERNET_ADDRESS \*pMacSrc)
Gets the source MAC address.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pMacSrc** – [out] 6-byte buffer to write source MAC address to
* **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
[`EC_T_INIT_MASTER_PARMS::pLinkParms`](api_general_functions.html.md#_CPPv4N22EC_T_INIT_MASTER_PARMS10pLinkParmsE)
### **emGetSrcMacAddress() Example**
```cpp
/* get MAC address of EtherCAT network adapter */
ETHERNET_ADDRESS oMacSrc;
OsMemset(&oMacSrc, 0, sizeof(ETHERNET_ADDRESS));
dwRes = emGetSrcMacAddress(dwInstanceId, &oMacSrc);
```
## emSetMasterState
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetMasterState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) eReqState)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetMasterState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) eReqState)
Set the master (and all slaves) into the requested EtherCAT state.
If the function is called with EC_NOWAIT, the client may wait for reaching the requested state using the notification callback (EC_NOTIFY_STATECHANGED).
By default the Master will just change to a higher state if all slaves have reached the requested state. It may happen that some slaves are in higher state at network than the Master, e.g.:
* Master and all slaves are in PREOP
* Application requests SAFEOP
* Master starts transition for all slaves
* Some slaves changed to SAFEOP, but some fail and therefore stay in PREOP
* Master state stays in PREOP, function returns with error
The application can request SAFEOP again to re-request the state of previously failed slaves. Transition to a lower state: The master changes to a lower state even if one slave is not able to follow. This function may not be called from within the JobTask’s context with dwTimeout other than EC_NOWAIT.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwTimeout** – [in] Timeout [ms]. This function will block until the requested state is reached or the timeout elapsed. If the timeout value is set to EC_NOWAIT the function will return immediately.
* **eReqState** – [in] Requested System state
* **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
* [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_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
* [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running
### enum EC_T_STATE
*Values:*
### enumerator eEcatState_UNKNOWN
Unknown state
### enumerator eEcatState_INIT
EtherCAT state INIT
### enumerator eEcatState_PREOP
EtherCAT state PREOP (pre-operational)
### enumerator eEcatState_SAFEOP
EtherCAT state SAFEOP (safe operational)
### enumerator eEcatState_OP
EtherCAT state OP (operational)
### enumerator eEcatState_BOOTSTRAP
EtherCAT state BOOTSTRAP
### **emSetMasterState() Example**
```cpp
/* set EtherCAT master (and all slaves) into requested state */
dwRes = emSetMasterState(dwInstanceId, 5000, eEcatState_PREOP);
```
#### SEE ALSO
[emIoCtl - EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE](api_slave_control.html.md#emioctl-ec-ioctl-all-slaves-must-reach-master-state)
## emSetMasterStateReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetMasterStateReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) eReqState)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetMasterStateReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) eReqState)
Request to set the master (and all slaves) into the requested EtherCAT state and return immediately.
The Master by default will just change to a higher state, if all slaves have reached the requested state. It may happen that some slaves are in higher state at network than Master, e.g.:
* Master and all slaves are in PREOP
* Application requests SAFEOP
* Master starts transition for all slaves
* Some slaves changed to SAFEOP, but some fail and therefore stay in PREOP
* Master state stays in PREOP, function returns with error
The application can request SAFEOP again to re-request state of previously failed slaves. Transition to lower state: The master changes to lower state, even if one slave is not able to follow.
See also EC_NOTIFY_STATECHANGED.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwTimeout** – [in] Timeout [ms]. This function will block until the requested state is reached or the timeout elapsed. If the timeout value is set to EC_NOWAIT the function will return immediately.
* **eReqState** – [in] Requested System state
* **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
* [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
* [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
### **emSetMasterStateReq() Example**
```cpp
/* set EtherCAT master (and all slaves) into requested state */
dwRes = emSetMasterStateReq(dwInstanceId, 5000, eEcatState_PREOP);
```
#### SEE ALSO
[emIoCtl - EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE](api_slave_control.html.md#emioctl-ec-ioctl-all-slaves-must-reach-master-state)
#### SEE ALSO
[`emSetMasterState()`](api_general_functions.html.md#_CPPv416emSetMasterState10EC_T_DWORD10EC_T_DWORD10EC_T_STATE)
## emGetMasterState
### static [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) ecatGetMasterState(EC_T_VOID)
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) emGetMasterState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Get the EtherCAT master current state.
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **Returns:**
EtherCAT master state
### **emGetMasterState() Example**
```cpp
EC_T_STATE eMasterState = emGetMasterState(dwInstanceId);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
"Current Master State: %s:\n", ecatStateToStr(eMasterState)));
```
## emGetMasterStateEx
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetMasterStateEx([EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwCurrState, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReqState)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetMasterStateEx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwCurrState, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReqState)
Get the EtherCAT master current and requested state. Possible return values for current and requested state:
* [DEVICE_STATE_UNKNOWN](api_slave_control.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga33b90f5429fe46ff40e374be0d64c76b)
* [DEVICE_STATE_INIT](api_slave_control.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga2a184454821e98410d522211abc6e136)
* [DEVICE_STATE_PREOP](api_slave_control.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga0b667c3c6c197200043dde1cc401e5e1)
* [DEVICE_STATE_SAFEOP](api_slave_control.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga185291cf09a7d9dd5dfa8461d90e39c7)
* [DEVICE_STATE_OP](api_slave_control.html.md#dd/dc3/group___d_e_v_i_c_e___s_t_a_t_e_s_1ga9e6fe68bf128d21867c80f053b29a76a)
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pwCurrState** – [out] Current master state
* **pwReqState** – [out] Requested master state
* **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 output pointers are EC_NULL
### **emGetMasterStateEx() Example**
```cpp
EC_T_WORD wCurrState = 0;
EC_T_WORD wReqState = 0;
/* get EtherCAT master current state */
dwRes = emGetMasterStateEx(dwInstanceId, &wCurrState, &wReqState);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
"Current state: %s, requested state: %s\n",
ecatDeviceStateText(wCurrState), ecatDeviceStateText(wReqState)));
```
## emExecJob
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatExecJob([EC_T_USER_JOB](api_general_functions.html.md#_CPPv413EC_T_USER_JOB) eUserJob, [EC_T_USER_JOB_PARMS](api_general_functions.html.md#_CPPv419EC_T_USER_JOB_PARMS) \*pUserJobParms)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emExecJob([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_USER_JOB](api_general_functions.html.md#_CPPv413EC_T_USER_JOB) eUserJob, [EC_T_USER_JOB_PARMS](api_general_functions.html.md#_CPPv419EC_T_USER_JOB_PARMS) \*pUserJobParms)
Execute or initiate the requested job.
To achieve maximum speed, this function is implemented non re-entrant. It is highly recommended that only one single task is calling all required jobs to run the stack. If multiple tasks are calling this function, the calls have to be synchronized externally. Calling it in a context that doesn’t support operating system calls can lead to unpredictable behavior.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **eUserJob** – [in] User requested job
* **pUserJobParms** – [in] Optional user job parameters
* **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 output pointer is EC_NULL
* [EC_E_LINK_DISCONNECTED](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_1ga8dac899f16df522b9c6754c7d8d0fb72) if the link is disconnected
* [EC_E_FEATURE_DISABLED](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_1gab1113b4cdd40bec6cddbd07d8780ff8a) for eUsrJob_SwitchEoeFrames if EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED hasn’t be called before
* [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running
*Brief job overview:*
### enum EC_T_USER_JOB
*Values:*
### enumerator eUsrJob_Undefined
### enumerator eUsrJob_ProcessAllRxFrames
### enumerator eUsrJob_SendAllCycFrames
### enumerator eUsrJob_MasterTimer
### enumerator eUsrJob_SendAcycFrames
### enumerator eUsrJob_SendCycFramesByTaskId
### enumerator eUsrJob_MasterTimerMinimal
### enumerator eUsrJob_ProcessRxFramesByTaskId
### enumerator eUsrJob_ProcessAcycRxFrames
### enumerator eUsrJob_SwitchEoeFrames
### enumerator eUsrJob_StartTask
### enumerator eUsrJob_StopTask
### enumerator eUsrJob_StampSendAllCycFrames
### enumerator eUsrJob_StampSendCycFramesByTaskId
### enumerator eUsrJob_SimulatorTimer
### enumerator eUsrJob_MonitorTimer
### union EC_T_USER_JOB_PARMS
### Public Members
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bAllCycFramesProcessed
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumFramesSent
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskIdToSend
### struct [EC_T_USER_JOB_PARMS](api_general_functions.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_SEND_CYCFRAME_BY_TASKID](api_general_functions.html.md#_CPPv4N19EC_T_USER_JOB_PARMS24_SEND_CYCFRAME_BY_TASKIDE) SendCycFramesByTaskId
### struct [EC_T_USER_JOB_PARMS](api_general_functions.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_PROCESS_RXFRAME_BY_TASKID](api_general_functions.html.md#_CPPv4N19EC_T_USER_JOB_PARMS26_PROCESS_RXFRAME_BY_TASKIDE) ProcessRxFramesByTaskId
### struct [EC_T_USER_JOB_PARMS](api_general_functions.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_SWITCH_EOE_FRAMES](api_general_functions.html.md#_CPPv4N19EC_T_USER_JOB_PARMS18_SWITCH_EOE_FRAMESE) SwitchEoeFrames
### struct [EC_T_USER_JOB_PARMS](api_general_functions.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_START_TASK](api_general_functions.html.md#_CPPv4N19EC_T_USER_JOB_PARMS11_START_TASKE) StartTask
### struct [EC_T_USER_JOB_PARMS](api_general_functions.html.md#_CPPv419EC_T_USER_JOB_PARMS)::[\_STOP_TASK](api_general_functions.html.md#_CPPv4N19EC_T_USER_JOB_PARMS10_STOP_TASKE) StopTask
### struct \_PROCESS_RXFRAME_BY_TASKID
### Public Members
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bCycFramesProcessed
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId
### struct \_SEND_CYCFRAME_BY_TASKID
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId
### struct \_START_TASK
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId
### struct \_STOP_TASK
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId
### struct \_SWITCH_EOE_FRAMES
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxPortsToProcess
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumFramesProcessed
*Detailed job description:*
1. [`eUsrJob_ProcessAllRxFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB26eUsrJob_ProcessAllRxFramesE)
: When the Real-time Ethernet Driver operates in polling mode this call will process all currently received frames, when the Real-time Ethernet Driver operates in interrupt mode all received frames are processed immediately and this call just returns with nothing done.
```cpp
pUserJobParms->bAllCycFramesProcessed
```
If this flag is set to a value of [`EC_TRUE`](toc_api.html.md#c.EC_TRUE) it indicates that all previously initiated cyclic frames ( [`eUsrJob_SendAllCycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB24eUsrJob_SendAllCycFramesE) ) are received and processed within this call. Not used if pUserJobParms is set to [`EC_NULL`](toc_api.html.md#c.EC_NULL).
Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful, error code in case of failures.
2. [`eUsrJob_SendAllCycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB24eUsrJob_SendAllCycFramesE)
: Send all cyclic frames. New values will be written to the EtherCAT® SubDevice’s outputs and new input values will be received. If the Real-time Ethernet Driver operates in interrupt mode, the process data input values will be updated immediately after receiving the frames. If the Real-time Ethernet Driver operates in polling mode, the next call to [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) with the [`eUsrJob_ProcessAllRxFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB26eUsrJob_ProcessAllRxFramesE) job will check for received frames and update the process data input values.
```cpp
pUserJobParms->dwNumFramesSent
```
Indicates number of frames sent within this call. Not used if pUserJobParms is set to [`EC_NULL`](toc_api.html.md#c.EC_NULL).
Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful, error code in case of failures.
In case not all previously initiated cyclic frames are processed when calling this function an error notification will be generated ( [emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-frame-response-error)).
3. [`eUsrJob_SendAcycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB22eUsrJob_SendAcycFramesE)
: Acyclic EtherCAT® datagrams stored in the acyclic frame buffer FIFO will be sent when executing this call.
```cpp
pUserJobParms->dwNumFramesSent
```
Indicates number of frames sent within this call. Not used if pUserJobParms is set to [`EC_NULL`](toc_api.html.md#c.EC_NULL).
Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful, error code in case of failures.
4. [`eUsrJob_MasterTimer`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB19eUsrJob_MasterTimerE)
: To trigger the MainDevice and SubDevice state machines as well as the mailbox handling this call has to be executed cyclically. The MainDevice cycle time is determined by the period between calling [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) ( [`eUsrJob_MasterTimer`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB19eUsrJob_MasterTimerE)). The state-machines are handling the EtherCAT® state change transfers.
Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful, error code in case of failures.
5. [`eUsrJob_SendCycFramesByTaskId`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB29eUsrJob_SendCycFramesByTaskIdE)
: Send cyclic frames related to a specific task id. If more than one cyclic entries are configured this user job can be used to send the appropriate cyclic frames. All frames stored in cyclic entries with the given task id will be sent.
#### SEE ALSO
[Multiple cyclic entries configuration](software-integration_eni-configuration.html.md#multiple-cyclic-entries-configuration)
```cpp
pUserJobParms->SendCycFramesByTaskId.dwTaskId
```
Task id.
Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful, error code in case of failures. If not all previously initiated cyclic frames for the same task are already processed when calling this function an error will be generated ( [emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-frame-response-error)).
6. [`eUsrJob_ProcessRxFramesByTaskId`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB31eUsrJob_ProcessRxFramesByTaskIdE)
: [`eUsrJob_ProcessAcycRxFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB27eUsrJob_ProcessAcycRxFramesE)
#### SEE ALSO
Feature-Pack Split Frame Processing
7. [`eUsrJob_SwitchEoeFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB23eUsrJob_SwitchEoeFramesE)
: This job must be called if [emIoCtl - EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED](api_general_functions.html.md#emioctl-ec-ioctl-set-eoe-deffered-switching-enabled) has been called before. It can be called in parallel to Send / Process jobs in a lower prioritized task
```cpp
pUserJobParms->SwitchEoeFrames.dwMaxPortsToProcess
```
Indicates number of ports to be processed within this call. If zero, all ports will be processed.
```cpp
pUserJobParms->SwitchEoeFrames.dwNumFramesProcessed
```
Returns number of frames processed within this call.
Return: [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) if successful
8. [`eUsrJob_StartTask`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB17eUsrJob_StartTaskE)
: Inform EC-Master that the current task is started. Specify pUserJobParms.StartTask.dwTaskId or pass pUserJobParms set to EC_NULL for task ID 0.
9. [`eUsrJob_StopTask`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB16eUsrJob_StopTaskE)
: Inform EC-Master that the current task is stopped. Specify pUserJobParms.StopTask.dwTaskId or pass pUserJobParms set to EC_NULL for task ID 0.
### **emExecJob() Example**
```cpp
EC_T_USER_JOB oUserJob;
OsMemset(&oUserJob, 0, sizeof(EC_T_USER_JOB));
oUserJob = eUsrJob_StartTask;
EC_T_USER_JOB_PARMS oUserJobParms;
OsMemset(&oUserJobParms, 0, sizeof(EC_T_USER_JOB));
dwRes = emExecJob(dwInstanceId, oUserJob, &oUserJobParms);
```
## emGetVersion
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetVersion([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwVersion, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwVersionType)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetVersion([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwVersion, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwVersionType)
Gets the version information.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pdwVersion** – [out] Pointer to EC_T_DWORD to carry out version number as a 32-bit value
* **pdwVersionType** – [out] Pointer to EC_T_DWORD to carry out version type. See [EC_VERSION_TYPE](api_general_functions.html.md#d2-d96-group-e-c-v-e-r-s-i-o-n-t-y-p-e-s).
* **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 output pointer is EC_NULL
**EC Version Type**
### EC_VERSION_TYPE_UNDEFINED
EC-Master Type Undefined
### EC_VERSION_TYPE_UNRESTRICTED
EC-Master Type Unrestricted
### EC_VERSION_TYPE_PROTECTED
EC-Master Type Protected
### EC_VERSION_TYPE_DONGLED
EC-Master Type Dongled
### EC_VERSION_TYPE_EVAL
EC-Master Type Eval
### **emGetVersion() Example**
```cpp
/* get stack version */
EC_T_DWORD dwVersion = EC_E_ERROR;
EC_T_DWORD dwVersionType = 0;
dwRes = emGetVersion(dwInstanceId, &dwVersion, &dwVersionType);
```
## emSetLicenseKey
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetLicenseKey(const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szLicenseKey)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetLicenseKey([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szLicenseKey)
Sets the license key for the protected version of EC-Master.
Must be called after initialization and before configuration. This function may not be called if a non protected version is used.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **szLicenseKey** – [in] License key as zero terminated string with 26, 53 or 56 characters
* **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
* [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 format of the license key is wrong. The correct length is 26, 53 or 56 characters.
* [EC_E_LICENSE_MISSING](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_1ga810a43bd89a1ef6ffa39af31090ac83e) if the license key doesn’t match the MAC Address
### **emSetLicenseKey() Example**
```cpp
dwRes = emSetLicenseKey(dwInstanceId, "DA1099F2-15C249E9-54327FBC");
```
#### SEE ALSO
- [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS)
- [`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)
## emSetOemKey
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetOemKey(EC_T_UINT64 qwOemKey)
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetOemKey([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_UINT64 qwOemKey)
Provide OEM Key needed for OEM Masters to parse ENI files and provide access via RAS. Must be called after initialization and before configuration.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **qwOemKey** – [in] 64 bit OEM key
### **emSetOemKey() Example**
```cpp
dwRes = emSetOemKey(dwInstanceId, 0x1234567812345678);
```
#### SEE ALSO
- [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS)
- [`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)
## emIoCtl
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatIoCtl([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCode, const EC_T_VOID \*const pbyInBuf, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInBufSize, EC_T_VOID \*const pbyOutBuf, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwOutBufSize, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*const pdwNumOutData)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emIoCtl([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCode, const EC_T_VOID \*const pbyInBuf, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInBufSize, EC_T_VOID \*const pbyOutBuf, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwOutBufSize, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*const pdwNumOutData)
A generic control interface between the application, the EtherCAT stack and its Link Layers.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwCode** – [in] IOCTL code (EC_IOCTL…)
* **pbyInBuf** – [in] IOCTL input parameters
* **dwInBufSize** – [in] Size of IOCTL input parameters in bytes
* **pbyOutBuf** – [out] Buffer for IOCTL output
* **dwOutBufSize** – [in] Size of buffer at pbyOutBuf in bytes
* **pdwNumOutData** – [out] Amount of bytes written to pbyOutBuf by IOCTL. EC_NULL: amount not set by IOCTL.
* **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, the input pointer is EC_NULL or contains EC_NULL pointer
* [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if memory cannot be allocated
* [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running
## emIoCtl - EC_IOCTL_GET_PDMEMORYSIZE
### EC_IOCTL_GET_PDMEMORYSIZE
Get the process data image size. This information may be used to provide process data image storage from outside the core. This IOCTL is to be called after network configuration.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Pointer to memory where the memory size information will be stored (type: [EC_T_MEMREQ_DESC](api_general_functions.html.md#da/df0/struct_e_c___t___m_e_m_r_e_q___d_e_s_c))
* **dwOutBufSize** – [in] Size of the output buffer in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
### struct EC_T_MEMREQ_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPDOutSize
Size of the output process data image
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPDInSize
Size of the input process data image
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_REGISTER_PDMEMORYPROVIDER
### EC_IOCTL_REGISTER_PDMEMORYPROVIDER
This function call registers an external memory provider to the stack, this memory will be used to store process data. If no memory provider is registered the stack will internally allocate the necessary amount of memory. The function [EC_IOCTL_GET_PDMEMORYSIZE](api_general_functions.html.md#d0/d35/_ec_io_ctl_8h_1aab1c5dd0794f6d2aafe8ecf3a3094b42) should be executed to determine the amount of memory the stack needs to store process data values. An external memory provider may additionally supply some hooks to give the stack a possibility to synchronize memory access with the application. Also the memory provider has to be registered after configuring the network but prior to registering any client. Every client that registers with the stack will get back the memory pointers to PDOut/PDIn data registered within this call.
* **Parameters:**
* **pbyInBuf** – [in] Memory provider ([EC_T_MEMPROV_DESC](api_general_functions.html.md#d6/df3/struct_e_c___t___m_e_m_p_r_o_v___d_e_s_c))
* **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
* **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
### struct EC_T_MEMPROV_DESC
### Public Members
### [EC_T_PVOID](toc_api.html.md#_CPPv410EC_T_PVOID) pvContext
Context pointer. This pointer is used every time one of the callback functions (e.g. pfPDOutReadRequest) is called.
### [EC_T_PBYTE](toc_api.html.md#_CPPv410EC_T_PBYTE) pbyPDOutData
Pointer to the fixed output process data buffer (values transferred from the master to the slaves). A value of EC_NULL may be given in case the pointer will be provided later when the function [EC_T_MEMPROV_DESC.pfPDOutDataReadRequest](api_general_functions.html.md#d6/df3/struct_e_c___t___m_e_m_p_r_o_v___d_e_s_c_1a2a4d36753f2c3cdbd529c578939307a6) is called.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPDOutDataLength
Length of the output process data buffer
### [EC_T_PBYTE](toc_api.html.md#_CPPv410EC_T_PBYTE) pbyPDInData
Pointer to the fixed input process data buffer (values transferred from the slaves to the master). A value of EC_NULL may be given in case the pointer will be provided later when the function [EC_T_MEMPROV_DESC.pfPDInDataWriteRequest](api_general_functions.html.md#d6/df3/struct_e_c___t___m_e_m_p_r_o_v___d_e_s_c_1ac4fa95d642804b955de5ae6cde1da477) is called.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPDInDataLength
Length of the input process data buffer
### [EC_T_PFMEMREQ](api_general_functions.html.md#_CPPv413EC_T_PFMEMREQ) pfPDOutDataReadRequest
This function will be called cyclically within the process data transfer cycle prior to reading data from the output process data buffer. If EC_NULL is set, the fixed buffer [EC_T_MEMPROV_DESC.pbyPDOutData](api_general_functions.html.md#d6/df3/struct_e_c___t___m_e_m_p_r_o_v___d_e_s_c_1a73d668e08f6422100f1df75aadd19e94) is used.
### [EC_T_PFMEMREL](api_general_functions.html.md#_CPPv413EC_T_PFMEMREL) pfPDOutDataReadRelease
This function will be called cyclically within the process data transfer cycle after all data were read from the output process data buffer
### [EC_T_PFMEMREQ](api_general_functions.html.md#_CPPv413EC_T_PFMEMREQ) pfPDOutDataWriteRequest
This function will be called cyclically within the process data transfer cycle prior to writing new data into the output process data buffer. If EC_NULL is set, the fixed buffer [EC_T_MEMPROV_DESC.pbyPDOutData](api_general_functions.html.md#d6/df3/struct_e_c___t___m_e_m_p_r_o_v___d_e_s_c_1a73d668e08f6422100f1df75aadd19e94) is used.
### [EC_T_PFMEMREL](api_general_functions.html.md#_CPPv413EC_T_PFMEMREL) pfPDOutDataWriteRelease
This function will be called cyclically within the process data transfer cycle after all data were written into the output process data buffer
### [EC_T_PFMEMREQ](api_general_functions.html.md#_CPPv413EC_T_PFMEMREQ) pfPDInDataWriteRequest
This function will be called cyclically within the process data transfer cycle prior to writing new data into the input process data buffer. If EC_NULL is set, the fixed buffer [EC_T_MEMPROV_DESC.pbyPDInData](api_general_functions.html.md#d6/df3/struct_e_c___t___m_e_m_p_r_o_v___d_e_s_c_1a46bab8e220e17412e5344c5036d31b8f) is used.
### [EC_T_PFMEMREL](api_general_functions.html.md#_CPPv413EC_T_PFMEMREL) pfPDInDataWriteRelease
This function will be called cyclically within the process data transfer cycle after all data were written into the input process data buffer
### [EC_T_PBYTE](toc_api.html.md#_CPPv410EC_T_PBYTE) pbyMasterRedPDOutData
Pointer to the MasterRed output process data buffer (ACTIVE to INACTIVE)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMasterRedPDOutDataLength
Length of the MasterRed output process data buffer
### [EC_T_PBYTE](toc_api.html.md#_CPPv410EC_T_PBYTE) pbyMasterRedPDInData
Pointer to the default input process data buffer (INACTIVE to ACTIVE)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMasterRedPDInDataLength
Length of the input process data buffer
### [EC_T_PFMEMREQ](api_general_functions.html.md#_CPPv413EC_T_PFMEMREQ) pfMasterRedPDOutReadRequest
This function will be called within the process data transfer cycle prior to reading data
### [EC_T_PFMEMREL](api_general_functions.html.md#_CPPv413EC_T_PFMEMREL) pfMasterRedPDOutReadRelease
This function will be called after all data has been read from the output process data buffer
### [EC_T_PFMEMREQ](api_general_functions.html.md#_CPPv413EC_T_PFMEMREQ) pfMasterRedPDOutWriteRequest
This function will be called within the process data transfer cycle prior to reading data
### [EC_T_PFMEMREL](api_general_functions.html.md#_CPPv413EC_T_PFMEMREL) pfMasterRedPDOutWriteRelease
This function will be called after all data were read from the output process data buffer
### [EC_T_PFMEMREQ](api_general_functions.html.md#_CPPv413EC_T_PFMEMREQ) pfMasterRedPDInWriteRequest
This function will be called within the process data transfer cycle prior to writing data
### [EC_T_PFMEMREL](api_general_functions.html.md#_CPPv413EC_T_PFMEMREL) pfMasterRedPDInWriteRelease
This function will be called after all data were written to the input process data buffer
### [EC_T_PFMEMREQ](api_general_functions.html.md#_CPPv413EC_T_PFMEMREQ) pfMasterRedPDInReadRequest
This function will be called within the process data transfer cycle prior to writing data
### [EC_T_PFMEMREL](api_general_functions.html.md#_CPPv413EC_T_PFMEMREL) pfMasterRedPDInReadRelease
This function will be called after all data were written to the input process data buffer
### typedef EC_T_VOID (\*EC_T_PFMEMREQ)([EC_T_PVOID](toc_api.html.md#_CPPv410EC_T_PVOID) pvContext, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_PBYTE](toc_api.html.md#_CPPv410EC_T_PBYTE) \*ppbyPDData)
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
* **Param dwTaskId:**
**[in]** Task ID of cyclic data transfer (ENI: Cyclic/TaskId). If TASKID_COMPLETE_PD is given, the function must return a complete output process data buffer which contains valid data for all cyclic tasks.
* **Param ppbyPDData:**
**[out]** Pointer to the process data buffer to be used. If set to EC_NULL, the corresponding fixed buffer from [EC_T_MEMPROV_DESC](api_general_functions.html.md#d6/df3/struct_e_c___t___m_e_m_p_r_o_v___d_e_s_c) is used. The provided buffer size must correspond to the caller context.
### typedef EC_T_VOID (\*EC_T_PFMEMREL)([EC_T_PVOID](toc_api.html.md#_CPPv410EC_T_PVOID) pvContext, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId)
* **Param pvContext:**
**[in]** Arbitrarily application-defined parameter passed to callback
* **Param dwTaskId:**
**[in]** Task ID of cyclic data transfer (ENI: Cyclic/TaskId)
#### SEE ALSO
- [emIoCtl - EC_IOCTL_GET_PDMEMORYSIZE](api_general_functions.html.md#emioctl-ec-ioctl-get-pdmemorysize)
- [`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)
- [`emRegisterClient()`](api_general_functions.html.md#_CPPv416emRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS)
- Feature Pack “MainDevice Redundancy”
- [`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_REGISTER_CYCFRAME_RX_CB
### EC_IOCTL_REGISTER_CYCFRAME_RX_CB
Register callback for all cyclic frames received. Typically this is used when the Real-time Ethernet Driver operates in interrupt mode to get an event when the new input data (cyclic frame) is available. The callback function has to be registered after the stack initialization and before starting the job task.
* **Parameters:**
* **pbyInBuf** – [in] Cyclic frame received callback descriptor ([EC_T_CYCFRAME_RX_CBDESC](api_general_functions.html.md#dd/dff/struct_e_c___t___c_y_c_f_r_a_m_e___r_x___c_b_d_e_s_c))
* **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
* **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
### struct EC_T_CYCFRAME_RX_CBDESC
### Public Members
### EC_T_VOID \*pCallbackContext
[in] Context pointer. This pointer is used as parameter every time the callback function is called.
### [EC_PF_CYCFRAME_RECV](api_general_functions.html.md#_CPPv419EC_PF_CYCFRAME_RECV) pfnCallback
[in] This function will be called after the cyclic frame is received, if there is more than one cyclic frame after the last frame. The application has to assure that these functions will not block.
### typedef EC_T_VOID (\*EC_PF_CYCFRAME_RECV)([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, EC_T_VOID \*pvContext)
* **Param dwTaskId:**
[in] Task id of the received cyclic frame
* **Param pvContext:**
[in] Context pointer. This pointer is used as parameter every time when the callback function is called.
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_ISLINK_CONNECTED
### EC_IOCTL_ISLINK_CONNECTED
Determine whether the main link or redundancy link is connected.
#### NOTE
See also EC_IOCTL_IS_MAIN_LINK_CONNECTED, EC_IOCTL_IS_RED_LINK_CONNECTED
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Pointer to EC_T_DWORD or EC_T_LINK_CONNECTED_INFO. EC_T_DWORD: If value is EC_TRUE link is connected, if EC_FALSE it is not.
* **dwOutBufSize** – [in] Size of the output buffer in bytes (sizeof(EC_T_DWORD) / sizeof(EC_T_LINK_CONNECTED_INFO))
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
With Redundancy support enabled, [`EC_FALSE`](toc_api.html.md#c.EC_FALSE) is only set if MainPort and RedPort are down.
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_GET_LINKLAYER_MODE
### EC_IOCTL_GET_LINKLAYER_MODE
Get Real-time Ethernet Driver mode (EcLinkMode_POLLING, EcLinkMode_INTERRUPT)
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Pointer to struct [EC_T_LINKLAYER_MODE_DESC](api_general_functions.html.md#db/d79/struct_e_c___t___l_i_n_k_l_a_y_e_r___m_o_d_e___d_e_s_c)
* **dwOutBufSize** – [in] Size of the output buffer in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
### struct EC_T_LINKLAYER_MODE_DESC
### Public Members
### [EC_T_LINKMODE](emll_init.html.md#_CPPv413EC_T_LINKMODE) eLinkMode
[out] Operation mode of main interface
### [EC_T_LINKMODE](emll_init.html.md#_CPPv413EC_T_LINKMODE) eLinkModeRed
[out] Operation mode of redundancy interface
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_GET_CYCLIC_CONFIG_INFO
### EC_IOCTL_GET_CYCLIC_CONFIG_INFO
Get cyclic configuration information from ENI file.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to dwCycEntryIndex: Cyclic entry index for which to get information
* **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes
* **pbyOutBuf** – [out] Pointer to [EC_T_CYC_CONFIG_DESC](api_general_functions.html.md#d2/d75/struct_e_c___t___c_y_c___c_o_n_f_i_g___d_e_s_c) data type
* **dwOutBufSize** – [in] Size of the output buffer provided at pbyOutBuf in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
### struct EC_T_CYC_CONFIG_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumCycEntries
[out] Total number of cyclic entries
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId
[out] Task ID of selected cyclic entry (ENI: Cyclic/TaskId)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPriority
[out] Priority of selected cyclic entry
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCycleTime
[out] Cycle time of selected cyclic entry
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_IS_SLAVETOSLAVE_COMM_CONFIGURED
### EC_IOCTL_IS_SLAVETOSLAVE_COMM_CONFIGURED
Determine if any slave to slave communication is configured.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Pointer to EC_T_DWORD. If value is EC_TRUE slave to slave communication is configured, if EC_FALSE it is not.
* **dwOutBufSize** – [in] Size of the output buffer in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_LINKIOCTL…
The generic control interface provides access to the main network adapter when adding `EC_IOCTL_LINKLAYER_MAIN` to the `EC_LINKIOCTL` parameter at dwCode.
```cpp
EC_T_DWORD dwCode = (EC_IOCTL_LINKLAYER_MAIN | EC_LINKIOCTL_GET_ETHERNET_ADDRESS);
```
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_LINKIOCTL_GET_ETHERNET_ADDRESS
Provides MAC addresses of main or red line.
**emIoCtl - EC_LINKIOCTL_GET_ETHERNET_ADDRESS**
: **Parameter**
: * `pbyInBuf`: [in] Should be set to EC_NULL
* `dwInBufSize`: [in] Should be set to 0
* `pbyOutBuf`: [out] Pointer to MAC address buffer (6 bytes)
* `dwOutBufSize`: [in] Size of the output buffer in bytes (at least 6)
* `pdwNumOutData`: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
**Return**
: EC_E_NOERROR or error code
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_LINKIOCTL_GET_SPEED
**emIoCtl - EC_LINKIOCTL_GET_SPEED**
: **Parameter**
: * `pbyInBuf`: [in] Should be set to EC_NULL
* `dwInBufSize`: [in] Should be set to 0
* `pbyOutBuf`: [out] Pointer to EC_T_DWORD. Set by Real-time Ethernet Driver to 10/100/1000.
* `dwOutBufSize`: [in] Size of the output buffer in bytes
* `pdwNumOutData`: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
**Return**
: EC_E_NOERROR or error code
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_LINKIOCTL_GET_PCI_INFO
Get current network adapter’s PCI information
**emIoCtl - EC_LINKIOCTL_GET_PCI_INFO**
: **Parameter**
: * `pbyInBuf`: [in] Should be set to EC_NULL
* `dwInBufSize`: [in] Should be set to 0
* `pbyOutBuf`: [out] Pointer to EC_T_PCI_INFO buffer
* `dwOutBufSize`: [in] Size of the output buffer in bytes. Must be at least the size of EC_T_PCI_INFO.
* `pdwNumOutData`: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
**Return**
: EC_E_NOERROR or error code
### struct EC_T_PCI_INFO
### Public Members
### [EC_T_PCI_INFO_LOCATION](api_general_functions.html.md#_CPPv422EC_T_PCI_INFO_LOCATION) Location
PCI location (bus, device, function)
### [EC_T_PCI_INFO_IDENIFICATION](api_general_functions.html.md#_CPPv427EC_T_PCI_INFO_IDENIFICATION) Ident
PCI identification (vendor id, device id)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIoBarCnt
I/O bar count
### [EC_T_PCI_INFO_IOBAR](api_general_functions.html.md#_CPPv419EC_T_PCI_INFO_IOBAR) aIoBar
PCI I/O bars info
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMemBarCnt
Memory bar count
### [EC_T_PCI_INFO_MEMBAR](api_general_functions.html.md#_CPPv420EC_T_PCI_INFO_MEMBAR) aMemBar
PCI Memory bars info
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInterruptCnt
IRQ count
### [EC_T_PCI_INFO_INTERRUPT](api_general_functions.html.md#_CPPv423EC_T_PCI_INFO_INTERRUPT) aInterrupt
PCI IRQ info
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) adwReserved[16]
Reserved for future use
### struct EC_T_PCI_INFO_LOCATION
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDomainNumber
Domain
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBusNumber
Bus number
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDeviceNumber
Device number
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFunctionNumber
Function number
### struct EC_T_PCI_INFO_IDENIFICATION
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwVendorId
Vendor ID
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDeviceId
Device ID
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReserved
Reserved for future use
### struct EC_T_PCI_INFO_IOBAR
### Public Members
### EC_T_UINT64 qwBaseAddress
I/O bar base address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLen
Bar length
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReserved
Reserved for future use
### struct EC_T_PCI_INFO_MEMBAR
### Public Members
### EC_T_UINT64 qwBaseAddress
Memory bar base address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLen
Bar length
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReserved
Reserved for future use
### struct EC_T_PCI_INFO_INTERRUPT
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIrq
IRQ number
### EC_T_CPUSET CpuAffinity
Reserved for future use
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) adwReserved[2]
Reserved for future use
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_CYCFRAME_LAYOUT
### EC_IOCTL_SET_CYCFRAME_LAYOUT
Set the cyclic frames layout.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to an [EC_T_CYCFRAME_LAYOUT](api_general_functions.html.md#d0/d35/_ec_io_ctl_8h_1a6ce49d0f8cdb66e9f92560d5430268b4) value containing the cyclic frame layout
* **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes
* **pbyOutBuf** – [out] Pointer to EC_T_BOOL to carry out current enable set
* **dwOutBufSize** – [in] Size of the output buffer provided at pbyOutBuf in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.
* **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
### enum EC_T_CYCFRAME_LAYOUT
*Values:*
### enumerator eCycFrameLayout_STANDARD
Layout according ENI with command add/reordering, no relationship to PD
### enumerator eCycFrameLayout_DYNAMIC
Layout is dynamically modified to send as few as possible cyclic frames and commands
### enumerator eCycFrameLayout_FIXED
Layout strictly match ENI, frame buffers and PD area overlapped
### enumerator eCycFrameLayout_IN_DMA
Layout strictly match ENI, frame buffers and PD area overlapped, frame buffers in DMA
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_MASTER_DEFAULT_TIMEOUTS
### EC_IOCTL_SET_MASTER_DEFAULT_TIMEOUTS
Set master default timeouts.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to [EC_T_MASTERDEFAULTTIMEOUTS_DESC](api_general_functions.html.md#db/dfc/struct_e_c___t___m_a_s_t_e_r_d_e_f_a_u_l_t_t_i_m_e_o_u_t_s___d_e_s_c)
* **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
* **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
### struct EC_T_MASTERDEFAULTTIMEOUTS_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMasterStateChange
Default state change timeout [ms], applied if emSetMasterState called with EC_NOWAIT
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInitCmdRetry
Timeout [ms] between retry sending an init-command
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxCmd
Timeout [ms] between retry sending an mailbox command
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxPolling
Mailbox polling cycle [ms] ( default: 10 ms )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDcmInSync
Timeout [ms] to wait for DCM InSync in state change PREOP to SAFEOP ( default: infinite )
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wInitCmd
Timeout [ms] to InitCmds if not specified in ENI ( default: 1100 ms )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveIdentification
Timeout [ms] to wait for the reading of the slave identification ( default: 5000 )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwGenerateEni
Timeout [ms] to wait for eCnfType_GenPreopENI, eCnfType_GenOpENI, eCnfType_Gen… ( default: 30000 ms )
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBootMbxPolling
Mailbox polling cycle [ms] for Boot ( default: 10 ms )
Setting a value of this descriptor to zero resets the default timeout value to the initial value.
#### SEE ALSO
- [`emSetMasterState()`](api_general_functions.html.md#_CPPv416emSetMasterState10EC_T_DWORD10EC_T_DWORD10EC_T_STATE)
- [`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_COPYINFO_IN_SENDCYCFRAMES
### EC_IOCTL_SET_COPYINFO_IN_SENDCYCFRAMES
Set copy info processed in either [eUsrJob_SendAllCycFrames](api_general_functions.html.md#d0/d7a/_ec_interface_common_8h_1a2896339cca5c839bfe2ee15381f32dbfac36e00fb71e0a6bcad659eb942d0e04c) or in [eUsrJob_ProcessAllRxFrames](api_general_functions.html.md#d0/d7a/_ec_interface_common_8h_1a2896339cca5c839bfe2ee15381f32dbfa7812f457083c392d7242823b1696ba98).
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL. EC_TRUE: SendCycFrames, EC_FALSE: ProcessAllRxFrames.
* **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
* **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
Default: Set by ProcessAllRxFrames.
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_BUS_CYCLE_TIME
### EC_IOCTL_SET_BUS_CYCLE_TIME
Set bus cycle time [us] master parameter without calling [emInitMaster()](api_general_functions.html.md#db/d74/_ec_master_api_8cpp_1a20396c6311952930b2a5c10c2baf2131) again.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_DWORD. Value may not be 0!
* **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
* **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
Implicitly recalculates Order Timeout and [`EC_T_INIT_MASTER_PARMS::dwEcatCmdTimeout`](api_general_functions.html.md#_CPPv4N22EC_T_INIT_MASTER_PARMS16dwEcatCmdTimeoutE).
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_ADDITIONAL_VARIABLES_FOR_SPECIFIC_DATA_TYPES
### EC_IOCTL_ADDITIONAL_VARIABLES_FOR_SPECIFIC_DATA_TYPES
Enable or disable additional variables for specific data types. Default: Enabled.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: enable, EC_FALSE: disable.
* **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
* **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
Additional variables are added to the process image for the following data types:
- FSOE_4096
- FSOE_4098
- FSOE_4099
- FB Info 1
- FB Info 3
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SLV_ALIAS_ENABLE
### EC_IOCTL_SLV_ALIAS_ENABLE
Enables slave alias addressing for all slaves.
* **Parameters:**
* **pbyInBuf** – [in] Should be set to EC_NULL
* **dwInBufSize** – [in] Should be set to 0
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
#### IMPORTANT
All SubDevice need to have the correct alias address set! If in doubt, don’t use this IOCTL.
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR
### EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR
Set ignore INPUTs on WKC error.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: Ignore INPUTs on WKC error.
* **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
* **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
Calling this IOCTL with [`EC_TRUE`](toc_api.html.md#c.EC_TRUE) as parameter will ignore input data of cyclic commands on WKC error.
By default input data are updated if WKC is non zero. If WKC is not matching the expected value a notification [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR
### EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR
Set INPUTs to zero on WKC error.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: INPUTs are set to zero on WKC error.
* **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
* **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
Calling this IOCTL with [`EC_TRUE`](toc_api.html.md#c.EC_TRUE) as parameter will set inputs to zero on WKC error.
By default input data are updated if WKC is non zero. If WKC is not matching the expected value a notification [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO
### EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO
Set INPUTs to zero on WKC is zero.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: Set INPUTs to zero if WKC is zero.
* **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
* **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
Calling this IOCTL with [`EC_TRUE`](toc_api.html.md#c.EC_TRUE) as parameter will set inputs to zero on WKC is zero.
By default input data are ignored on WKC is zero and remain unchanged. If WKC is not matching the expected value a notification [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.
## emIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_FRAME_LOSS
### EC_IOCTL_SET_ZERO_INPUTS_ON_FRAME_LOSS
Set inputs to zero on frame loss.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: Set inputs to zero on frame loss
* **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
* **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
Calling this IOCTL with [`EC_TRUE`](toc_api.html.md#c.EC_TRUE) as parameter will set inputs to zero on frame loss.
By default input data are ignored on frame loss and remain unchanged.
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_GENENI_ASSIGN_EEPROM_BACK_TO_ECAT
### EC_IOCTL_SET_GENENI_ASSIGN_EEPROM_BACK_TO_ECAT
Enable or disable creation of “assign EEPROM back to ECAT” InitCmd if ENI generated based on bus-scan result.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: generate InitCmd.
* **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
* **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
The InitCmd “assign EEPROM back to ECAT” in the ENI depends on the attribute “AssignToPdi” of the EEPROM tag in the SubDevice’s description within the ESI file. Because this attribute is not reflected in the SII in the SubDevice’s EEPROM, the MainDevice cannot know its value and inserts the InitCmd by default for legacy reasons.
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED
### EC_IOCTL_SET_EOE_DEFFERED_SWITCHING_ENABLED
Enable or disable deferred EoE switching.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: Deferred EoE switching enabled.
* **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
* **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
Enabling deferred EoE switching reduces the CPU load of JOB_ProcessAllRxFrames in case of EoE communication. [`eUsrJob_SwitchEoeFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB23eUsrJob_SwitchEoeFramesE) has to be called explicitly to switch the received EoE frames between the EoE SubDevices and EoE end point(s).
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_MAILBOX_POLLING_CYCLES
### EC_IOCTL_SET_MAILBOX_POLLING_CYCLES
Change the mailbox polling interval.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to struct [EC_T_SET_MAILBOX_POLLING_CYCLES_DESC](api_general_functions.html.md#d2/d39/struct_e_c___t___s_e_t___m_a_i_l_b_o_x___p_o_l_l_i_n_g___c_y_c_l_e_s___d_e_s_c)
* **dwInBufSize** – [in] Size of the input buffer in bytes, e.g. sizeof(EC_T_SET_MAILBOX_POLLING_CYCLES_DESC)
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
### struct EC_T_SET_MAILBOX_POLLING_CYCLES_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId
[in] Slave Id
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wCycles
[in] Mailbox polling interval [ms]
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_MASTER_MAX_STATE
### EC_IOCTL_SET_MASTER_MAX_STATE
Set maximal master state. [emSetMasterState()](api_general_functions.html.md#db/d74/_ec_master_api_8cpp_1a4bedc33338cea3730b48340860bb5a21) returns with [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 the requested master state exceeds the maximal master state.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_STATE
* **dwInBufSize** – [in] Size of the input buffer in bytes, e.g. sizeof(EC_T_STATE)
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
- ### enum [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE)
- [`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_AUTO_ADJUST_MBX_STATE_COUNT_ENABLED
### EC_IOCTL_SET_AUTO_ADJUST_MBX_STATE_COUNT_ENABLED
This call specifies if the mailbox states count must be automatically adjusted according the mailbox state addresses in the ENI. This is needed if the ENI is inconsistent regarding the mailbox states, leading to Error 0x98130033 ENI: Inconsistent content. Default: Use ENI specified mailbox state count (EC_FALSE).
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL
* **dwInBufSize** – [in] Size of the input buffer in bytes, e.g. sizeof(EC_T_BOOL)
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_ACTIVATE_VOE_RECV_FIFO
### EC_IOCTL_ACTIVATE_VOE_RECV_FIFO
Activates and set the size of the VoE receive FIFO.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to value of EC_T_WORD, size of the FIFO, use 0 to set it to the original size
* **dwInBufSize** – [in] Size of the input buffer in bytes, e.g. sizeof(EC_T_WORD)
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_SET_GEN_ENI_PARM
| Identifier | Description |
|---------------------------------|----------------------------------------------------------------------------------------|
| EC_GEN_ENI_PARM_ID_SLAVE_PREFIX | Prefix of SubDevices and their variables’ names. By default the prefix is ‘SubDevice’. |
### EC_IOCTL_SET_GEN_ENI_PARM
Change the behavior when the configuration of the EtherCAT network is generated according to a bus scan result of [emConfigureNetwork()](api_general_functions.html.md#db/d74/_ec_master_api_8cpp_1a94b249de63c121ccd694c834d820b1f2) with the parameter [eCnfType_GenPreopENI](api_general_functions.html.md#d0/d7a/_ec_interface_common_8h_1a31f4f87c29827f14776e5d1df7a8f637aad07f29bb292c6d95ea715590e7d747f) or [eCnfType_GenOpENI](api_general_functions.html.md#d0/d7a/_ec_interface_common_8h_1a31f4f87c29827f14776e5d1df7a8f637aeccdaf2f1fd20bd2f50ae9a51ad37818). In that case, default settings are taken to set e.g. the name of the EtherCAT slave device. The next table gives an overview about the possible parameters to be changed.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to struct [EC_T_SET_GEN_ENI_PARM](api_general_functions.html.md#dc/d89/struct_e_c___t___s_e_t___g_e_n___e_n_i___p_a_r_m)
* **dwInBufSize** – [in] Size of the input buffer in bytes, e.g. sizeof(EC_T_SET_GEN_ENI_PARM)
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
### struct EC_T_SET_GEN_ENI_PARM
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwParmId
ID of parameter to be set (EC_GEN_ENI_PARM_ID_…)
### [EC_T_GEN_ENI_PARM](api_general_functions.html.md#_CPPv417EC_T_GEN_ENI_PARM) GenEniParm
Value of parameter to be set
### union EC_T_GEN_ENI_PARM
### Public Members
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szSlaveNamePrefix[MAX_SHORT_STRLEN + 1]
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIgnoreScanBusError
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
## emIoCtl - EC_IOCTL_REALLOC_MBX_QUEUE
### EC_IOCTL_REALLOC_MBX_QUEUE
Reallocate the mailbox queues of the different mailbox protocols.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to struct [EC_T_REALLOC_MBX_QUEUE_DESC](api_general_functions.html.md#d3/d09/struct_e_c___t___r_e_a_l_l_o_c___m_b_x___q_u_e_u_e___d_e_s_c)
* **dwInBufSize** – [in] Size of the input buffer in bytes, e.g. sizeof(EC_T_REALLOC_MBX_QUEUE_DESC)
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
### struct EC_T_REALLOC_MBX_QUEUE_DESC
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveFixedAddress
Slave fixed address, 0 for all slaves
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMbxProtocols
Combination of Mbx protocols EC_MBX_PROTOCOL_COE…
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxMbxTferQueued
Maximal number of transfers queued for the specified mailbox protocol of the specified slave
#### SEE ALSO
[`emIoCtl()`](api_general_functions.html.md#_CPPv47emIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)
# api_multi_bus.html.md
# Multiple EtherCAT® Bus Support
## Licensing
Multiple EtherCAT® Bus support is included within the Class B and Class A MainDevice stack. For each bus a separate runtime license is required. A single runtime allows the usage of the multi instance functions only with an instance identifier of 0.
## Overview
The acontis EtherCAT® MainDevice allows controlling more than one EtherCAT® bus within one application process. For this use case the MainDevice core is instantiated several times by using the multi instance API functions inside the application.
Each API function is available as a single instance version (prefix ecat, e.g. [`ecatInitMaster()`](api_general_functions.html.md#_CPPv414ecatInitMasterPK22EC_T_INIT_MASTER_PARMS)) and a multi instance version (prefix em, e.g. [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS)).
The first parameter of all multi instance functions `emXxx()` is the instance identifier.
The single instance functions `ecatXxx()` will use the first MainDevice core instance with the identifier 0.
The maximum number of supported instances is 12 (MAX_NUMOF_MASTER_INSTANCES).
## Example application
The application EcMasterDemoMulti demonstrates a client application which handles two MainDevice instances with the following configuration (el9800.xml):
- MainDevice instance 0: One Beckhoff EtherCAT® Evaluation Board EL9800
- MainDevice instance 1: One Beckhoff EtherCAT® Evaluation Board EL9800
Parameters for this application:
```console
$ -ndis 192.168.1.32 1 -f el9800.xml @ -ndis 192.168.2.32 1 -f el9800.xml
```
# api_notifications.html.md
# Generic notification interface
One of the parameters the client has to set when registering with the EtherCAT® MainDevice is a generic notification callback function ( `emNotify()`). The MainDevice calls this function every time an event (for example an error event) occurs about which the client has to be informed.
Within this callback function the client must not call any active EtherCAT® functions which finally would lead to send EtherCAT® commands (e.g. initiation of mailbox transfers, starting/stopping the MainDevice, sending raw commands). In such cases the behavior is undefined.
This callback function is usually called in the context of the EtherCAT® MainDevice timer thread or the EtherCAT® Real-time Ethernet Driver receiver thread. It may also be called within the context of a user thread (when calling an EtherCAT® MainDevice function). To avoid dead-lock situations the notification callback handler may not use mutex semaphores.
As the whole EtherCAT® operation is blocked while calling this function the error handling must not use much CPU time or even call operating system functions that may block. Usually the error handling will be done in a separate application thread.
## Notification callback: emNotify
When a client registers with the EtherCAT® MainDevice the client has to determine a generic notification callback function. The MainDevice calls this function every time an event (for example an error event or operational state change event) occurs about which the client has to be informed. Within this callback function the client must not call any active EtherCAT® functions which finally would lead to sending EtherCAT® commands (e.g. initiation of mailbox transfers, starting/stopping the MainDevice, sending raw commands). In such cases the behavior is undefined. Only EtherCAT® functions which are explicitly marked to be callable within `emNotify()` may be called.
A further important rule exists due to the fact that this callback function is usually called in the context of the EtherCAT® MainDevice timer thread. As the whole EtherCAT® operation is blocked while calling this function the notification handler must not use much CPU time or even call operating system functions that may block. Time consuming operations should be executed in separate application threads.
### typedef [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) (\*[EC_PF_NOTIFY](api_general_functions.html.md#_CPPv412EC_PF_NOTIFY))([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](api_notifications.html.md#_CPPv416EC_T_NOTIFYPARMS) \*pParms)
### struct EC_T_NOTIFYPARMS
Data structure filled with detailed information about the according notification.
### Public Members
### EC_T_VOID \*pCallerData
[in] Client depending caller data parameter. This pointer is one of the parameters when the client registers.
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyInBuf
[in] Notification input parameters
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInBufSize
[in] Size of notification input parameters in bytes
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyOutBuf
[out] Buffer for notification output (result)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwOutBufSize
[in] Size of buffer at pbyOutBuf in bytes
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOutData
[out] Amount of bytes written to pbyOutBuf by notification. EC_NULL: amount not set by notification.
## emNotify - EC_NOTIFY_STATECHANGED
Notification about a change in the MainDevice’s operational state. This notification is enabled by default.
**emNotify - EC_NOTIFY_STATECHANGED**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to data of type EC_T_STATECHANGE which contains the old and the new MainDevice operational state
* `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_STATECHANGE
### Public Members
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) oldState
Old operational state
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) newState
New operational state
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the deactivation
## emNotify - EC_NOTIFY_XXXX
Notification about an error.
**emNotify - EC_NOTIFY_XXXX**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to data of type EC_T_ERROR_NOTIFICATION_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
#### SEE ALSO
[Diagnosis, error detection, error notifications](api_diagnosis.html.md#diagnosis-error-detection-error-notifications)
## Feature Pack MainDevice Redundancy Notifcations
#### SEE ALSO
Feature Pack “MainDevice Redundancy”
## emNotifyApp
By calling this function the generic notification callback function setup by [`emRegisterClient()`](api_general_functions.html.md#_CPPv416emRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS) is called for all clients including RAS.
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatNotifyApp([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](api_notifications.html.md#_CPPv416EC_T_NOTIFYPARMS) \*pParms)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emNotifyApp([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](api_notifications.html.md#_CPPv416EC_T_NOTIFYPARMS) \*pParms)
Calls the notification callback functions of all registered clients.
#### NOTE
EC_E_ERROR and EC_E_INVALIDPARM from registered clients’ callback functions are ignored.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwCode** – [in] Application specific notification code. dwCode must be <= EC_NOTIFY_APP_MAX_CODE. The callback functions get “EC_NOTIFY_APP | dwCode” as parameter.
* **pParms** – [in] Parameter to all callback functions. Note: Output parameters are not transferred from RAS client to RAS server.
* **Returns:**
[EC_E_ERROR](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_1gae45dc6c94a43aa671697ecc700555c22) or first error code different from [EC_E_ERROR](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_1gae45dc6c94a43aa671697ecc700555c22) and [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) of registered clients’ callback functions
The maximum value for dwCode is defined by `EC_NOTIFY_APP_MAX_CODE`
## emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED
The following notifications can be enabled or disabled.
- [emNotify - EC_NOTIFY_SLAVE_STATECHANGED](api_slave_control.html.md#emnotify-ec-notify-slave-statechanged) (default Off)
- [emNotify - EC_NOTIFY_SLAVES_STATECHANGED](api_slave_control.html.md#emnotify-ec-notify-slaves-statechanged) (default Off)
- [emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE](api_diagnosis.html.md#emnotify-ec-notify-slave-unexpected-state) (default On)
- [emNotify - EC_NOTIFY_SLAVES_UNEXPECTED_STATE](api_diagnosis.html.md#emnotify-ec-notify-slaves-unexpected-state) (default Off)
- [emNotify - EC_NOTIFY_SLAVE_PRESENCE](api_busscan.html.md#emnotify-ec-notify-slave-presence) (default On)
- [emNotify - EC_NOTIFY_SLAVES_PRESENCE](api_busscan.html.md#emnotify-ec-notify-slaves-presence) (default Off)
- [emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO](api_diagnosis.html.md#emnotify-ec-notify-slave-error-status-info) (default On)
- [emNotify - EC_NOTIFY_SLAVES_ERROR_STATUS](api_diagnosis.html.md#emnotify-ec-notify-slaves-error-status) (default Off)
- [emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL](api_diagnosis.html.md#emnotify-ec-notify-not-all-devices-operational) (default On)
- [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) (default On)
- [emNotify - EC_NOTIFY_SB_MISMATCH](api_busscan.html.md#emnotify-ec-notify-sb-mismatch) (default On)
- [emNotify - EC_NOTIFY_SB_STATUS](api_busscan.html.md#emnotify-ec-notify-sb-status) (default On)
- [emNotify - EC_NOTIFY_STATUS_SLAVE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-status-slave-error) (default On)
- [emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-frame-response-error) (default On)
- [emNotify - EC_NOTIFY_HC_TOPOCHGDONE](api_busscan.html.md#emnotify-ec-notify-hc-topochgdone) (default On)
- [emNotify - EC_NOTIFY_STATECHANGED](api_notifications.html.md#emnotify-ec-notify-statechanged) (default On)
- [emNotify - EC_NOTIFY_COE_INIT_CMD](mbx_coe.html.md#emnotify-ec-notify-coe-init-cmd) (default Off)
- `EC_NOTIFY_JUNCTION_RED_CHANGE` (default Off)
- [emNotify - EC_NOTIFY_ALL_DEVICES_OPERATIONAL](api_diagnosis.html.md#emnotify-ec-notify-all-devices-operational) (default Off)
- `EC_NOTIFY_DC_STATUS` (default On)
- `EC_NOTIFY_DC_SLV_SYNC` (default On)
- `EC_NOTIFY_DCM_SYNC` (default On)
- [emNotify - EC_NOTIFY_SLAVE_INITCMD_RESPONSE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-slave-initcmd-response-error) (default On)
- `EC_NOTIFY_REFCLOCK_PRESENCE` (default Off)
- `EC_NOTIFY_DCX_SYNC` (default On)
- `EC_NOTIFY_HC_DETECTADDGROUPS` (default On)
- [emNotify - EC_NOTIFY_FRAMELOSS_AFTER_SLAVE](api_busscan.html.md#emnotify-ec-notify-frameloss-after-slave) (default On)
- [emNotify - EC_NOTIFY_ETH_LINK_NOT_CONNECTED](api_diagnosis.html.md#emnotify-ec-notify-eth-link-not-connected) (default On)
- [emNotify - EC_NOTIFY_S2SMBX_ERROR](api_diagnosis.html.md#emnotify-ec-notify-s2smbx-error) (default On)
- [emNotify - EC_NOTIFY_SLAVE_INITCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-slave-initcmd-wkc-error) (default On)
- [emNotify - EC_NOTIFY_BAD_CONNECTION](api_diagnosis.html.md#emnotify-ec-notify-bad-connection) (default On)
### EC_IOCTL_SET_NOTIFICATION_ENABLED
Set notification enabled state. With [EC_T_SET_NOTIFICATION_ENABLED_PARMS::dwCode](api_notifications.html.md#d6/ddc/struct_e_c___t___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d___p_a_r_m_s_1ae1b2f429de202edb4e017449955a8800) set to EC_ALL_NOTIFICATIONS, all notifications can be changed at once. [EC_T_SET_NOTIFICATION_ENABLED_PARMS::dwEnabled](api_notifications.html.md#d6/ddc/struct_e_c___t___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d___p_a_r_m_s_1a322df8c32453561c2be96821b3d3e1db) set to EC_NOTIFICATION_DEFAULT, resets to default.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to [EC_T_SET_NOTIFICATION_ENABLED_PARMS](api_notifications.html.md#d6/ddc/struct_e_c___t___s_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d___p_a_r_m_s).
* **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
* **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
### struct EC_T_SET_NOTIFICATION_ENABLED_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId
[in] Client ID, 0: Master
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCode
[in] Notification code or EC_ALL_NOTIFICATIONS
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwEnabled
[in] Enable, disable or reset to default notification. See EC_NOTIFICATION_ flags.
Notifications are given to clients if enabled for dwClientId = 0 AND corresponding dwClientId.
## emIoCtl - EC_IOCTL_GET_NOTIFICATION_ENABLED
### EC_IOCTL_GET_NOTIFICATION_ENABLED
The enabled state of notifications can be retrieved using [EC_IOCTL_GET_NOTIFICATION_ENABLED](api_notifications.html.md#d0/d35/_ec_io_ctl_8h_1a925565a04161b26d801353adb08054dd).
* **Parameters:**
* **pbyInBuf** – [in] Pointer to [EC_T_GET_NOTIFICATION_ENABLED_PARMS](api_notifications.html.md#dc/d03/struct_e_c___t___g_e_t___n_o_t_i_f_i_c_a_t_i_o_n___e_n_a_b_l_e_d___p_a_r_m_s)
* **dwInBufSize** – [in] Size of the input buffer provided at pbyInBuf in bytes
* **pbyOutBuf** – [out] Pointer to EC_T_BOOL to carry out current enable set
* **dwOutBufSize** – [in] Size of the output buffer provided at pbyOutBuf in bytes
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer
* **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
### struct EC_T_GET_NOTIFICATION_ENABLED_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId
[in] Client ID, 0: Master
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCode
[in] Notification code
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled)
# api_perfmeas.html.md
# Performance Measurement
The acontis EC-Master software has a built-in performance measurement capability. This can be used to measure the execution times of the job functions that are called within the cyclic part of the application, as well as application specific functions. These executions times can be recorded both in form of overall statistics (min/avg/max) and in form of histograms.
## Enabling performance measurements
Performance measurements need to be enabled inside the MainDevice init parms.
```cpp
/* enable performance measurements */
oInitParms.PerfMeasInternalParms.bEnabled = EC_TRUE;
/* initialize the MainDevice */
dwRes = ecatInitMaster(&oInitParms);
```
#### SEE ALSO
[`EC_T_PERF_MEAS_INTERNAL_PARMS`](api_general_functions.html.md#_CPPv429EC_T_PERF_MEAS_INTERNAL_PARMS)
## Retrieving overall performance statistics (min/avg/max)
Performance measurements in the example application can be activated using the command line parameter (-perf). It enables performance measurements and performance histograms as well. The resulting measurement values are recorded every few seconds to the log file, and printed to the console in the following format:
```text
PerfMsmt 'JOB_ProcessAllRxFrames' (min/avg/max) [us]: 12.5/ 15.9/ 25.6
PerfMsmt 'JOB_SendAllCycFrames ' (min/avg/max) [us]: 3.6/ 5.7/ 14.8
PerfMsmt 'JOB_MasterTimer ' (min/avg/max) [us]: 2.1/ 3.7/ 8.2
PerfMsmt 'JOB_SendAcycFrames ' (min/avg/max) [us]: 0.3/ 0.6/ 2.6
PerfMsmt 'Cycle Time ' (min/avg/max) [us]: 918.4/ 999.6/1067.9
PerfMsmt 'myAppWorkPd ' (min/avg/max) [us]: 0.1/ 0.4/ 0.8
PerfMsmt 'JOB_Total ' (min/avg/max) [us]: 19.0/ 25.9/ 39.2
```
In an application these values can be retrieved using the emPerfMeasGet/emPerfMeasAppGet APIs. These APIs require the index of a measurement point. Note that the index of a particular measurement point is implementation defined and not the same in all versions. It should therefore be detected at runtime using emPerfMeasGetInfo. The following example shows how measurements for JOB_ProcessAllRxFrames can be retrieved:
```cpp
EC_T_DWORD dwProcessAllRxFramesIdx = 0;
EC_T_DWORD dwMeasNum = 0;
dwRes = ecatPerfMeasGetNumOf(&dwMeasNum);
/* find index of perf measurement */
for (EC_T_DWORD i = 0; i < dwMeasNum; ++i)
{
EC_T_PERF_MEAS_INFO PerfMeasInfo;
dwRes = ecatPerfMeasGetInfo(i, &PerfMeasInfo, 1);
if (0 == OsStrncmp("JOB_ProcessAllRxFrames", PerfMeasInfo.szName, OsStrlen("JOB_ProcessAllRxFrames") + 1))
{
dwProcessAllRxFramesIdx = i;
break;
}
}
/* retrieve values */
EC_T_PERF_MEAS_VAL PerfMeasVal;
dwRes = ecatPerfMeasGetRaw(dwProcessAllRxFramesIdx, &PerfMeasVal, EC_NULL, 1);
```
## Recording performance histograms
In addition to the overall statistics described above it is possible to create a histogram of all results of a particular benchmark. The histogram has the following format:
```cpp
/* enabling histograms */
EC_T_PERF_MEAS_COUNTER_PARMS* pHistParms = EC_NULL;
pHistParms = &oInitParms.PerfMeasInternalParms.HistogramParms;
/* amount of bins to use for the histogram */
pHistParms->dwBinCount = 1000;
/* range of the histograms.
* - results below qwMinTicks are stored in the first bin
* - results above qwMaxTicks are stored in the last bin
*
* a good starting point is the range 0 <-> 2 * the amount of ticks per cycle
*/
pHistParms->qwMinTicks = 0;
pHistParms->qwMaxTicks = 2 * qwTicksPerCycle;
/* initialize the MainDevice */
dwRes = ecatInitMaster(&oInitParms);
```
#### SEE ALSO
[`EC_T_PERF_MEAS_HISTOGRAM_PARMS`](api_general_functions.html.md#_CPPv430EC_T_PERF_MEAS_HISTOGRAM_PARMS)
Similar to the overall statistics it is possible to retrieve the histograms using emPerfMeasGetRaw:
```cpp
/* retrieve values */
EC_T_PERF_MEAS_HISTOGRAM PerfMeasHist;
PerfMeasHist.aBins = (EC_T_DWORD*)OsMalloc(dwBinCount * sizeof(EC_T_DWORD));
PerfMeasHist.dwBinCount = dwBinCount;
dwRes = ecatPerfMeasGetRaw(dwProcessAllRxFramesIdx, EC_NULL, &PerfMeasHist, 1);
```
## Special benchmark types
In addition to the normal benchmarks as described above, there are some special benchmark types which are flagged in [`EC_T_PERF_MEAS_INFO`](api_perfmeas.html.md#_CPPv419EC_T_PERF_MEAS_INFO).
### EC_T_PERF_MEAS_FLAG_OFFSET
Distance benchmarks are used to measure the time between the cycle start and the benchmark start. This flag has no influence on the measurement and is simply passed through to the application.
### EC_T_PERF_MEAS_FLAG_LONG_TIMER
Changes the default of qwMinTicks/qwMaxTicks selected when passing qwMinTicks=qwMinTicks=0 from `0 - cycle time` to `0.5 * cycle time - 1.5 * cycle time`
## Application benchmarks
In addition to the internal benchmarks it is possible to create application specific benchmarks using the emPerfMeasApp API.
```cpp
static EC_T_PERF_MEAS_INFO_PARMS S_aPerfMeasInfos[] =
{
{"myBench", 0}
};
#define APPL_PERF_MEAS_NUM (sizeof(S_aPerfMeasInfos) / sizeof(S_aPerfMeasInfos[0]))
#define PERF_myBench 0
EC_T_PERF_MEAS_APP_PARMS oPerfMeasAppParms;
OsMemset(&oPerfMeasAppParms, 0, sizeof(EC_T_PERF_MEAS_APP_PARMS));
oPerfMeasAppParms.dwNumMeas = APPL_PERF_MEAS_NUM;
oPerfMeasAppParms.aPerfMeasInfos = S_aPerfMeasInfos;
dwRes = ecatPerfMeasAppCreate( &oPerfMeasAppParms, EC_NULL);
ecatPerfMeasAppStart(EC_NULL, PERF_myBench);
/* benchmarked work */
ecatPerfMeasAppEnd(EC_NULL, PERF_myBench);
```
## API
### emPerfMeasAppCreate
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasAppCreate([EC_T_PERF_MEAS_APP_PARMS](api_perfmeas.html.md#_CPPv424EC_T_PERF_MEAS_APP_PARMS) \*pPerfMeasAppParms, EC_T_VOID \*\*ppvPerfMeas)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasAppCreate([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_PERF_MEAS_APP_PARMS](api_perfmeas.html.md#_CPPv424EC_T_PERF_MEAS_APP_PARMS) \*pPerfMeasAppParms, EC_T_VOID \*\*ppvPerfMeas)
Create a PerfMeas object and bind it to the master instance.
This API can be called multiple times to create PerfMeas objects. The performance counters in each of the objects can be accessed in the following two ways:
* by passing the PerfMeas object and the index of the performance measurement. The index ranges from [0-pPerfMeasAppParms->dwNumAppMeas].
* by passing EC_NULL instead of a PerfMeas object and an index. In this case the index works across all PerfMeas objects bound to the master instance.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pPerfMeasAppParms** – [in] Pointer to parameter definitions
* **ppvPerfMeas** – [out] Created PerfMeas object
* **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
### struct EC_T_PERF_MEAS_APP_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumMeas
[in] Number of performance counters to create
### EC_T_PERF_MEAS_INFO_PARMS \*aPerfMeasInfos
[in] PerfMeasInfos associated with the corresponding benchmark
### [EC_T_PERF_MEAS_COUNTER_PARMS](api_general_functions.html.md#_CPPv428EC_T_PERF_MEAS_COUNTER_PARMS) CounterParms
[in] Timer function settings. When not provided OsMeasGetCounterTicks is used.
### [EC_T_PERF_MEAS_HISTOGRAM_PARMS](api_general_functions.html.md#_CPPv430EC_T_PERF_MEAS_HISTOGRAM_PARMS) HistogramParms
[in] Histogram settings. When not provided the histogram is disabled.
### emPerfMeasAppDelete
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasAppDelete(EC_T_VOID \*pvPerfMeas)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasAppDelete([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_VOID \*pvPerfMeas)
Delete application performance measurement and unbind it from the master instance.
Objects which are not deleted using PerfMeasAppDelete are automatically deleted when calling DeinitMaster.
#### NOTE
This invalidates the global index used when passing EC_NULL into the other PerfMeasApp functions
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pvPerfMeas** – [in] PerfMeas object to delete
* **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
### emPerfMeasAppStart
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasAppStart(EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasAppStart([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex)
Start application performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pvPerfMeas** – [in] PerfMeas object or EC_NULL to use continuous index
* **dwIndex** – [in] Index of the performance measurement
* **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
### emPerfMeasAppEnd
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasAppEnd(EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasAppEnd([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex)
Stop application performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pvPerfMeas** – [in] PerfMeas object or EC_NULL to use continuous index
* **dwIndex** – [in] Index of the performance measurement
* **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
### emPerfMeasAppReset
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasAppReset(EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasAppReset([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex)
Reset application performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pvPerfMeas** – [in] PerfMeas object or EC_NULL to use continuous index
* **dwIndex** – [in] Index of the performance measurement, use EC_PERF_MEAS_ALL to reset all
* **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
### emPerfMeasAppGetNumOf
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasAppGetNumOf(EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasAppGetNumOf([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOf)
Reset number of application performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pvPerfMeas** – [in] PerfMeas object or EC_NULL to get the number of performance measurements in all PerfMeas objects
* **pdwNumOf** – [out] Number of performance measurements
* **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
### emPerfMeasAppGetInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasAppGetInfo(EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex, [EC_T_PERF_MEAS_INFO](api_perfmeas.html.md#_CPPv419EC_T_PERF_MEAS_INFO) \*pPerfMeasInfo, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPerfMeasNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasAppGetInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex, [EC_T_PERF_MEAS_INFO](api_perfmeas.html.md#_CPPv419EC_T_PERF_MEAS_INFO) \*pPerfMeasInfo, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPerfMeasNumOf)
Get general info about one/all application performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pvPerfMeas** – [in] PerfMeas object or EC_NULL to use continuous index
* **dwIndex** – [in] Index of the performance measurement information, use EC_PERF_MEAS_ALL to get all
* **pPerfMeasInfo** – [out] Pointer to a buffer receiving one/all performance measurement information
* **dwPerfMeasNumOf** – [in] Number of elements allocated in pPerfMeasInfo
* **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
### struct EC_T_PERF_MEAS_INFO
### Public Members
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szName[MAX_STD_STRLEN]
Name of the benchmark
### EC_T_UINT64 qwFrequency
Frequency in Hz used by the timer
### [EC_T_USER_JOB](api_general_functions.html.md#_CPPv413EC_T_USER_JOB) eUserJob
UserJob associated with the benchmark
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBinCountHistogram
Length of Histogram Bins
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags
Flags associated with the benchmark (See EC_T_PERF_MEAS_FLAG…)
### emPerfMeasAppGetRaw
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasAppGetRaw(EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex, [EC_T_PERF_MEAS_VAL](api_perfmeas.html.md#_CPPv418EC_T_PERF_MEAS_VAL) \*pPerfMeasVal, [EC_T_PERF_MEAS_HISTOGRAM](api_perfmeas.html.md#_CPPv424EC_T_PERF_MEAS_HISTOGRAM) \*pPerfMeasHistogram, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPerfMeasNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasAppGetRaw([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, EC_T_VOID \*pvPerfMeas, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex, [EC_T_PERF_MEAS_VAL](api_perfmeas.html.md#_CPPv418EC_T_PERF_MEAS_VAL) \*pPerfMeasVal, [EC_T_PERF_MEAS_HISTOGRAM](api_perfmeas.html.md#_CPPv424EC_T_PERF_MEAS_HISTOGRAM) \*pPerfMeasHistogram, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPerfMeasNumOf)
Get raw data of one/all application performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pvPerfMeas** – [in] PerfMeas object or EC_NULL to use continuous index
* **dwIndex** – [in] Index of the performance measurement, use EC_PERF_MEAS_ALL to get all
* **pPerfMeasVal** – [out] Pointer to a buffer receiving one/all performance measurement values or EC_NULL
* **pPerfMeasHistogram** – [out] Pointer to a buffer receiving one/all performance measurement histograms or EC_NULL
* **dwPerfMeasNumOf** – [in] Number of elements allocated in pPerfMeasVal and pPerfMeasHistogram
* **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
### struct EC_T_PERF_MEAS_VAL
### Public Members
### EC_T_UINT64 qwCurrTicks
[ticks]
### EC_T_UINT64 qwMinTicks
[ticks]
### EC_T_UINT64 qwMaxTicks
[ticks]
### EC_T_UINT64 qwAvgTicks
[ticks]
### struct EC_T_PERF_MEAS_HISTOGRAM
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*aBins
Histogram Bins:
The first bin is used for times below
`dwMinTicks`. The last bin is used for times equal and above `dwMaxTicks`. All other times are stored in `dwBinCount - 2`
bins of equal size.
With e.g. dwBinCount = 202
qwMinTicks corresponding to 500us
qwMaxTicks corresponding to 1500us
aBins[0]: (-inf, 500us) corresponds to -inf < x < 500us
aBins[1]: [500us, 505us) corresponds to 500us <= x < 505us
aBins[2]: [505us, 510us) corresponds to 505us <= x < 510us
…
aBins[199]: [1490us, 1495us) corresponds to 1490us <= x < 1495us
aBins[200]: [1495us, 1500us) corresponds to 1495us <= x < 1500us
aBins[201]: [1500us, inf+) corresponds to 1500us <= x < inf+
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBinCount
Length of aBins
### EC_T_UINT64 qwMinTicks
Results below qwMinTicks are stored in the first bin
### EC_T_UINT64 qwMaxTicks
Results above qwMaxTicks are stored in the last bin
### emPerfMeasResetByTaskId
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasResetByTaskId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasResetByTaskId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex)
Reset internal performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwTaskId** – [in] Task Job ID
* **dwIndex** – [in] Index of the performance measurement, use EC_PERF_MEAS_ALL to reset all
* **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
### emPerfMeasGetNumOfByTaskId
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasGetNumOfByTaskId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasGetNumOfByTaskId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOf)
Reset number of internal performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwTaskId** – [in] Task Job ID
* **pdwNumOf** – [out] Number of performance measurements
* **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
### emPerfMeasGetInfoByTaskId
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasGetInfoByTaskId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex, [EC_T_PERF_MEAS_INFO](api_perfmeas.html.md#_CPPv419EC_T_PERF_MEAS_INFO) \*pPerfMeasInfo, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPerfMeasNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasGetInfoByTaskId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex, [EC_T_PERF_MEAS_INFO](api_perfmeas.html.md#_CPPv419EC_T_PERF_MEAS_INFO) \*pPerfMeasInfo, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPerfMeasNumOf)
Get general info about one/all internal performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwTaskId** – [in] Task Job ID
* **dwIndex** – [in] Index of the performance measurement, use EC_PERF_MEAS_ALL to get all
* **pPerfMeasInfo** – [out] Pointer to a buffer receiving one/all performance measurement infos
* **dwPerfMeasNumOf** – [in] Number of elements allocated in pPerfMeasInfo
* **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
### emPerfMeasGetRawByTaskId
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatPerfMeasGetRawByTaskId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex, [EC_T_PERF_MEAS_VAL](api_perfmeas.html.md#_CPPv418EC_T_PERF_MEAS_VAL) \*pPerfMeasVal, [EC_T_PERF_MEAS_HISTOGRAM](api_perfmeas.html.md#_CPPv424EC_T_PERF_MEAS_HISTOGRAM) \*pPerfMeasHistogram, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPerfMeasNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emPerfMeasGetRawByTaskId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIndex, [EC_T_PERF_MEAS_VAL](api_perfmeas.html.md#_CPPv418EC_T_PERF_MEAS_VAL) \*pPerfMeasVal, [EC_T_PERF_MEAS_HISTOGRAM](api_perfmeas.html.md#_CPPv424EC_T_PERF_MEAS_HISTOGRAM) \*pPerfMeasHistogram, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPerfMeasNumOf)
Get raw data of one/all application performance measurement.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwTaskId** – [in] Task Job ID
* **dwIndex** – [in] Index of the performance measurement, use EC_PERF_MEAS_ALL to get all
* **pPerfMeasVal** – [out] Pointer to a buffer receiving one/all performance measurement values or EC_NULL
* **pPerfMeasHistogram** – [out] Pointer to a buffer receiving one/all performance measurement histograms or EC_NULL
* **dwPerfMeasNumOf** – [in] Number of elements allocated in pPerfMeasVal and pPerfMeasHistogram
* **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
# api_process_data.html.md
# Process Data Access
## emGetProcessData
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetProcessData([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwOffset, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLength, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetProcessData([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwOffset, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Blocking function to retrieve consistent process data from outside the JobTask context.
This function requests a copy of the process data (stored in RAM). The actual memcpy operation is executed by the JobTask to ensure data consistency. While waiting for the copy to complete, the calling context blocks and repeatedly calls sleep with an interval of at least the cycle time or one millisecond, whichever is greater. The function returns either with the requested process data once the copy is finished, or when the specified timeout has expired.
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 is 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
The function is blocking and should be used carefully in time-sensitive contexts and may not be called from within the JobTask context.
#### 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 transferred data
* **dwDataLen** – [in] Buffer length [bytes]
* **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
### **emGetProcessData() Example**
```cpp
/* get Process data (synchronized with JobTask) */
EC_T_BYTE abyData[1] = { 0 };
dwRes = emGetProcessData(dwInstanceId, EC_FALSE, 0 /* byte offset */,
abyData, 1 /* byte length */, 5000);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
"Process Data: 0x%02X\n", abyData[0]));
```
## emGetProcessDataBits
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetProcessDataBits([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyDataDst, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitLengthDst, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetProcessDataBits([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataBitLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_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 transferred data
* **dwDataBitLen** – [in] Buffer length [bit]
* **dwTimeout** – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.
* **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
[`emGetProcessData()`](api_process_data.html.md#_CPPv416emGetProcessData10EC_T_DWORD9EC_T_BOOL10EC_T_DWORDP9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD)
### **emGetProcessDataBits() Example**
```cpp
/* get bits from Process Data Image (synchronized with JobTask) */
EC_T_BYTE abyData[1] = { 0 };
dwRes = emGetProcessDataBits(dwInstanceId, EC_FALSE, 0 /* bit offset */,
abyData, 8 /* bit length */, 5000);
```
## emSetProcessData
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetProcessData([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwOffset, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLength, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetProcessData([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwOffset, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_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 transferred data
* **dwDataLen** – [in] Buffer length [bytes]
* **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
### **emSetProcessData() Example**
```cpp
/* write value 0x12 to Process Data Image (synchronized with JobTask) */
EC_T_BYTE abyData[1] = { 0x12 };
dwRes = emSetProcessData(dwInstanceId, EC_FALSE, 0 /* byte offset */,
abyData, 1 /* byte length */, 5000);
```
## emSetProcessDataBits
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetProcessDataBits([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyDataSrc, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitLengthSrc, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetProcessDataBits([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataBitLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_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 transferred data
* **dwDataBitLen** – [in] Buffer length [bit]
* **dwTimeout** – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.
* **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
[`emSetProcessData()`](api_process_data.html.md#_CPPv416emSetProcessData10EC_T_DWORD9EC_T_BOOL10EC_T_DWORDP9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD)
### **emSetProcessDataBits() Example**
```cpp
/* write bits to Process Data Image (synchronized with JobTask) */
EC_T_BYTE abyData[1] = { 0x12 };
dwRes = emSetProcessDataBits(dwInstanceId, EC_TRUE, 0 /* bit offset */,
abyData, 8 /* bit length */, 5000);
```
## emForceProcessDataBits
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatForceProcessDataBits([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wBitLength, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emForceProcessDataBits([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDataBitLen, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Force a specific number of bits from a given buffer to the process image with a bit offset.
All output data set by this API are overwriting the values set by the application. All input data set by this API are overwriting the values read from the slaves. Forcing will be terminated by calling the corresponding functions. This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **bOutputData** – [in] EC_TRUE: write output data, EC_FALSE: write input data
* **dwBitOffsetPd** – [in] Bit offset in Process data image
* **wDataBitLen** – [in] Buffer length [bit]
* **pbyData** – [in] Buffer containing transfered data
* **dwTimeout** – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.
* **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
### **emForceProcessDataBits() Example**
```cpp
/* force specific number of bits from given buffer to process image with a bit offset */
EC_T_BYTE abyData[1] = { 1 };
dwRes = emForceProcessDataBits(dwInstanceId, dwClientId,
EC_FALSE, 0 /* bit offset */, 1 /* bit length */, abyData, 5000 /* timeout */);
```
#### SEE ALSO
- [`emSetProcessData()`](api_process_data.html.md#_CPPv416emSetProcessData10EC_T_DWORD9EC_T_BOOL10EC_T_DWORDP9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD)
- [`emReleaseProcessDataBits()`](api_process_data.html.md#_CPPv424emReleaseProcessDataBits10EC_T_DWORD10EC_T_DWORD9EC_T_BOOL10EC_T_DWORD9EC_T_WORD10EC_T_DWORD)
- [`emReleaseAllProcessDataBits()`](api_process_data.html.md#_CPPv427emReleaseAllProcessDataBits10EC_T_DWORD10EC_T_DWORD10EC_T_DWORD)
## emReleaseProcessDataBits
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReleaseProcessDataBits([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wBitLength, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emReleaseProcessDataBits([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wBitLength, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Release previously forced process data.
* Forced output: Value set by application become valid again. Because forced process data bits are written directly into the process output image, the application has to update the process image with the required value, otherwise the forced value is still valid.
* Forced input: Value read from the slaves become valid again.
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **bOutputData** – [in] EC_TRUE: write output data, EC_FALSE: write input data
* **dwBitOffsetPd** – [in] Bit offset in Process data image
* **wBitLength** – [in] Number of bits that shall be written to the process image.
* **dwTimeout** – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.
* **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
### **emReleaseProcessDataBits() Example**
```cpp
/* release previously forced process data */
dwRes = emReleaseProcessDataBits(dwInstanceId, dwClientId,
EC_FALSE, 0 /* bit offset */, 1 /* bit length */, 5000 /* timeout */);
```
#### SEE ALSO
- [`emSetProcessData()`](api_process_data.html.md#_CPPv416emSetProcessData10EC_T_DWORD9EC_T_BOOL10EC_T_DWORDP9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD)
- [`emForceProcessDataBits()`](api_process_data.html.md#_CPPv422emForceProcessDataBits10EC_T_DWORD10EC_T_DWORD9EC_T_BOOL10EC_T_DWORD9EC_T_WORDP9EC_T_BYTE10EC_T_DWORD)
## emReleaseAllProcessDataBits
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReleaseAllProcessDataBits([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emReleaseAllProcessDataBits([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Release all previously forced process data for a dedicated client.
* Forced output: Value set by application become valid again. Because forced process data bits are written directly into the process output image, the application has to update the process image with the required value, otherwise the forced value is still valid.
* Forced input: Value read from the slaves become valid again.
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTimeout** – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.
* **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
### **emReleaseAllProcessDataBits() Example**
```cpp
/* release all previously forced process data of client */
dwRes = emReleaseAllProcessDataBits(dwInstanceId, dwClientId, 5000 /* timeout */);
```
#### SEE ALSO
- [`emSetProcessData()`](api_process_data.html.md#_CPPv416emSetProcessData10EC_T_DWORD9EC_T_BOOL10EC_T_DWORDP9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD)
- [`emForceProcessDataBits()`](api_process_data.html.md#_CPPv422emForceProcessDataBits10EC_T_DWORD10EC_T_DWORD9EC_T_BOOL10EC_T_DWORD9EC_T_WORDP9EC_T_BYTE10EC_T_DWORD)
## emGetProcessImageInputPtr
### static [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*ecatGetProcessImageInputPtr(EC_T_VOID)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*emGetProcessImageInputPtr([EC_T_DWORD](toc_api.html.md#_CPPv410EC_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
### **emGetProcessImageInputPtr() Example**
```cpp
EC_T_BYTE* pbyProcessImageInput = emGetProcessImageInputPtr(dwInstanceId);
```
#### SEE ALSO
- [`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)
- [emIoCtl - EC_IOCTL_GET_PDMEMORYSIZE](api_general_functions.html.md#emioctl-ec-ioctl-get-pdmemorysize)
- [emIoCtl - EC_IOCTL_REGISTER_PDMEMORYPROVIDER](api_general_functions.html.md#emioctl-ec-ioctl-register-pdmemoryprovider)
- [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) ( `eUsrJob_ProcessAllRxFrames`) in case of Polling Mode
## emGetProcessImageOutputPtr
### static [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*ecatGetProcessImageOutputPtr(EC_T_VOID)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*emGetProcessImageOutputPtr([EC_T_DWORD](toc_api.html.md#_CPPv410EC_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
### **emGetProcessImageOutputPtr() Example**
```cpp
EC_T_BYTE* pbyProcessImageOutput = emGetProcessImageOutputPtr(dwInstanceId);
```
#### SEE ALSO
- [`emConfigureNetwork()`](api_general_functions.html.md#_CPPv418emConfigureNetwork10EC_T_DWORD13EC_T_CNF_TYPE10EC_T_PBYTE10EC_T_DWORD)
- [emIoCtl - EC_IOCTL_GET_PDMEMORYSIZE](api_general_functions.html.md#emioctl-ec-ioctl-get-pdmemorysize)
- [emIoCtl - EC_IOCTL_REGISTER_PDMEMORYPROVIDER](api_general_functions.html.md#emioctl-ec-ioctl-register-pdmemoryprovider)
- [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) ( `eUsrJob_SendAllCycFrames`)
## emGetDiagnosisImagePtr
### static [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*ecatGetDiagnosisImagePtr(EC_T_VOID)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*emGetDiagnosisImagePtr([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Gets the diagnosis image pointer.
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **Returns:**
Diagnosis image pointer
### **emGetDiagnosisImagePtr() Example**
```cpp
EC_T_BYTE* pbyProcessImageOutput = emGetDiagnosisImagePtr(dwInstanceId);
```
## emGetDiagnosisImageSize
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetDiagnosisImageSize(EC_T_VOID)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetDiagnosisImageSize([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Gets the diagnosis image size.
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **Returns:**
Diagnosis image size
## emGetProcessVarInfoNumOf, emGetProcessVarInfoEx
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetProcessVarInfoNumOf([EC_T_VAR_DIRECTION](api_process_data.html.md#_CPPv418EC_T_VAR_DIRECTION) eVarDirection, [EC_T_VAR_SOURCE](api_process_data.html.md#_CPPv415EC_T_VAR_SOURCE) eVarSource, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwProcessVarInfoNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetProcessVarInfoNumOf([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_VAR_DIRECTION](api_process_data.html.md#_CPPv418EC_T_VAR_DIRECTION) eVarDirection, [EC_T_VAR_SOURCE](api_process_data.html.md#_CPPv415EC_T_VAR_SOURCE) eVarSource, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwProcessVarInfoNumOf)
Get process variables information.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **eVarDirection** – [in] INPUTs, OUTPUTs, … . See [EC_T_VAR_DIRECTION](api_process_data.html.md#d0-dd4-group-e-c-t-v-a-r-d-i-r-e-c-t-i-o-n) .
* **eVarSource** – [in] Slave, Master, … . See [EC_T_VAR_SOURCE](api_process_data.html.md#db-db7-group-e-c-t-v-a-r-s-o-u-r-c-e) .
* **bFixedAddress** – [in] Use station address if EC_TRUE. Otherwise use AutoInc address.
* **wSlaveAddress** – [in] Slave address according to bFixedAddress
* **pdwProcessVarInfoNumOf** – [out] Process variables count
* **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
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetProcessVarInfoEx([EC_T_VAR_DIRECTION](api_process_data.html.md#_CPPv418EC_T_VAR_DIRECTION) eVarDirection, [EC_T_VAR_SOURCE](api_process_data.html.md#_CPPv415EC_T_VAR_SOURCE) eVarSource, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*aoVarInfo, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxProcessVarInfoNumOf, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwProcessVarInfoNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetProcessVarInfoEx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_VAR_DIRECTION](api_process_data.html.md#_CPPv418EC_T_VAR_DIRECTION) eVarDirection, [EC_T_VAR_SOURCE](api_process_data.html.md#_CPPv415EC_T_VAR_SOURCE) eVarSource, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*aoVarInfoEx, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMaxVarInfoCnt, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwVarInfoCnt)
Get process variables information.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **eVarDirection** – [in] INPUTs, OUTPUTs, … . See [EC_T_VAR_DIRECTION](api_process_data.html.md#d0-dd4-group-e-c-t-v-a-r-d-i-r-e-c-t-i-o-n) .
* **eVarSource** – [in] Slave, Master, … . See [EC_T_VAR_SOURCE](api_process_data.html.md#db-db7-group-e-c-t-v-a-r-s-o-u-r-c-e) .
* **bFixedAddress** – [in] Use station address if EC_TRUE. Otherwise use AutoInc address.
* **wSlaveAddress** – [in] Slave address according to bFixedAddress
* **aoVarInfoEx** – [out] The read process variable extended information entries
* **dwMaxVarInfoCnt** – [in] Maximum number of variables that can be stored at aoVarInfoEx
* **pdwVarInfoCnt** – [out] Number process variable entries that have been stored in aoVarInfoEx
* **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
The following example demonstrates how to get all process data variables:
### **emGetProcessVarInfoEx() Example**
```cpp
EC_T_DWORD dwProcessVarInfoNumOf = 0;
dwRes = emGetProcessVarInfoNumOf(dwInstanceId, eVarDirection_All, eVarSource_All, EC_FALSE, 0, &dwProcessVarInfoNumOf);
/* ... */
EC_T_PROCESS_VAR_INFO_EX* aoVarInfoEx = (EC_T_PROCESS_VAR_INFO_EX*)OsMalloc(dwProcessVarInfoNumOf * sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emGetProcessVarInfoEx(dwInstanceId, eVarDirection_All, eVarSource_All, EC_FALSE, 0, aoVarInfoEx, dwProcessVarInfoNumOf, EC_NULL);
/* ... */
OsSafeFree(aoVarInfoEx);
```
**EC_T_VAR_DIRECTION**
### enum EC_T_VAR_DIRECTION
*Values:*
### enumerator eVarDirection_Undefined
Undefined Direction
### enumerator eVarDirection_INPUT
INPUTs
### enumerator eVarDirection_OUTPUT
OUTPUTs
### enumerator eVarDirection_All
INPUTs and OUTPUTs
### enumerator eVarDirection_BCppDummy
**EC_T_VAR_SOURCE**
### enum EC_T_VAR_SOURCE
*Values:*
### enumerator eVarSource_Undefined
Undefined Source
### enumerator eVarSource_All
Slaves and Master/Monitor/Simulator
### enumerator eVarSource_AllSlaves
All Slaves
### enumerator eVarSource_Slave
Slave
### enumerator eVarSource_Master
Master
### enumerator eVarSource_Monitor
Monitor
### enumerator eVarSource_Simulator
Simulator
### enumerator eVarSource_BCppDummy
## emGetSlaveInpVarInfoNumOf
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveInpVarInfoNumOf([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwSlaveInpVarInfoNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveInpVarInfoNumOf([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwSlaveInpVarInfoNumOf)
Gets the number of input variables of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **pwSlaveInpVarInfoNumOf** – [out] Number of found process variable entries
* **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 output pointer is EC_NULL
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
#### SEE ALSO
- [`emGetSlaveInpVarInfo()`](api_process_data.html.md#_CPPv420emGetSlaveInpVarInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP21EC_T_PROCESS_VAR_INFOP9EC_T_WORD)
- [`emGetSlaveInpVarInfoEx()`](api_process_data.html.md#_CPPv422emGetSlaveInpVarInfoEx10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP24EC_T_PROCESS_VAR_INFO_EXP9EC_T_WORD)
### **emGetSlaveInpVarInfoNumOf() Example**
```cpp
/* get number of input variables of specific slave */
EC_T_WORD numOfVars = 0;
dwRes = emGetSlaveInpVarInfoNumOf(dwInstanceId, EC_TRUE, 1004, &numOfVars);
```
## emGetSlaveInpVarInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveInpVarInfo([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pSlaveProcVarInfoEntries, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveInpVarInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pSlaveProcVarInfoEntries, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)
Gets the process variable information entries of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wNumOfVarsToRead** – [in] Number process variable entries that have been stored in pSlaveProcVarInfoEntries
* **pSlaveProcVarInfoEntries** – [out] The read process variable information entries
* **pwReadEntries** – [out] The number of read process variable information entries
* **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
### struct EC_T_PROCESS_VAR_INFO
### Public Members
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szName[MAX_PROCESS_VAR_NAME_LEN]
[out] Name of the found process variable
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDataType
[out] Data type of the found process variable (according to ETG.1000, section 5). See also EcType.h, DEFTYPE_BOOLEAN.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wFixedAddr
[out] Station address of the slave that is owner of this variable
### [EC_T_INT](toc_api.html.md#_CPPv48EC_T_INT) nBitSize
[out] Size in bits of the found process variable
### [EC_T_INT](toc_api.html.md#_CPPv48EC_T_INT) nBitOffs
[out] Bit offset in the process data image
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIsInputData
[out] Determines whether the found process variable is an input variable or an output variable
### MAX_PROCESS_VAR_NAME_LEN
Maximum length of a process variable name: 71 characters
### **emGetSlaveInpVarInfo() Example**
```cpp
/* get process variable information entries of specific slave */
EC_T_PROCESS_VAR_INFO aSlaveInpVarInfoNumOf[4];
EC_T_WORD wReadEntries = 0;
EC_T_WORD numOfVars = 0;
emGetSlaveInpVarInfoNumOf(dwInstanceId, EC_TRUE, 1004, &numOfVars);
dwRes = emGetSlaveInpVarInfo(dwInstanceId, EC_TRUE,
1001, numOfVars, aSlaveInpVarInfoNumOf, &wReadEntries);
```
## emGetSlaveInpVarInfoEx
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveInpVarInfoEx([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pSlaveProcVarInfoEntries, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveInpVarInfoEx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pSlaveProcVarInfoEntriesEx, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)
Gets the input process variable extended information entries of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wNumOfVarsToRead** – [in] Number process variable entries that have been stored in pSlaveProcVarInfoEntries
* **pSlaveProcVarInfoEntriesEx** – [out] The read process variable extended information entries
* **pwReadEntries** – [out] The number of read process variable information entries
* **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 output pointer is EC_NULL
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
### struct EC_T_PROCESS_VAR_INFO_EX
### Public Members
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szName[MAX_PROCESS_VAR_NAME_LEN_EX]
[out] Name of the found process variable
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDataType
[out] Data type of the found process variable (according to ETG.1000, section 5). See also EcType.h, DEFTYPE_BOOLEAN.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wFixedAddr
[out] Station address of the slave that is owner of this variable
### [EC_T_INT](toc_api.html.md#_CPPv48EC_T_INT) nBitSize
[out] Size in bits of the found process variable
### [EC_T_INT](toc_api.html.md#_CPPv48EC_T_INT) nBitOffs
[out] Bit offset in the process data image
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIsInputData
[out] Determines whether the found process variable is an input variable or an output variable
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex
[out] Object index
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex
[out] Object sub index
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPdoIndex
[out] Index of PDO (process data object)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffs
[out] Bit offset in the diagnostic image (API GetDiagnosisImagePtr)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMasterSyncUnit
[out] Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTaskId
[out] ID of task where process variable is located
### EC_T_CYC_COPY_INFO CopyInfo
[out] Copy Info if applied to the variable
### MAX_PROCESS_VAR_NAME_LEN_EX
Maximum length of an extended process variable name: 127 characters
### **emGetSlaveInpVarInfoEx() Example**
```cpp
EC_T_PROCESS_VAR_INFO_EX aSlaveInpVarInfoNumOf[4];
EC_T_WORD wReadEntries = 0;
EC_T_WORD wNumOfVarsToRead = 4;
emGetSlaveInpVarInfoNumOf(dwInstanceId, EC_TRUE, 1004, &wNumOfVarsToRead);
/* get extended process variable information entries of specific slave */
dwRes = emGetSlaveInpVarInfoEx(dwInstanceId, EC_TRUE, 1001,
wNumOfVarsToRead, aSlaveInpVarInfoNumOf, &wReadEntries);
```
## emGetSlaveOutpVarInfoNumOf
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveOutpVarInfoNumOf([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwSlaveOutpVarInfoNumOf)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveOutpVarInfoNumOf([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwSlaveOutpVarInfoNumOf)
Gets the number of output variables of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **pwSlaveOutpVarInfoNumOf** – [out] Number of found process variables
* **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
### **emGetSlaveOutpVarInfoNumOf() Example**
```cpp
/* get number of output variables of specific slave */
EC_T_WORD numOfVars = 0;
dwRes = emGetSlaveOutpVarInfoNumOf(dwInstanceId, EC_TRUE, 1002, &numOfVars);
```
#### SEE ALSO
- [`emGetSlaveOutpVarInfo()`](api_process_data.html.md#_CPPv421emGetSlaveOutpVarInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP21EC_T_PROCESS_VAR_INFOP9EC_T_WORD)
- [`emGetSlaveOutpVarInfoEx()`](api_process_data.html.md#_CPPv423emGetSlaveOutpVarInfoEx10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_WORDP24EC_T_PROCESS_VAR_INFO_EXP9EC_T_WORD)
## emGetSlaveOutpVarInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveOutpVarInfo([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pSlaveProcVarInfoEntries, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveOutpVarInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pSlaveProcVarInfoEntries, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)
Gets the output process variable information entries of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wNumOfVarsToRead** – [in] Number of found process variable entries
* **pSlaveProcVarInfoEntries** – [out] The read process variable information entries
* **pwReadEntries** – [out] The number of read process variable information entries
* **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
### **emGetSlaveOutpVarInfo() Example**
```cpp
/* get general output process variable information entries of specific slave */
EC_T_PROCESS_VAR_INFO aoSlaveOutpVarInfo[4]; /* see emGetSlaveOutpVarInfoNumOf() */
EC_T_WORD wSlaveOutpVarInfoCnt = 0;
dwRes = emGetSlaveOutpVarInfo(dwInstanceId, EC_TRUE, 1002,
4 /* see emGetSlaveOutpVarInfoNumOf() */, aoSlaveOutpVarInfo, &wSlaveOutpVarInfoCnt);
```
#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO`](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO)
## emGetSlaveOutpVarInfoEx
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveOutpVarInfoEx([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pSlaveProcVarInfoEntries, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveOutpVarInfoEx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumOfVarsToRead, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pSlaveProcVarInfoEntriesEx, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadEntries)
Gets the output process variable extended information entries of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wNumOfVarsToRead** – [in] Number of process variable information entries
* **pSlaveProcVarInfoEntriesEx** – [out] The read process extended variable entries
* **pwReadEntries** – [out] The number of read process variable information entries
* **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
### **emGetSlaveOutpVarInfoEx() Example**
```cpp
/* get extended output process variable information entries of specific slave */
EC_T_PROCESS_VAR_INFO_EX aoSlaveOutpVarInfo[4]; /* see emGetSlaveOutpVarInfoNumOf() */
EC_T_WORD wSlaveOutpVarInfoCnt = 0;
dwRes = emGetSlaveOutpVarInfoEx(dwInstanceId, EC_TRUE, 1002,
4 /* see emGetSlaveOutpVarInfoNumOf() */, aoSlaveOutpVarInfo, &wSlaveOutpVarInfoCnt);
```
#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)
## emGetSlaveInpVarByObjectEx
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveInpVarByObjectEx([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveInpVarByObjectEx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)
Gets the input process variable extended information entry by object index, subindex of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wIndex** – [in] Object index
* **wSubIndex** – [in] Object sub index
* **pProcessVarInfoEntry** – [out] Process variable extended information entry
* **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
### **emGetSlaveInpVarByObjectEx() Example**
```cpp
/* get input process variable extended information entry by object index,
subindex of specific slave */
EC_T_PROCESS_VAR_INFO_EX processVarInfoEntry;
OsMemset(&processVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emGetSlaveInpVarByObjectEx(dwInstanceId, EC_TRUE,
1004, 0x6000 /* Index */, 1 /* SubIndex */, &processVarInfoEntry);
```
#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)
## emGetSlaveOutpVarByObjectEx
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveOutpVarByObjectEx([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveOutpVarByObjectEx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)
Gets the input process variable extended information entry by object index, subindex of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wIndex** – [in] Object index
* **wSubIndex** – [in] Object sub index
* **pProcessVarInfoEntry** – [out] Process variable extended information entry
* **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
### **emGetSlaveOutpVarByObjectEx() Example**
```cpp
/* get output process variable extended information entry
by object index, subindex of specific slave. */
EC_T_PROCESS_VAR_INFO_EX oSlaveOutpVarInfo;
OsMemset(&oSlaveOutpVarInfo, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emGetSlaveOutpVarByObjectEx(dwInstanceId, EC_TRUE,
1002, 0x3001 /* Index */, 1 /* SubIndex */, &oSlaveOutpVarInfo);
```
#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)
## emFindInpVarByName
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFindInpVarByName(const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pProcessVarInfoEntry)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFindInpVarByName([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pProcessVarInfoEntry)
Finds an input process variable information entry by the variable name.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **szVariableName** – [in] Variable name
* **pProcessVarInfoEntry** – [out] Process variable information entry
* **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
### **emFindInpVarByName() Example**
```cpp
/* get general information about Process Data variable by name */
EC_T_PROCESS_VAR_INFO oProcessVarInfoEntry;
OsMemset(&oProcessVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO));
dwRes = emFindInpVarByName(dwInstanceId, "Slave_1004 [EL1014].Channel 1.Input", &oProcessVarInfoEntry);
```
#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO`](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO)
## emFindInpVarByNameEx
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFindInpVarByNameEx(const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFindInpVarByNameEx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)
Finds an input process variable extended information entry by the variable name.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **szVariableName** – [in] Variable name
* **pProcessVarInfoEntry** – [out] Process variable extended information entry
* **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
### **emFindInpVarByNameEx() Example**
```cpp
/* get extended information about Process Data variable by name */
EC_T_PROCESS_VAR_INFO_EX oProcessVarInfoEntry;
OsMemset(&oProcessVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emFindInpVarByNameEx(dwInstanceId, "Slave_1004 [EL1014].Channel 1.Input", &oProcessVarInfoEntry);
```
#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)
## emFindOutpVarByName
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFindOutpVarByName(const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pProcessVarInfoEntry)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFindOutpVarByName([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO) \*pProcessVarInfoEntry)
Finds an output process variable information entry by the variable name.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **szVariableName** – [in] Variable name
* **pProcessVarInfoEntry** – [out] Process variable information entry
* **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
### **emFindOutpVarByName() Example**
```cpp
/* get general information about Process Data variable by name */
EC_T_PROCESS_VAR_INFO oProcessVarInfoEntry;
OsMemset(&oProcessVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO));
dwRes = emFindOutpVarByName(dwInstanceId, "Slave_1002 [EL2004].Channel 1.Output", &oProcessVarInfoEntry);
```
#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO`](api_process_data.html.md#_CPPv421EC_T_PROCESS_VAR_INFO)
## emFindOutpVarByNameEx
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFindOutpVarByNameEx(const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFindOutpVarByNameEx([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcessVarInfoEntry)
Finds an output process variable extended information entry by the variable name.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **szVariableName** – [in] Variable name
* **pProcessVarInfoEntry** – [out] Process variable extended information entry
* **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
### **emFindOutpVarByName() Example**
```cpp
/* get extended information about Process Data variable by name */
EC_T_PROCESS_VAR_INFO_EX oProcessVarInfoEntry;
OsMemset(&oProcessVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emFindOutpVarByNameEx(dwInstanceId, "Slave_1002 [EL2004].Channel 1.Output", &oProcessVarInfoEntry);
```
#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)
## emLinkInputVarByName
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatLinkInputVarByName(const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVarName, [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pLinkVarInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emLinkInputVarByName([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVarName, [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pLinkVarInfo)
Link application variable to input process image. Input process variable is given by its name.
* **Parameters:**
* **dwInstanceID** – [in] Master instance ID
* **szVarName** – [in] Name of variable
* **pLinkVarInfo** – [in] Information about linked variable
* **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 an error code
### typedef EC_T_VOID (\*EC_PF_LINK_VAR_CONVERTER)(const [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pApplVarInfo, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyProcessImage)
* **Param pApplVarInfo:**
**[in]** Information about application variable
* **Param pbyProcessImage:**
**[in]** Pointer to input resp. output process image
### struct EC_T_LINK_VAR_INFO
### Public Members
### EC_T_VOID \*pvContext
[in] Arbitrarily application-defined parameter
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyApplVar
[in] Pointer to application variable where process variable should be linked to
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wApplVarType
[in] Type of application variable
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wApplVarBitSize
[in] Size of variable (in bits)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwApplVarBitOffs
[in] Bit offset of variable
### [EC_PF_LINK_VAR_CONVERTER](api_process_data.html.md#_CPPv424EC_PF_LINK_VAR_CONVERTER) pfnConverter
[in] Callback function to manipulate the input when reading from process image resp. the output when writing to process image (could be EC_NULL)
### [EC_T_PROCESS_VAR_INFO_EX](api_process_data.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX) \*pProcVarInfoEx
[out] Extended information about process variable
## emLinkInputVarByObject
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatLinkInputVarByObject([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pLinkVarInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emLinkInputVarByObject([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pLinkVarInfo)
Link application variable to input process image. Input process variable is given by its object index and subindex of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Master instance ID
* **bFixedAddressing** – [in] Use station address if EC_TRUE. Otherwise use AutoInc address.
* **wSlaveAddress** – [in] Slave address according to bFixedAddressing
* **wIndex** – [in] Object index
* **wSubIndex** – [in] Object subindex
* **pLinkVarInfo** – [in] Information about linked variable
* **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 an error code
#### SEE ALSO
[`EC_T_LINK_VAR_INFO`](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO)
## emLinkOutputVarByName
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatLinkOutputVarByName(const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVarName, [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pLinkVarInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emLinkOutputVarByName([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szVarName, [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pLinkVarInfo)
Link application variable to output process image. Output process variable is given by its name.
* **Parameters:**
* **dwInstanceID** – [in] Master instance ID
* **szVarName** – [in] Name of variable
* **pLinkVarInfo** – [in] Information about linked variable
* **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 an error code
#### SEE ALSO
[`EC_T_LINK_VAR_INFO`](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO)
## emLinkOutputVarByObject
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatLinkOutputVarByObject([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pLinkVarInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emLinkOutputVarByObject([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIndex, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSubIndex, [EC_T_LINK_VAR_INFO](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO) \*pLinkVarInfo)
Link application variable to output process image. Output process variable is given by its object index and subindex of a specific slave.
* **Parameters:**
* **dwInstanceID** – [in] Master instance ID
* **bFixedAddressing** – [in] Use station address if EC_TRUE. Otherwise use AutoInc address.
* **wSlaveAddress** – [in] Slave address according to bFixedAddressing
* **wIndex** – [in] Object index
* **wSubIndex** – [in] Object subindex
* **pLinkVarInfo** – [in] Information about linked variable
* **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 an error code
#### SEE ALSO
[`EC_T_LINK_VAR_INFO`](api_process_data.html.md#_CPPv418EC_T_LINK_VAR_INFO)
## emTraceDataConfig
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatTraceDataConfig([EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wTraceDataSize)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emTraceDataConfig([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wTraceDataSize)
Configures a trace data buffer and enables it for transmission.
Must be called after initialization and before configuration.
#### NOTE
If wTraceDataSize is too large, configuration will fail with return code [EC_E_XML_CYCCMDS_SIZEMISMATCH](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_1ga057e7cdfe426e792a7ab60830d2b3cf7).
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **wTraceDataSize** – [in] Size of Trace Data in bytes
* **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
* [EC_E_NOTSUPPORTED](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_1ga11f77305fb1d3868539a735298cc7864) if eCycFrameLayout_FIXED is configured
## emTraceDataGetInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatTraceDataGetInfo([EC_T_TRACE_DATA_INFO](api_process_data.html.md#_CPPv420EC_T_TRACE_DATA_INFO) \*pTraceDataInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emTraceDataGetInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_TRACE_DATA_INFO](api_process_data.html.md#_CPPv420EC_T_TRACE_DATA_INFO) \*pTraceDataInfo)
Get information about the offset and size of trace data.
The trace data buffer is located in [EC_T_TRACE_DATA_INFO.pbyData](api_process_data.html.md#d4/db8/struct_e_c___t___t_r_a_c_e___d_a_t_a___i_n_f_o_1a2dbd8469527c6dfce9bf5a1bc0a31a80) at the byte offset [EC_T_TRACE_DATA_INFO.dwOffset](api_process_data.html.md#d4/db8/struct_e_c___t___t_r_a_c_e___d_a_t_a___i_n_f_o_1af8a02bf1934081b8744d39664711e939).
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **pTraceDataInfo** – [out] Information about trace data
* **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
### struct EC_T_TRACE_DATA_INFO
### Public Members
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData
[out] Process data output buffer, containing trace data
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwOffset
[out] Trace data offset in bytes
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSize
[out] Trace data size in bytes
### **emTraceDataGetInfo() Example**
```cpp
/* get trace data offset and size */
EC_T_TRACE_DATA_INFO traceDataInfo;
OsMemset(&traceDataInfo, 0, sizeof(EC_T_TRACE_DATA_INFO));
dwRes = emTraceDataGetInfo(dwInstanceId, &traceDataInfo);
```
## 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
```cpp
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 */
```
## 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
```cpp
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 */
```
## 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
```cpp
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 */
```
## 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
```cpp
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 ... */
```
## 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
```cpp
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 ... */
```
## 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
```cpp
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 ... */
```
## 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
#### SEE ALSO
- [`EC_SETBITS`](api_process_data.html.md#c.EC_SETBITS)
- [`EC_GETBITS`](api_process_data.html.md#c.EC_GETBITS)
```cpp
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 0x3D 0xAD 0x00 */
```
## EC_COMPAREBITS
### EC_COMPAREBITS(pbyBuf1, nBitOffs1, pbyBuf2, nBitOffs2, nBitSize)
Compares a block of bits of two buffers.
#### NOTE
The buffers are compared bitwise with the same semantic as memcmp(). The buffers are not checked for overrun.
* **Parameters:**
* **pbyBuf1** – [in] Buffer 1
* **nBitOffs1** – [in] Bit offset within buffer 1
* **pbyBuf2** – [in] Buffer 2
* **nBitOffs2** – [in] Bit offset within buffer 2
* **nBitSize** – [in] Bit size to compare
* **Returns:**
Integral value indicating the relationship between the content of the memory blocks:
* 0: The blocks of bits within the two buffers are equal
* <0: Binary value from block of bits in buffer 1 has a lower value than binary value from block of bits in buffer 2
* >0: Binary value from block of bits in buffer 1 has a greater value than binary value from block of bits in buffer 2
#### SEE ALSO
- [`EC_COPYBITS`](api_process_data.html.md#c.EC_COPYBITS)
```cpp
EC_T_BYTE pbyBuf1[] = {0xB8, 0x3D, 0xAD, 0x00};
EC_T_BYTE pbyBuf2[] = {0xF4, 0xED, 0x69, 0xA5};
assert(0 == EC_COMPAREBITS(pbyBuf1, 3, pbyBuf2, 6, 22));
```
## 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 only be 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
#### SEE ALSO
- [`EC_GET_FRM_WORD`](api_process_data.html.md#c.EC_GET_FRM_WORD)
- [`EC_GET_FRM_DWORD`](api_process_data.html.md#c.EC_GET_FRM_DWORD)
- [`EC_GET_FRM_QWORD`](api_process_data.html.md#c.EC_GET_FRM_QWORD)
## 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 only be 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
#### SEE ALSO
- [`EC_SET_FRM_WORD`](api_process_data.html.md#c.EC_SET_FRM_WORD)
- [`EC_SET_FRM_DWORD`](api_process_data.html.md#c.EC_SET_FRM_DWORD)
- [`EC_SET_FRM_QWORD`](api_process_data.html.md#c.EC_SET_FRM_QWORD)
## EC_COPYBIT
### EC_COPYBIT(pbyBuf, nBitOffs, bVal)
Copy a boolean bit value into the buffer.
* **Parameters:**
* **pbyBuf** – Destination buffer.
* **nBitOffs** – Bit offset to write.
* **bVal** – Boolean bit value.
## EC_TESTBIT
### EC_TESTBIT(pbyBuf, nBitOffs)
Test whether a bit in the buffer is set.
* **Parameters:**
* **pbyBuf** – Source buffer.
* **nBitOffs** – Bit offset to test.
* **Returns:**
EC_TRUE if bit is set, otherwise EC_FALSE.
## EC_SETBIT
### EC_SETBIT(pbyBuf, nBitOffs)
Set a single bit in the buffer.
* **Parameters:**
* **pbyBuf** – Destination buffer.
* **nBitOffs** – Bit offset to set.
## EC_CLRBIT
### EC_CLRBIT(pbyBuf, nBitOffs)
Clear a single bit in the buffer.
* **Parameters:**
* **pbyBuf** – Destination buffer.
* **nBitOffs** – Bit offset to clear.
# api_return_status.html.md
# Generic API return status values
Most of the functions and also some notifications will return an error status value to indicate whether a function was successfully executed or not. Some of the return status values have a generic meaning unspecific to the called API function.
| [`EC_E_NOERROR`](error-codes_generic.html.md#c.EC_E_NOERROR) | The function was successfully executed |
|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| [`EC_E_NOTSUPPORTED`](error-codes_generic.html.md#c.EC_E_NOTSUPPORTED) | Unsupported feature or functionality |
| [`EC_E_BUSY`](error-codes_generic.html.md#c.EC_E_BUSY) | The MainDevice is currently busy and the function has to be re-tried at a later time |
| [`EC_E_NOMEMORY`](error-codes_generic.html.md#c.EC_E_NOMEMORY) | Not enough memory or frame buffer resources available |
| [`EC_E_INVALIDPARM`](error-codes_generic.html.md#c.EC_E_INVALIDPARM) | Invalid or inconsistent parameters |
| [`EC_E_TIMEOUT`](error-codes_generic.html.md#c.EC_E_TIMEOUT) | Timeout error |
| [`EC_E_SLAVE_ERROR`](error-codes_generic.html.md#c.EC_E_SLAVE_ERROR) | A SubDevice error was detected |
#### SEE ALSO
- [emNotify - EC_NOTIFY_STATUS_SLAVE_ERROR](api_diagnosis.html.md#emnotify-ec-notify-status-slave-error)
- [emNotify - EC_NOTIFY_SLAVE_ERROR_STATUS_INFO](api_diagnosis.html.md#emnotify-ec-notify-slave-error-status-info)
| [`EC_E_INVALID_SLAVE_STATE`](error-codes_generic.html.md#c.EC_E_INVALID_SLAVE_STATE) | The SubDevice is not in the requested state to execute the operation (e.g. when initiating a mailbox transfer the SubDevice must be at least in PREOP state) |
|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`EC_E_SLAVE_NOT_ADDRESSABLE`](error-codes_generic.html.md#c.EC_E_SLAVE_NOT_ADDRESSABLE) | The SubDevice does not respond to its station address (e.g. when requesting its AL_STATUS value). The SubDevice may be removed from the bus or powered-off. |
| [`EC_E_LINK_DISCONNECTED`](error-codes_generic.html.md#c.EC_E_LINK_DISCONNECTED) | Link cable not connected |
| [`EC_E_MASTERCORE_INACCESSIBLE`](error-codes_generic.html.md#c.EC_E_MASTERCORE_INACCESSIBLE) | MainDevice core inaccessible. This result code usually means a remote connected server / EtherCAT® MainDevice does not respond anymore. |
The [`EC_E_BUSY`](error-codes_generic.html.md#c.EC_E_BUSY) return status value indicates that a previously requested operation is still in progress. For example if the MainDevice is requested to enter the OPERATIONAL state the next request from the API will return this status value unless the OPERATIONAL state is entered.
# api_slave_control.html.md
# SubDevice control and status functions
## emGetNumConfiguredSlaves
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetNumConfiguredSlaves(EC_T_VOID)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetNumConfiguredSlaves([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Returns the number of slaves which are configured in the ENI.
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **Returns:**
Number of slaves
### **emGetNumConfiguredSlaves() Example**
```cpp
EC_T_DWORD dwSlaveCnt = emGetNumConfiguredSlaves(dwInstanceId);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
" Slave Count: %d", dwSlaveCnt));
```
## emGetNumConnectedSlaves
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetNumConnectedSlaves(EC_T_VOID)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetNumConnectedSlaves([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID)
Get number of currently connected slaves.
* **Parameters:**
**dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **Returns:**
Number of connected slaves
### **emGetNumConnectedSlaves() Example**
```cpp
EC_T_DWORD dwSlaveCnt = emGetNumConnectedSlaves(dwInstanceId);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
" Slave Count: %d", dwSlaveCnt));
```
## emGetSlaveId
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveId([EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveId([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress)
Determines the slave ID using the slave station address.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **wStationAddress** – [in] Station address of the slave
* **Returns:**
Slave ID or INVALID_SLAVE_ID if the slave could not be found or the stack is not initialized
### **emGetSlaveId() Example**
```cpp
/* get slave ID using slave station address */
EC_T_WORD wStationAddress = 1002;
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, wStationAddress);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
" Slave ID: %d", dwSlaveId));
```
## emGetSlaveIdAtPosition
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveIdAtPosition([EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAutoIncAddress)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveIdAtPosition([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAutoIncAddress)
Determines the slave ID using the slave auto increment address.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **wAutoIncAddress** – [in] Auto increment address of the slave
* **Returns:**
Slave ID or INVALID_SLAVE_ID if no slave matching wAutoIncAddress can be found
### **emGetSlaveIdAtPosition() Example**
```cpp
/* get slave ID using configured auto increment address */
EC_T_WORD wAutoIncAdress = 0xFFFB;
EC_T_DWORD dwSlavePos = emGetSlaveIdAtPosition(dwInstanceId, wAutoIncAdress);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO,
" Slave Position: %d", dwSlavePos));
```
## emSetSlaveState
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetSlaveState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDeviceState, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetSlaveState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDeviceState, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Set a specified slave into the requested EtherCAT state.
The requested state shall not be higher than the overall operational state. DEVICE_STATE_BOOTSTRAP can only be requested if the slave’s state is INIT. This function may not be called from within the JobTask’s context.
If the function is called with EC_NOWAIT, the client may wait for reaching the requested state using the notification callback (EC_NOTIFY_SLAVE_STATECHANGED).
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **wDeviceState** – [in] Requested device state. See [Slave device state’s](api_slave_control.html.md#dd-dc3-group-d-e-v-i-c-e-s-t-a-t-e-s)
* **dwTimeout** – [in] Timeout [ms]. This function will block until the requested state is reached or the timeout elapsed. If the timeout value is set to EC_NOWAIT the function will return immediately.
* **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 or denies the requested state, see comments below
* [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 BOOTSTRAP was requested for a slave that does not support it
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
* [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 the EtherCAT stack cannot execute the request at this time, the function has to be called at a later time
* [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 requesting the slave’s state (slave may not be connected or did not respond)
* [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
### DEVICE_STATE_UNKNOWN
Slave in unknown state
### DEVICE_STATE_INIT
Slave in INIT state
### DEVICE_STATE_PREOP
Slave in PREOP state
### DEVICE_STATE_BOOTSTRAP
Slave in BOOTSTRAP state
### DEVICE_STATE_SAFEOP
Slave in SAFEOP state
### DEVICE_STATE_OP
Slave in OP state
### DEVICE_STATE_ERROR
Slave in error state
### **emSetSlaveState() Example**
```cpp
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
EC_T_WORD wDeviceState = DEVICE_STATE_PREOP;
dwRes = emSetSlaveState(dwInstanceId, dwSlaveId, wDeviceState, 5000 /* timeout */);
```
#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emSetSlaveStateReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetSlaveStateReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDeviceState, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetSlaveStateReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDeviceState, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Request to set a specified slave into the requested EtherCAT state and return immediately.
The requested state shall not be higher than the overall operational state. DEVICE_STATE_BOOTSTRAP can only be requested if the slave’s state is INIT.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **wDeviceState** – [in] Requested device state. See [Slave device state’s](api_slave_control.html.md#dd-dc3-group-d-e-v-i-c-e-s-t-a-t-e-s)
* **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 or denies the requested state, see comments below
* [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 BOOTSTRAP was requested for a slave that does not support it
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
* [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 EtherCAT stack cannot execute the request at this time, the function has to be called at a later time
* [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
### **emSetSlaveStateReq() Example**
```cpp
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
EC_T_WORD wDeviceState = DEVICE_STATE_PREOP;
dwRes = emSetSlaveStateReq(dwInstanceId, dwSlaveId, wDeviceState, 5000 /* timeout */);
```
#### SEE ALSO
[`emSetSlaveState()`](api_slave_control.html.md#_CPPv415emSetSlaveState10EC_T_DWORD10EC_T_DWORD9EC_T_WORD10EC_T_DWORD)
#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emGetSlaveState
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlaveState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwCurrDevState, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReqDevState)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlaveState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwCurrDevState, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReqDevState)
Get the slave state.
The slave state is always read automatically from the AL_STATUS register whenever necessary. It is not forced by calling this function. This function may be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **pwCurrDevState** – [out] Current slave state
* **pwReqDevState** – [out] Requested slave state
* **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 output pointers are EC_NULL
* [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if the slave is not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
### **emGetSlaveState() Example**
```cpp
/* get slave state */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_WORD pwCurrDevState = 0;
EC_T_WORD wReqDevState = 0;
dwRes = emGetSlaveState(dwInstanceId, dwSlaveId, &pwCurrDevState, &wReqDevState);
```
#### SEE ALSO
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
- [`emSetSlaveState()`](api_slave_control.html.md#_CPPv415emSetSlaveState10EC_T_DWORD10EC_T_DWORD9EC_T_WORD10EC_T_DWORD)
## emIsSlavePresent
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatIsSlavePresent([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*pbPresence)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emIsSlavePresent([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*pbPresence)
Returns whether a specific slave is currently connected to the Bus.
This function may be called from within the JobTask.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **pbPresence** – [out] EC_TRUE if the slave is currently connected to the bus, EC_FALSE if not
* **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
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
### **emIsSlavePresent() Example**
```cpp
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_BOOL bPresence = EC_FALSE;
/* returns whether a specific slave is currently connected to network */
dwRes = emIsSlavePresent(dwInstanceId, dwSlaveId, &bPresence);
```
#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emGetSlaveProp
### static [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) ecatGetSlaveProp([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) \*pSlaveProp)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) emGetSlaveProp([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) \*pSlaveProp)
Determines the properties of the slave device.
### *Deprecated:*
Use emGetCfgSlaveInfo instead
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **pSlaveProp** – [out] Slave properties
* **Returns:**
EC_TRUE if the slave exists, EC_FALSE if no slave matching dwSlaveId can be found
### **emGetSlaveProp() Example**
```cpp
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1002);
EC_T_SLAVE_PROP oSlaveProp;
OsMemset(&oSlaveProp, 0, sizeof(EC_T_SLAVE_PROP));
EC_T_BOOL bSlaveProp = emGetSlaveProp(dwInstanceId, dwSlaveId, &oSlaveProp);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO, " Slave ID: %d", bSlaveProp));
```
#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emSlaveSerializeMbxTfers
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSlaveSerializeMbxTfers([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSlaveSerializeMbxTfers([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId)
Serializes all mailbox transfers to the specified slave.
The parallel (overlapped) usage of more than one protocol (CoE, EoE, FoE, etc.) will be disabled. By default parallel mailbox transfers are enabled.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **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
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
* [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave does not support mailbox transfers
### **emSlaveSerializeMbxTfers() Example**
```cpp
/* serialize all mailbox transfers to specified slave */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
dwRes = emSlaveSerializeMbxTfers(dwInstanceId, dwSlaveId);
```
#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emSlaveParallelMbxTfers
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSlaveParallelMbxTfers([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSlaveParallelMbxTfers([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId)
Re-enable the parallel mailbox transfers to the specified slave.
Allows parallel (overlapped) usage of more than one protocol (CoE, EoE, FoE, etc.). By default parallel mailbox transfers are enabled.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **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
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
* [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave does not support mailbox transfers
### **emSlaveParallelMbxTfers() Example**
```cpp
/* re-enable parallel mailbox transfers to specified slave */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
dwRes = emSlaveParallelMbxTfers(dwInstanceId, dwSlaveId);
```
#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emIoCtl - EC_IOCTL_SET_MBX_RETRYACCESS_PERIOD
### EC_IOCTL_SET_MBX_RETRYACCESS_PERIOD
Sets the mailbox retry access period [ms] for a specific slave. If a slave rejects a mailbox access because of a busy state, the master restarts mailbox access after that period of time.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to a size 6 byte array. The first 4 bytes must contain the slave id (EC_T_DWORD), the last 2 bytes the new retry access period in milliseconds(EC_T_WORD).
* **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
* **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
By default, the retry access period is set to 25 milliseconds.
## emNotify - EC_NOTIFY_SLAVE_STATECHANGED
This notification is given when a SubDevice changed its EtherCAT® state. This notification is disabled by default.
**emNotify - EC_NOTIFY_SLAVE_STATECHANGED**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SLAVE_STATECHANGED_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_SLAVE_STATECHANGED_NTFY_DESC
### Public Members
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) newState
New slave state
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the activation
## emNotify - EC_NOTIFY_SLAVES_STATECHANGED
Collects [emNotify - EC_NOTIFY_SLAVE_STATECHANGED](api_slave_control.html.md#emnotify-ec-notify-slave-statechanged).
This notification is disabled by default.
#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled) for how to control the activation
**emNotify - EC_NOTIFY_SLAVES_STATECHANGED**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SLAVES_STATECHANGED_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_SLAVES_STATECHANGED_NTFY_DESC_ENTRY
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress
Slave station address
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byState
New slave state
## emWriteSlaveRegister
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatWriteSlaveRegister([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [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) emWriteSlaveRegister([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [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)
Writes data into the ESC memory of a specified slave.
This function may not be called from within the JobTask’s context
#### WARNING
Changing contents of ESC registers may lead to unpredictable behavior of the slaves and/or the master.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wRegisterOffset** – [in] Register offset. E.g. use 0x0120 to write to the AL Control register.
* **pbyData** – [in] Buffer containing transfered data
* **wLen** – [in] Number of bytes to send
* **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_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
* [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.
### **emWriteSlaveRegister() Example**
```cpp
dwRes = emWriteSlaveRegister(dwInstanceId, EC_TRUE,
1001, wRegisterOffset, abyData, wLen, 5000 /* timeout */);
```
## emWriteSlaveRegisterReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatWriteSlaveRegisterReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [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) emWriteSlaveRegisterReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen)
Requests a data write transfer into the ESC memory of a specified slave and returns immediately.
A notification EC_NOTIFY_SLAVE_REGISTER_TRANSFER is given on completion. This function may be called from within the JobTask’s context.
#### WARNING
Changing contents of ESC registers may lead to unpredictable behavior of the slaves and/or the master.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC](api_slave_control.html.md#df/ddd/struct_e_c___t___s_l_a_v_e_r_e_g_i_s_t_e_r___t_r_a_n_s_f_e_r___n_t_f_y___d_e_s_c).
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wRegisterOffset** – [in] Register offset. E.g. use 0x0120 to write to the AL Control register.
* **pbyData** – [in] Buffer containing transferred data
* **wLen** – [in] Number of bytes to send
* **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_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
* [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.
### **emWriteSlaveRegisterReq() Example**
```cpp
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
/* assigned by application. should be unique for each transfer */
/* write data into slave's ESC memory */
dwRes = emWriteSlaveRegisterReq(dwInstanceId, dwClientId, dwTferId,
EC_TRUE, 1001, wRegisterOffset, abyData, wLen);
```
#### SEE ALSO
[emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER](api_slave_control.html.md#emnotify-ec-notify-slave-register-transfer)
## emReadSlaveRegister
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReadSlaveRegister([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [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) emReadSlaveRegister([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [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)
Reads data from the ESC memory of a specified slave.
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wRegisterOffset** – [in] Register offset. I.e. use 0x0130 to read the AL Status register.
* **pbyData** – [out] Buffer receiving transfered data
* **wLen** – [in] Number of bytes to receive
* **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_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if the slave is not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
* [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.
### **emReadSlaveRegister() Example**
```cpp
/* read ESC memory */
EC_T_BYTE abyData[2] = {0, 0};
dwRes = emReadSlaveRegister(dwInstanceId, EC_TRUE, 1001,
0 /* ADO */, abyData, 2, 5000 /* timeout */);
```
## emReadSlaveRegisterReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReadSlaveRegisterReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [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) emReadSlaveRegisterReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen)
Requests data read transfer from the ESC memory of a specified slave and returns immediately.
A notification EC_NOTIFY_SLAVE_REGISTER_TRANSFER is given on completion. This function may be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_SLAVEREGISTER_TRANSFER_NTFY_DESC](api_slave_control.html.md#df/ddd/struct_e_c___t___s_l_a_v_e_r_e_g_i_s_t_e_r___t_r_a_n_s_f_e_r___n_t_f_y___d_e_s_c).
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wRegisterOffset** – [in] Register offset, e.g. use 0x0130 to read the AL Status register
* **pbyData** – [out] Buffer receiving transfered data
* **wLen** – [in] Number of bytes to receive
* **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_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
* [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.
### **emReadSlaveRegisterReq() Example**
```cpp
/* read ESC memory (non-blocking) */
EC_T_BYTE abyData[2] = {0, 0};
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
/* get data read transfer from ESC memory of specified slave */
dwRes = emReadSlaveRegisterReq(dwInstanceId, dwClientId, dwTferId,
EC_TRUE, 1001, 0 /* ADO */, abyData, 2);
```
#### SEE ALSO
[emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER](api_slave_control.html.md#emnotify-ec-notify-slave-register-transfer)
## emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER
This notification is given, when a SubDevice register transfer is completed.
**emNotify - EC_NOTIFY_SLAVE_REGISTER_TRANSFER**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SLAVEREGISTER_TRANSFER_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_SLAVEREGISTER_TRANSFER_NTFY_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId
Transfer ID. For every new slave register transfer a unique ID has to be assigned. This ID can be used after completion to identify the transfer.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwResult
Result of Slave register transfer
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bRead
EC_TRUE: Read register, EC_FALSE: Write register transfer
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wFixedAddr
Station address of slave
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRegisterOffset
Register offset
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLen
Length of slave register transfer
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData
Pointer to the data read
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkc
Received working counter
## emReadSlaveEEPRom
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReadSlaveEEPRom([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReadLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOutData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emReadSlaveEEPRom([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReadLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOutData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Read EEPROM data from a slave.
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wEEPRomStartOffset** – [in] Word address to start EEPROM read from
* **pwReadData** – [in] Pointer to EC_T_WORD array to carry the read data
* **dwReadLen** – [in] Size of the EC_T_WORD array provided at pwReadData (in EC_T_WORDs)
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD carrying actually read data (in EC_T_WORDs) after completion
* **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.
* **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
### **emReadSlaveEEPRom() Example**
```cpp
/* read EEPROM data from slave */
EC_T_WORD awData[16];
EC_T_DWORD dwNumOutData = 0;
OsMemset(awData, 0, sizeof(awData));
dwRes = emReadSlaveEEPRom(dwInstanceId, EC_TRUE, 1001,
7 /* WORD offset */, awData, EC_NUMOFELEMENTS(awData),
&dwNumOutData, 5000 /* timeout */);
```
## emReadSlaveEEPRomReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReadSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReadLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOutData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emReadSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwReadData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReadLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOutData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Requests an EEPROM data read operation from a slave and returns immediately.
An EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_EEPROM_OPERATION_NTFY_DESC](api_slave_control.html.md#d9/dc3/struct_e_c___t___e_e_p_r_o_m___o_p_e_r_a_t_i_o_n___n_t_f_y___d_e_s_c).
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wEEPRomStartOffset** – [in] Word address to start EEPROM read from
* **pwReadData** – [out] Pointer to EC_T_WORD array to carry the read data, must be valid until the operation complete
* **dwReadLen** – [in] Size of the EC_T_WORD array provided at pwReadData (in EC_T_WORDs)
* **pdwNumOutData** – [out] Pointer to EC_T_DWORD carrying actually read data (in EC_T_WORDs) after completion
* **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
### **emReadSlaveEEPRomReq() Example**
```cpp
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
EC_T_WORD awData[16];
EC_T_DWORD dwNumOutData = 0;
OsMemset(awData, 0, sizeof(awData));
/* requests EEPROM data read operation from slave */
dwRes = emReadSlaveEEPRomReq(dwInstanceId, dwClientId,
dwTferId, EC_TRUE, 1001, 7 /* WORD offset */, awData,
EC_NUMOFELEMENTS(awData), &dwNumOutData, 5000 /* timeout */);
```
#### SEE ALSO
[emNotify - EC_NOTIFY_EEPROM_OPERATION](api_slave_control.html.md#emnotify-ec-notify-eeprom-operation)
## emWriteSlaveEEPRom
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatWriteSlaveEEPRom([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset, const [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwWriteData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwWriteLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emWriteSlaveEEPRom([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset, const [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwWriteData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwWriteLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Write EEPROM data to slave.
The EEPROM’s CRC is updated automatically. [emResetSlaveController()](api_slave_control.html.md#db/d74/_ec_master_api_8cpp_1a7d0eae738aaf6a8b130fb013543520f1) is needed to reload the alias address in register 0x12.
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wEEPRomStartOffset** – [in] Word address to start EEPROM Write from
* **pwWriteData** – [in] Pointer to WORD array carrying the data to write
* **dwWriteLen** – [in] Size of Write Data WORD array (in WORDS)
* **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.
* **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
### **emWriteSlaveEEPRom() Example**
```cpp
dwRes = emWriteSlaveEEPRom(dwInstanceId, EC_TRUE,
1001, 0 /* offset */, awData, dwWriteLen, 5000 /* timeout */);
```
#### SEE ALSO
[`emResetSlaveController()`](api_slave_control.html.md#_CPPv422emResetSlaveController10EC_T_DWORD9EC_T_BOOL9EC_T_WORD10EC_T_DWORD)
## emWriteSlaveEEPRomReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatWriteSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset, const [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwWriteData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwWriteLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emWriteSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset, const [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwWriteData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwWriteLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Requests an EEPROM data write operation from a slave and returns immediately.
The EEPROM’s CRC is updated automatically. A reset of the slave controller is needed to reload the alias address in register 0x12. An EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_EEPROM_OPERATION_NTFY_DESC](api_slave_control.html.md#d9/dc3/struct_e_c___t___e_e_p_r_o_m___o_p_e_r_a_t_i_o_n___n_t_f_y___d_e_s_c).
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wEEPRomStartOffset** – [in] Word address to start EEPROM Write from
* **pwWriteData** – [in] Pointer to WORD array carrying the write data, must be valid until operation complete
* **dwWriteLen** – [in] Size of Write Data WORD array (in WORDS)
* **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
### **emWriteSlaveEEPRomReq() Example**
```cpp
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
dwRes = emWriteSlaveEEPRomReq(dwInstanceId, dwClientId, dwTferId,
EC_TRUE, 1001, 0 /* offset */, awData, dwWriteLen, 5000 /* timeout */);
```
#### SEE ALSO
- [`emResetSlaveController()`](api_slave_control.html.md#_CPPv422emResetSlaveController10EC_T_DWORD9EC_T_BOOL9EC_T_WORD10EC_T_DWORD)
- [emNotify - EC_NOTIFY_EEPROM_OPERATION](api_slave_control.html.md#emnotify-ec-notify-eeprom-operation)
## emAssignSlaveEEPRom
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatAssignSlaveEEPRom([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSlavePDIAccessEnable, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bForceAssign, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emAssignSlaveEEPRom([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSlavePDIAccessEnable, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bForceAssign, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Set EEPROM Assignment to PDI or EtherCAT Master.
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **bSlavePDIAccessEnable** – [in] EC_TRUE: EEPROM assigned to slave PDI application, EC_FALSE: EEPROM assigned to EC-Master
* **bForceAssign** – [in] Force Assignment of EEPROM (only for ECat Master Assignment)
* **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.
* **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
### **emAssignSlaveEEPRom() Example**
```cpp
/* set EEPROM access to PDI */
dwRes = emAssignSlaveEEPRom(dwInstanceId, EC_TRUE,
1001, EC_TRUE /* PDI access */, EC_TRUE /* force */, 5000 /* timeout */);
```
## emAssignSlaveEEPRomReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatAssignSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSlavePDIAccessEnable, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bForceAssign, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emAssignSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSlavePDIAccessEnable, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bForceAssign, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Requests EEPROM Assignment to PDI or EtherCAT Master operation and returns immediately.
EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_EEPROM_OPERATION_NTFY_DESC](api_slave_control.html.md#d9/dc3/struct_e_c___t___e_e_p_r_o_m___o_p_e_r_a_t_i_o_n___n_t_f_y___d_e_s_c).
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **bSlavePDIAccessEnable** – [in] EC_TRUE: EEPROM assigned to slave PDI application, EC_FALSE: EEPROM assigned to EC-Master
* **bForceAssign** – [in] Force Assignment of EEPROM (only for ECat Master Assignment)
* **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
### **emAssignSlaveEEPRomReq() Example**
```cpp
/* set EEPROM access to PDI (non-blocking) */
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
/* requests EEPROM Assignment to PDI or EtherCAT Master operation and return immediately */
dwRes = emAssignSlaveEEPRomReq(dwInstanceId, dwClientId, dwTferId,
EC_TRUE, 1001, EC_TRUE /* PDI access */, EC_TRUE /* force */, 5000 /* timeout */);
```
#### SEE ALSO
[emNotify - EC_NOTIFY_EEPROM_OPERATION](api_slave_control.html.md#emnotify-ec-notify-eeprom-operation)
## emActiveSlaveEEPRom
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatActiveSlaveEEPRom([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*pbSlavePDIAccessActive, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emActiveSlaveEEPRom([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*pbSlavePDIAccessActive, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Check whether EEPROM is marked access active by Slave PDI application.
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **pbSlavePDIAccessActive** – [out] Pointer to Boolean value: EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active
* **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.
* **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
### **emActiveSlaveEEPRom() Example**
```cpp
/* check whether EEPROM is marked access active by PDI */
EC_T_BOOL bSlavePDIAccessActive = EC_FALSE;
dwRes = emActiveSlaveEEPRom(dwInstanceId, EC_TRUE, 1001,
&bSlavePDIAccessActive, 5000 /* timeout */);
```
## emActiveSlaveEEPRomReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatActiveSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*pbSlavePDIAccessActive, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emActiveSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) \*pbSlavePDIAccessActive, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Requests EEPROM is marked access active by Slave PDI application check and returns immediately.
An EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_EEPROM_OPERATION_NTFY_DESC](api_slave_control.html.md#d9/dc3/struct_e_c___t___e_e_p_r_o_m___o_p_e_r_a_t_i_o_n___n_t_f_y___d_e_s_c).
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **pbSlavePDIAccessActive** – [out] Pointer to Boolean value: EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active. Must be valid until operation complete.
* **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.
* **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
### **emActiveSlaveEEPRomReq() Example**
```cpp
/* check whether EEPROM is marked access active by PDI (non-blocking) */
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
EC_T_BOOL bSlavePDIAccessActive = EC_FALSE;
dwRes = emActiveSlaveEEPRomReq(dwInstanceId, dwClientId, dwTferId,
EC_TRUE, 1001, &bSlavePDIAccessActive, 5000 /* timeout */);
```
#### SEE ALSO
[emNotify - EC_NOTIFY_EEPROM_OPERATION](api_slave_control.html.md#emnotify-ec-notify-eeprom-operation)
## emReloadSlaveEEPRom
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReloadSlaveEEPRom([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emReloadSlaveEEPRom([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Causes a slave to reload its EEPROM values to ESC registers.
Alias address at 0x12 is not reloaded through this command, this is prevented by the slave hardware. The slave controller must be reset to reload the alias address. This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.
* **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
### **emReloadSlaveEEPRom() Example**
```cpp
dwRes = emReloadSlaveEEPRom(dwInstanceId, EC_TRUE, 1001, 5000/* timeout */);
```
#### SEE ALSO
[`emResetSlaveController()`](api_slave_control.html.md#_CPPv422emResetSlaveController10EC_T_DWORD9EC_T_BOOL9EC_T_WORD10EC_T_DWORD)
## emReloadSlaveEEPRomReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReloadSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emReloadSlaveEEPRomReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Request a slave to reload its EEPROM values to ESC registers, and returns immediately.
Alias address at 0x12 is not reloaded through this command, this is prevented by the slave hardware. The slave controller must be reset to reload the alias address. An EC_NOTIFY_EEPROM_OPERATION is given on completion or timeout. This function may be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_EEPROM_OPERATION_NTFY_DESC](api_slave_control.html.md#d9/dc3/struct_e_c___t___e_e_p_r_o_m___o_p_e_r_a_t_i_o_n___n_t_f_y___d_e_s_c).
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **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
### **emReloadSlaveEEPRomReq() Example**
```cpp
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
dwRes = emReloadSlaveEEPRomReq(dwInstanceId, dwClientId,
dwTferId, EC_TRUE, 1001, 5000 /* timeout */);
```
#### SEE ALSO
- [emNotify - EC_NOTIFY_EEPROM_OPERATION](api_slave_control.html.md#emnotify-ec-notify-eeprom-operation)
- [`emResetSlaveController()`](api_slave_control.html.md#_CPPv422emResetSlaveController10EC_T_DWORD9EC_T_BOOL9EC_T_WORD10EC_T_DWORD)
## emNotify - EC_NOTIFY_EEPROM_OPERATION
This notification is given when a SubDevice EEPROM operation is completed.
**emNotify - EC_NOTIFY_EEPROM_OPERATION**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_EEPROM_OPERATION_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_EEPROM_OPERATION_NTFY_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId
Transfer ID. For every new EEPROM operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer.
### [EC_T_EEPROM_OPERATION_TYPE](api_slave_control.html.md#_CPPv426EC_T_EEPROM_OPERATION_TYPE) eType
Type of EEPROM operation
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwResult
Result of EEPROM operation
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### union \_EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT
### struct \_EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_ACTIVE
### Public Members
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSlavePDIAccessActive
EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active
### struct \_EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_READ
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset
Start address of EEPRom operation. Given by API.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwData
Pointer to WORD array containing the data. Given by API.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwReadLen
Number of Words to be read. Given by API.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwNumOutData
Number of Words actually read from EEPRom
### struct \_EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_WRITE
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset
Start address of EEPRom operation. Given by API.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwData
Pointer to WORD array containing the data. Given by API.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwWriteLen
Number of Words to be written. Given by API.
### enum EC_T_EEPROM_OPERATION_TYPE
*Values:*
### enumerator eEEPRomOp_Unknown
Unknown EEPROM operation, only for internal use
### enumerator eEEPRomOp_Assign
Assign slave EEPROM operation, used by emAssignSlaveEEPRomReq
### enumerator eEEPRomOp_Active
Active slave EEPROM operation, used by emActiveSlaveEEPRomReq
### enumerator eEEPRomOp_Read
Read slave EEPRom operation, used by emReadSlaveEEPRomReq
### enumerator eEEPRomOp_Write
Write slave EEPRom operation, used by emWriteSlaveEEPRomReq
### enumerator eEEPRomOp_Reload
Reload slave EEPRom operation, used by emReloadSlaveEEPRomReq
### enumerator eEEPRomOp_Reset
Reset slave EEPRom operation, used by emResetSlaveController
## emResetSlaveController
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatResetSlaveController([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emResetSlaveController([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Reset EtherCAT slave controller (ESC)
A special sequence of three independent and consecutive frames/commands is sent to the slave (reset register ECAT 0x0040 or PDI 0x0041), after which the slave resets. If that fails, the reset sequence is repeated until it succeeds or the timeout expires. The ESC must support resetting and the slave state should be INIT when calling this function. The number of acyclic frames per cycle [EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesPerCycle](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_1a34882b698c00a4c5a7dcab0c18286629) must be at least 3, otherwise an error is returned. This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. The timeout value must not be set to EC_NOWAIT.
* **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
* [EC_E_NOTSUPPORTED](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_1ga11f77305fb1d3868539a735298cc7864) if [EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesPerCycle](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_1a34882b698c00a4c5a7dcab0c18286629) is less than 3
* [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if the slave is not present
* [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
### **emResetSlaveController() Example**
```cpp
/* reset EtherCAT slave controller */
dwRes = emResetSlaveController(dwInstanceId, EC_TRUE, 1001, 5000 /* timeout */);
```
## emIoCtl - EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE
### EC_IOCTL_ALL_SLAVES_MUST_REACH_MASTER_STATE
Specifies if all the slaves must reach the requested master state.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE all slaves must reach the master requested state, if set to EC_FALSE the master can reach the requested state even if some slaves are missing or cannot reach the requested state.
* **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
* **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
Missing mandatory SubDevices will be signalized by [emNotify - EC_NOTIFY_SLAVE_PRESENCE](api_busscan.html.md#emnotify-ec-notify-slave-presence). SubDevices that cannot reach the requested MainDevice state will be signalized by [emNotify - EC_NOTIFY_SLAVE_UNEXPECTED_STATE](api_diagnosis.html.md#emnotify-ec-notify-slave-unexpected-state). [emNotify - EC_NOTIFY_NOT_ALL_DEVICES_OPERATIONAL](api_diagnosis.html.md#emnotify-ec-notify-not-all-devices-operational) will not be generated anymore if this IOCTL is called with [`EC_FALSE`](toc_api.html.md#c.EC_FALSE), [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) will be still generated.
## emGetCfgSlaveInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetCfgSlaveInfo([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bStationAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_CFG_SLAVE_INFO](api_slave_control.html.md#_CPPv419EC_T_CFG_SLAVE_INFO) \*pSlaveInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetCfgSlaveInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_CFG_SLAVE_INFO](api_slave_control.html.md#_CPPv419EC_T_CFG_SLAVE_INFO) \*pSlaveInfo)
Return information about a configured slave from the ENI file.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **pSlaveInfo** – [out] Information about the slave
* **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
### struct EC_T_CFG_SLAVE_INFO
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId
[out] Slave’s ID to bind bus slave and config slave information
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) abyDeviceName[ECAT_DEVICE_NAMESIZE]
[out] Slave’s configured name (80 Byte) (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwHCGroupIdx
[out] Index of Hot Connect group, 0 for mandatory
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIsPresent
[out] Slave present on bus
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIsHCGroupPresent
[out] Slave’s Hot Connect group present on bus
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwVendorId
[out] Vendor identification (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwProductCode
[out] Product code (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRevisionNumber
[out] Revision number (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSerialNumber
[out] Serial number (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress
[out] Slave’s configured station address (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAutoIncAddress
[out] Slave’s auto increment address (may differ from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdOffsIn
[out] Process input data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdSizeIn
[out] Process input data bit size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdOffsOut
[out] Process output data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdSizeOut
[out] Process output data bit size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdOffsIn2
[out] 2nd sync unit process input data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdSizeIn2
[out] 2nd sync unit process input data bit size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdOffsOut2
[out] 2nd sync unit process output data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdSizeOut2
[out] 2nd sync unit process output data bit size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdOffsIn3
[out] 3rd sync unit process input data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdSizeIn3
[out] 3rd sync unit process input data bit size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdOffsOut3
[out] 3rd sync unit process output data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdSizeOut3
[out] 3rd sync unit process output data bit size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdOffsIn4
[out] 4th sync unit process input data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdSizeIn4
[out] 4th sync unit process input data bit size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdOffsOut4
[out] 4th sync unit process output data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdSizeOut4
[out] 4th sync unit process output data bit size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxSupportedProtocols
[out] Mailbox protocols supported by the slave (from ENI file). Combination of [Supported mailbox protocols](api_slave_control.html.md#d6-d4d-group-e-c-m-b-x-p-r-o-t-o-c-o-l-s) flags.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxOutSize
[out] Mailbox output byte size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxInSize
[out] Mailbox input byte size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxOutSize2
[out] Bootstrap mailbox output byte size (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwMbxInSize2
[out] Bootstrap mailbox input byte size (from ENI file)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDcSupport
[out] Slave supports DC (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumProcessVarsInp
[out] Number of input process data variables (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wNumProcessVarsOutp
[out] Number of output process data variables (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPrevStationAddress
[out] Station address of the previous slave (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPrevPort
[out] Connected port of the previous slave (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIdentifyAdo
[out] ADO used for identification command (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIdentifyData
[out] Identification value to be validated (from ENI file)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byPortDescriptor
[out] Port descriptor (ESC register 0x0007) (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffsIn[EC_CFG_SLAVE_PD_SECTIONS]
[out] Offset of WkcState bit in diagnosis image (ENI: ProcessData/Recv[1..4]/BitStart): 0xFFFFFFFF = offset not available. WkcState bit values: 0 = Data valid, 1 = Data invalid.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagOffsOut[EC_CFG_SLAVE_PD_SECTIONS]
[out] Offset of WkcState bit in diagnosis image (ENI: ProcessData/Send[1..4]/BitStart): 0xFFFFFFFF = offset not available. WkcState bit values: 0 = Data valid, 1 = Data invalid.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) awMasterSyncUnitIn[EC_CFG_SLAVE_PD_SECTIONS]
[out] Sync Unit (ENI: ProcessData/TxPdo[1..4]@Su)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) awMasterSyncUnitOut[EC_CFG_SLAVE_PD_SECTIONS]
[out] Sync Unit (ENI: ProcessData/RxPdo[1..4]@Su)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisabled
[out] Slave disabled by API SetSlaveDisabled / SetSlavesDisabled.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisconnected
[out] Slave disconnected by API SetSlaveDisconnected / SetSlavesDisconnected.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bExtended
[out] Slave generated by API ConfigExtend
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDcReferenceClock
[out] Slave is reference clock (from ENI file)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDcPotentialRefClock
[out] Slave can be used as a reference clock (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDcCycleTime0
[out] Cycle time of Sync0 event [ns] (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDcCycleTime1
[out] Calculated value dwDcCycleTime1 [ns] = Cycle time of Sync1 event - Cycle time of Sync1 event + Shift time of Sync0 event (from ENI file)
### [EC_T_INT](toc_api.html.md#_CPPv48EC_T_INT) nDcShiftTime
[out] Shift time of Sync0 event [ns] (from ENI file)
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szProductRevision[24]
[out] Slave’s ProductRevision (ENI:Slave/Info/ProductRevision), e.g. “EK1100-0000-0018”. Empty string if not present in ENI.
**Supported mailbox protocols flags**
### EC_MBX_PROTOCOL_AOE
### EC_MBX_PROTOCOL_EOE
### EC_MBX_PROTOCOL_COE
### EC_MBX_PROTOCOL_FOE
### EC_MBX_PROTOCOL_SOE
### EC_MBX_PROTOCOL_VOE
### **emGetCfgSlaveInfo() Example**
```cpp
/* get information about slave configured in ENI file */
EC_T_CFG_SLAVE_INFO oSlaveInfo;
OsMemset(&oSlaveInfo, 0, sizeof(EC_T_CFG_SLAVE_INFO));
dwRes = emGetCfgSlaveInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveInfo);
```
## emGetCfgSlaveEoeInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetCfgSlaveEoeInfo([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bStationAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_CFG_SLAVE_EOE_INFO](api_slave_control.html.md#_CPPv423EC_T_CFG_SLAVE_EOE_INFO) \*pSlaveEoeInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetCfgSlaveEoeInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_CFG_SLAVE_EOE_INFO](api_slave_control.html.md#_CPPv423EC_T_CFG_SLAVE_EOE_INFO) \*pSlaveEoeInfo)
Return EoE information about a configured slave from the ENI file.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **pSlaveEoeInfo** – [out] Information about the slave
* **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
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
* [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if the slave does not support mailbox communication
* [EC_E_NO_EOE_SUPPORT](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_1gae1e7c653cdf6275070be88c546b34ce1) if the slave supports mailbox communication, but not EoE
### struct EC_T_CFG_SLAVE_EOE_INFO
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId
[out] Slave ID
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMacAddr
[out] Indicates whether the MAC address could be read and is valid
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyMacAddr[6]
[out] MAC address
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIpAddr
[out] Indicates whether the IP address could be read and is valid
### [EC_T_IPADDR](ras_api.html.md#_CPPv411EC_T_IPADDR) oIpAddr
[out] IP address
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSubnetMask
[out] Indicates whether the subnet mask could be read and is valid
### [EC_T_IPADDR](ras_api.html.md#_CPPv411EC_T_IPADDR) oSubnetMask
[out] Subnet mask
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDefaultGateway
[out] Indicates whether the default gateway could be read and is valid
### [EC_T_IPADDR](ras_api.html.md#_CPPv411EC_T_IPADDR) oDefaultGateway
[out] Default gateway
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDnsServer
[out] Indicates whether the DNS server could be read and is valid
### [EC_T_IPADDR](ras_api.html.md#_CPPv411EC_T_IPADDR) oDnsServer
[out] DNS server
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDnsName
[out] Indicates whether the DNS name could be read and is valid
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szDnsName[32]
[out] DNS name
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisableEoe
[out] Indicates whether the EoE is Disabled or not
### **emGetCfgSlaveEoeInfo() Example**
```cpp
/* get EoE information about slave configured in ENI file */
EC_T_CFG_SLAVE_EOE_INFO oSlaveInfo;
OsMemset(&oSlaveInfo, 0, sizeof(EC_T_CFG_SLAVE_EOE_INFO));
dwRes = emGetCfgSlaveEoeInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveInfo);
```
## emGetCfgSlaveSmInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetCfgSlaveSmInfo([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bStationAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_CFG_SLAVE_SM_INFO](api_slave_control.html.md#_CPPv422EC_T_CFG_SLAVE_SM_INFO) \*pSlaveSmInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetCfgSlaveSmInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_CFG_SLAVE_SM_INFO](api_slave_control.html.md#_CPPv422EC_T_CFG_SLAVE_SM_INFO) \*pSlaveSmInfo)
Return SyncManager information of a configured slave from the ENI file.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **pSlaveSmInfo** – [out] Information about the slave.
* **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
### struct EC_T_CFG_SLAVE_SM_ENTRY
### Public Members
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPhysAddr
[out] ESC (0x800 + y \* 8)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLength
[out] ESC (0x802 + y \* 8)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byOpMode
[out] Bits 0..1 ESC (0x804 + y \* 8)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byDirection
[out] Bits 2..3 ESC (0x804 + y \* 8)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdBitOffs
[out] Process input data bit offset (from ENI file)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPdBitSize
[out] Process input data bit size (from ENI file)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wWkcStateDiagBitOffs
[out] Offset of WkcState bit in diagnosis image
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMasterSyncUnit
[out] Sync Unit (ENI: ProcessData/TxPdo[1..4]@Su)
### struct EC_T_CFG_SLAVE_SM_INFO
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId
[out] Slave ID
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSmInfoNumOf
[out] Number of available sync managers
### [EC_T_CFG_SLAVE_SM_ENTRY](api_slave_control.html.md#_CPPv423EC_T_CFG_SLAVE_SM_ENTRY) aoSmInfos[ECREG_SYNCMANAGER_MAX_NUMOF]
[out] Sync managers info
### **emGetCfgSlaveSmInfo() Example**
```cpp
/* get information about slave's sync managers configured in ENI file */
EC_T_CFG_SLAVE_SM_INFO oSlaveSmInfo;
OsMemset(&oSlaveSmInfo, 0, sizeof(EC_T_CFG_SLAVE_SM_INFO));
dwRes = emGetCfgSlaveSmInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveSmInfo);
```
## emGetBusSlaveInfo
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetBusSlaveInfo([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bStationAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BUS_SLAVE_INFO](api_slave_control.html.md#_CPPv419EC_T_BUS_SLAVE_INFO) \*pSlaveInfo)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetBusSlaveInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BUS_SLAVE_INFO](api_slave_control.html.md#_CPPv419EC_T_BUS_SLAVE_INFO) \*pSlaveInfo)
Return information about a slave connected to the EtherCAT bus.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **pSlaveInfo** – [out] Information from the slave
* **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
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
### struct EC_T_BUS_SLAVE_INFO
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId
[out] The slave’s ID to bind bus slave and config slave information
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) adwPortSlaveIds[ESC_PORT_COUNT]
[out] The slave’s ID of the slaves connected to ports. See [Port slave ID’s](api_slave_control.html.md#df-dfc-group-e-c-s-l-a-v-e-i-d-s).
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPortState
[out] Port link state. Format: wwww xxxx yyyy zzzz (each nibble : port 3210)
wwww : Signal detected 1=yes, 0=no
xxxx : Loop closed 1=yes, 0=no
yyyy : Link established 1=yes, 0=no
zzzz : Slave connected 1=yes, 0=no (zzzz = logical result of w,x,y)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAutoIncAddress
[out] The slave’s auto increment address
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDcSupport
[out] Slave supports DC (Bus Topology Scan)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDc64Support
[out] Slave supports 64 Bit DC (Bus Topology Scan)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwVendorId
[out] Vendor Identification stored in the EEPROM at offset 0x0008
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwProductCode
[out] Product Code stored in the EEPROM at offset 0x000A
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRevisionNumber
[out] Revision number stored in the EEPROM at offset 0x000C
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSerialNumber
[out] Serial number stored in the EEPROM at offset 0x000E
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byESCType
[out] Type of ESC (Value of slave ESC register 0x0000)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byESCRevision
[out] Revision number of ESC (Value of slave ESC register 0x0001)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wESCBuild
[out] Build number of ESC (Value of slave ESC register 0x0002)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byPortDescriptor
[out] Port descriptor (Value of slave ESC register 0x0007)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wFeaturesSupported
[out] Features supported (Value of slave ESC register 0x0008)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress
[out] The slave’s station address (Value of slave ESC register 0x0010)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAliasAddress
[out] The slave’s alias address (Value of slave ESC register 0x0012)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAlStatus
[out] AL status (Value of slave ESC register 0x0130)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAlStatusCode
[out] AL status code. (Value of slave ESC register 0x0134 during last error acknowledge). This value is reset after a slave state change.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSystemTimeDifference
[out] System time difference. (Value of slave ESC register 0x092C)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wMbxSupportedProtocols
[out] Supported Mailbox Protocols stored in the EEPROM at offset 0x001C
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDlStatus
[out] DL status (Value of slave ESC register 0x0110)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPrevPort
[out] Connected port of the previous slave
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wIdentifyData
[out] Last read identification value see [EC_T_CFG_SLAVE_INFO.wIdentifyAdo](api_slave_control.html.md#d5/dca/struct_e_c___t___c_f_g___s_l_a_v_e___i_n_f_o_1a5972bcd59947447718549523d67d828d)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bLineCrossed
[out] Line crossed was detected at this slave
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveDelay
[out] Delay behind slave [ns].
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPropagDelay
[out] Propagation delay [ns]. ESC register 0x0928.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIsRefClock
[out] Slave is reference clock
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bIsDeviceEmulation
[out] Slave without Firmware. ESC register 0x0141, enabled by EEPROM offset 0x0000.8.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wLineCrossedFlags
[out] Combination of [Line crossed flags](api_slave_control.html.md#db-d4d-group-e-c-l-i-n-e-c-r-o-s-s-e-d-f-l-a-g-s)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCyclicWkcErrorCnt
[out] Counter for Cyclic WC Error
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveAbsentCnt
[out] Counter for Absent/Not Present Slaves
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwUnexpectedStateCnt
[out] Counter for Abnormal State Change
**Port Slave ID’s**
### MASTER_SLAVE_ID
### SIMULATOR_SLAVE_ID
### MASTER_RED_SLAVE_ID
### EL9010_SLAVE_ID
### FRAMELOSS_SLAVE_ID
### JUNCTION_RED_FLAG
**EC_LINECROSSED_ flags**
### EC_LINECROSSED_NOT_CONNECTED_PORTA
### EC_LINECROSSED_UNEXPECTED_INPUT_PORT
### EC_LINECROSSED_UNEXPECTED_JUNCTION_RED
### EC_LINECROSSED_UNRESOLVED_PORT_CONNECTION
### EC_LINECROSSED_HIDDEN_SLAVE_CONNECTED
### EC_LINECROSSED_PHYSIC_MISMATCH
### EC_LINECROSSED_INVALID_PORT_CONNECTION
### EC_LINECROSSED_UNEXPECTED_CABLE_RED
### **emGetBusSlaveInfo() Example**
```cpp
/* get information about slave connected to EtherCAT bus */
EC_T_BUS_SLAVE_INFO oSlaveInfo;
OsMemset(&oSlaveInfo, 0, sizeof(EC_T_BUS_SLAVE_INFO));
dwRes = emGetBusSlaveInfo(dwInstanceId, EC_TRUE, 1001, &oSlaveInfo);
```
## emReadSlaveIdentification
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReadSlaveIdentification([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAdo, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwValue, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emReadSlaveIdentification([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAdo, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwValue, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Read identification value from a slave.
This function may not be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wAdo** – [in] ADO used for identification command
* **pwValue** – [out] Pointer to Word value containing the Identification value
* **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_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
* [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_ADO_NOT_SUPPORTED](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_1ga76fa8b6a484e5f447a89bc16a8a4c95d) if the slave does not support requesting ID mechanism
* [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
### **emReadSlaveIdentification() Example**
```cpp
/* get identification value from slave */
EC_T_WORD wValue = 0;
dwRes = emReadSlaveIdentification(dwInstanceId, EC_TRUE, 1001,
0x0134 /* explicit device ID */, &wValue, 5000 /* timeout */);
```
## emReadSlaveIdentificationReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatReadSlaveIdentificationReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAdo, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwValue, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emReadSlaveIdentificationReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAdo, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwValue, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Request the identification value from a slave and returns immediately.
A notification EC_NOTIFY_SLAVE_IDENTIFICATION is given on completion or timeout. This function may be called from within the JobTask’s context.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_SLAVE_IDENTIFICATION_NTFY_DESC](api_slave_control.html.md#d6/d3b/struct_e_c___t___s_l_a_v_e___i_d_e_n_t_i_f_i_c_a_t_i_o_n___n_t_f_y___d_e_s_c).
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **wAdo** – [in] ADO used for identification command
* **pwValue** – [out] Pointer to Word value containing the Identification value, must be valid until the request complete.
* **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_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
* [EC_E_ADO_NOT_SUPPORTED](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_1ga76fa8b6a484e5f447a89bc16a8a4c95d) if the slave does not support requesting ID mechanism
### **emReadSlaveIdentificationReq() Example**
```cpp
/* get identification value from slave (non-blocking) */
EC_T_WORD wValue = 0;
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
dwRes = emReadSlaveIdentificationReq(dwInstanceId, dwClientId,
dwTferId, EC_TRUE, 1001, 0x0134 /* explicit device ID */, &wValue, 5000 /* timeout */);
```
#### SEE ALSO
[emNotify - EC_NOTIFY_SLAVE_IDENTIFICATION](api_slave_control.html.md#emnotify-ec-notify-slave-identification)
## emNotify - EC_NOTIFY_SLAVE_IDENTIFICATION
This notification is given, when the read SubDevice identification request is completed.
**emNotify - EC_NOTIFY_SLAVE_IDENTIFICATION**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_SLAVE_IDENTIFICATION_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_SLAVE_IDENTIFICATION_NTFY_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId
Transfer ID. For every new port operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwResult
Result of request
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wAdo
Slave address offset used for identification. Given by API.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wValue
Slave identification value. Given by API.
## emIoCtl - EC_IOCTL_SET_AUTO_ACK_AL_STATUS_ERROR_ENABLED
### EC_IOCTL_SET_AUTO_ACK_AL_STATUS_ERROR_ENABLED
Specifies if slave errors must be automatically acknowledged.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE slave errors must be automatically acknowledged, if set to EC_FALSE the application must acknowledge slave errors explicitly.
* **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
* **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
The pending SubDevice error will be acknowledged during the next [`emSetSlaveState()`](api_slave_control.html.md#_CPPv415emSetSlaveState10EC_T_DWORD10EC_T_DWORD9EC_T_WORD10EC_T_DWORD) call.
## emIoCtl - EC_IOCTL_SET_AUTO_ADJUST_CYCCMD_WKC_ENABLED
### EC_IOCTL_SET_AUTO_ADJUST_CYCCMD_WKC_ENABLED
Specifies if the cyclic commands expected WKC must be automatically adjusted according to the state and the presence of the slaves.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL variable. If set to EC_TRUE cyclic commands expected WKC must be automatically adjusted, if set to EC_FALSE the cyclic commands expected WKC stays unchanged.
* **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
* **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
If TRUE, the notification [emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR](api_diagnosis.html.md#emnotify-ec-notify-cyccmd-wkc-error) is only generated if a SubDevice doesn’t increment the WKC although it should. `AUTO_ADJUST_CYCCMD_WKC` is disabled by default.
#### SEE ALSO
- [Cyclic cmd WKC validation and Frame Loss](software-integration_error-detection.html.md#cyclic-cmd-wkc-validation-and-frame-loss)
- [Working Counter (WKC) State in Diagnosis Image](software-integration_error-detection.html.md#working-counter-wkc-state-in-diagnosis-image)
## emSetSlaveDisabled
Before using this function, please check if the following patents have to be taken into consideration for your application and use case:
- JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE
- JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM
- JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetSlaveDisabled([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisabled)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetSlaveDisabled([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisabled)
Enable or disable a specific slave.
The EtherCAT state of disabled slaves cannot be set higher than PREOP. If the state is higher than PREOP at the time this function is called the state will be automatically changed to PREOP. The information about the last requested state is lost and is set to PREOP too.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **bDisabled** – [in] EC_TRUE: Disable slave, EC_FALSE: Enable slave
* **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
### **emSetSlaveDisabled() Example**
```cpp
/* enable or disable specific slave */
dwRes = emSetSlaveDisabled(dwInstanceId, EC_TRUE, 1002, EC_TRUE /* disabled */);
```
## emIoCtl - EC_IOCTL_SET_SLAVE_MAX_STATE
Specifies maximum state for specific slave.
### EC_IOCTL_SET_SLAVE_MAX_STATE
Set maximum state for the slave.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to struct [EC_T_SLAVE_MAX_STATE_DESC](api_slave_control.html.md#d0/df8/struct_e_c___t___s_l_a_v_e___m_a_x___s_t_a_t_e___d_e_s_c)
* **dwInBufSize** – [in] Size of the input buffer in bytes, e.g. sizeof(EC_T_SLAVE_MAX_STATE_DESC)
* **pbyOutBuf** – [out] Should be set to EC_NULL
* **dwOutBufSize** – [in] Should be set to 0
* **pdwNumOutData** – [out] Should be set to EC_NULL
* **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
### struct EC_T_SLAVE_MAX_STATE_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId
[in] Slave ID
### [EC_T_STATE](api_general_functions.html.md#_CPPv410EC_T_STATE) eState
[in] Requested Slave State
## emSetSlaveDisconnected
Before using this function, please check if the following patents have to be taken into consideration for your application and use case:
- JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE
- JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM
- JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetSlaveDisconnected([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisconnected)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetSlaveDisconnected([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisconnected)
Mark specific slave for connection or disconnection.
The EtherCAT state of disconnected slaves cannot be set higher than INIT. If the state is higher than INIT at the time this function is called, the state will be automatically changed to INIT. The information about the last requested state is lost and is set to INIT too.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **bDisconnected** – [in] EC_TRUE: Mark slave for disconnection, EC_FALSE: Mark slave for (re-)connection
* **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
### **emSetSlaveDisconnected() Example**
```cpp
/*Connect or disconnect specific slave*/
dwRes = emSetSlaveDisconnected(dwInstanceId, EC_TRUE, 1002,
EC_TRUE /* disconnected */);
```
## emSetSlavesDisconnected
Before using this function, please check if the following patents have to be taken into consideration for your application and use case:
- JP2014146077: CONTROL DEVICE AND OPERATION METHOD FOR CONTROL DEVICE
- JP2014146070: CONTROL DEVICE, CONTROL METHOD, AND PROGRAM
- JP2014120884: INFORMATION PROCESSING APPARATUS, INFORMATION ROCESSING PROGRAM, AND INFORMATION PROCESSING METHOD
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetSlavesDisconnected([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, EC_T_SLAVE_SELECTION eSlaveSelection, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisconnected)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetSlavesDisconnected([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, EC_T_SLAVE_SELECTION eSlaveSelection, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisconnected)
Mark a specific group of slaves for connection or disconnection.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address
* **wSlaveAddress** – [in] Slave address according bFixedAddressing
* **eSlaveSelection** – [in] Slave selection criteria
* **bDisconnected** – [in] EC_TRUE: mark slaves for disconnection, EC_FALSE: mark slaves for connection
* **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
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching bFixedAddressing / wSlaveAddress can be found
### **emSetSlavesDisconnected() Example**
```cpp
/* set specific group of slaves for connection or disconnection */
dwRes = emSetSlavesDisconnected(dwInstanceId, EC_TRUE, 1001,
eSlaveSelectionTopoFollowers, EC_TRUE /* disconnected*/);
```
#### SEE ALSO
[`emSetSlaveDisconnected()`](api_slave_control.html.md#_CPPv422emSetSlaveDisconnected10EC_T_DWORD9EC_T_BOOL9EC_T_WORD9EC_T_BOOL)
## emGetSlavePortState
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatGetSlavePortState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwPortState)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emGetSlavePortState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwPortState)
Returns the state of the slave ports.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **pwPortState** –
[out] Slave port state.
Format: wwww xxxx yyyy zzzz (each nibble : port 3210)
wwww : Signal detected 1=yes, 0=no (ESC Register 0x110 Bit 9, 11, 13, 15)
xxxx : Loop closed 1=yes, 0=no (ESC Register 0x110 Bit 8, 10, 12, 14)
yyyy : Link established 1=yes, 0=no (ESC Register 0x110 Bit 4, 5, 6, 7)
zzzz : Slave connected 1=yes, 0=no (zzzz = logical result of w,x,y)
* **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 output pointer is EC_NULL
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
### **emGetSlavePortState() Example**
```cpp
EC_T_DWORD dwSlaveId = 2;
EC_T_WORD wPortState = 0;
dwRes = emGetSlavePortState(dwInstanceId, dwSlaveId, &wPortState);
```
#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emSetSlavePortState
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetSlavePortState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPort, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bClose, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bForce, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetSlavePortState([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPort, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bClose, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bForce, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Open or close slave port.
This function allows to open or close a specific slave port in different ways. It can also be used to re-open ports closed by a rescue scan.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwSlaveId** – [in] Slave ID
* **wPort** – [in] Port to open or close. Can be ESC_PORT_A, ESC_PORT_B, ESC_PORT_C, ESC_PORT_D.
* **bClose** – [in] EC_TRUE: close port, EC_FALSE: open port
* **bForce** – [in] EC_TRUE: port will be closed or open, EC_FALSE: port will be set in AutoClose mode
* **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
* [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
* [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
### **emSetSlavePortState() Example**
```cpp
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
dwRes = emSetSlavePortState(dwInstanceId, dwSlaveId, ESC_PORT_B,
EC_TRUE /* close */ , EC_TRUE /* force */, 5000 /* timeout */);
```
#### SEE ALSO
- [`emRescueScan()`](api_general_functions.html.md#_CPPv412emRescueScan10EC_T_DWORD10EC_T_DWORD)
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emSetSlavePortStateReq
### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatSetSlavePortStateReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPort, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bClose, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bForce, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emSetSlavePortStateReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwClientId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPort, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bClose, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bForce, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)
Requests Open or close slave port operation and returns immediately.
An [EC_T_PORT_OPERATION_NTFY_DESC](api_slave_control.html.md#dd/db1/struct_e_c___t___p_o_r_t___o_p_e_r_a_t_i_o_n___n_t_f_y___d_e_s_c) is given on completion. This function can be called to re-open ports closed by a rescue scan.
* **Parameters:**
* **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support)
* **dwClientId** – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)
* **dwTferId** – [in] Transfer ID. The application can set this ID to identify the transfer. It will be passed back to the application within [EC_T_PORT_OPERATION_NTFY_DESC](api_slave_control.html.md#dd/db1/struct_e_c___t___p_o_r_t___o_p_e_r_a_t_i_o_n___n_t_f_y___d_e_s_c).
* **dwSlaveId** – [in] Slave ID
* **wPort** – [in] Port to open or close. Can be ESC_PORT_A, ESC_PORT_B, ESC_PORT_C, ESC_PORT_D.
* **bClose** – [in] EC_TRUE: close port, EC_FALSE: open port
* **bForce** – [in] EC_TRUE: port will be closed or open, EC_FALSE: port will be set in AutoClose mode
* **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
* [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
* [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
### **emSetSlavePortStateReq() Example**
```cpp
EC_T_DWORD dwTferId = 1234; /* arbitrary unique ID from application */
EC_T_DWORD dwSlaveId = emGetSlaveId(dwInstanceId, 1001);
dwRes = emSetSlavePortStateReq(dwInstanceId, dwTferId, dwClientId,
dwSlaveId, ESC_PORT_B, EC_TRUE /* close */ , EC_TRUE /* force */, 5000 /* timeout */);
```
#### SEE ALSO
- [emNotify - EC_NOTIFY_PORT_OPERATION](api_slave_control.html.md#emnotify-ec-notify-port-operation)
- [`emRescueScan()`](api_general_functions.html.md#_CPPv412emRescueScan10EC_T_DWORD10EC_T_DWORD)
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
## emNotify - EC_NOTIFY_PORT_OPERATION
This notification is given, when the port operation request is completed.
**emNotify - EC_NOTIFY_PORT_OPERATION**
: **Parameter**
: * `pbyInBuf`: [in] Pointer to EC_T_PORT_OPERATION_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_PORT_OPERATION_NTFY_DESC
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTferId
Transfer ID. For every new port operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwResult
Result of request
### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp
Slave properties
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPortStateOld
Old state of the slave ports
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wPortStateNew
New state of the slave ports
#### SEE ALSO
[`emGetSlavePortState()`](api_slave_control.html.md#_CPPv419emGetSlavePortState10EC_T_DWORD10EC_T_DWORDP9EC_T_WORD)
## emIoCtl - EC_IOCTL_SET_NEW_BUSSLAVES_TO_INIT
### EC_IOCTL_SET_NEW_BUSSLAVES_TO_INIT
Force state change to INIT for all new slaves in the network after detection.
* **Parameters:**
* **pbyInBuf** – [in] Pointer to EC_T_BOOL. EC_TRUE: Force state change, EC_FALSE: No state change.
* **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
* **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
Default: No state change after detection
# emll.html.md
# Real-time Ethernet Driver (RtEth)
The EC-Master currently supports a variety of different Real-time Ethernet Driver modules, each contained in a single library file, which is loaded by the core library dynamically. The EC-Master EtherCAT® MainDevice stack shipment consist of a MainDevice core library (e.g. EcMaster.dll for Windows, libEcMaster.a for Linux) and one (or more) libraries each containing support for one specific Real-time Ethernet Driver module.
Which library actually is loaded depends on the Link Layer parameters at runtime.
Real-time means operating directly on the network adapter’s register set instead of using the operating system’s native driver.
The principle of the Real-time Ethernet Driver selection is that the Real-time Ethernet Driver name (Real-time Ethernet Driver identification) is used to determine the location and name of a registration function called by the EC-Master and registers function pointers that allow access to the Real-time Ethernet Driver functional entries.
The EtherCAT® Real-time Ethernet Driver will be initialized using a Real-time Ethernet Driver specific configuration parameter set.
A pointer to this parameter set is part of the initialization settings of the EC-Master when calling the function [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS).
The EC-Master supports two Real-time Ethernet Driver operating modes.
If the Real-time Ethernet Driver operates in interrupt mode all received Ethernet frames will be processed immediately in the context of the Real-time Ethernet Driver receiver task.
When using the polling mode the EC-Master will call the Real-time Ethernet Driver receiver polling function prior to processing received frames.
**Real-time Ethernet Driver and PHY OS Driver**
Some operating systems, e.g. Linux and Xenomai, provide drivers for most common Ethernet controllers and their related physical transceivers (PHY).
The manufacturer specific PHY circuits can be handled by a dedicated driver.
Using the PHY OS Driver interface it is possible to use the manufacturer’s dedicated PHY driver without modification of the acontis optimized Real-time Ethernet Driver.
Depending on the hardware architecture, an additional module from acontis, e.g. atemsys for Linux, grants access to the MDIO bus to the OS drivers, or request MDIO operations from the OS drivers.
#### NOTE
Real-time Ethernet Driver modules not listed here may be available if purchased additionally. Not all Real-time Ethernet Driver modules support interrupt mode.
# emll_init.html.md
# Real-time Ethernet Driver initialization
The different Real-time Ethernet Driver modules are selected and parameterized by a Real-time Ethernet Driver specific structure. Each Real-time Ethernet Driver specific structure starts with a common [`EC_T_LINK_PARMS`](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) structure, followed by some Real-time Ethernet Driver specific members. The common link parameter structure is passed to [`EC_T_INIT_MASTER_PARMS::pLinkParms`](api_general_functions.html.md#_CPPv4N22EC_T_INIT_MASTER_PARMS10pLinkParmsE) with the call of [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS) like in the following example:
```cpp
/* identify Link Layer in the common struture */
oLinkParmsSockRaw.linkParms.dwSignature = EC_LINK_PARMS_SIGNATURE_SOCKRAW;
oLinkParmsSockRaw.linkParms.dwSize = sizeof(EC_T_LINK_PARMS_SOCKRAW);
OsSafeStrncpy(oLinkParmsSockRaw.linkParms.szDriverIdent, EC_LINK_PARMS_IDENT_SOCKRAW, EC_DRIVER_IDENT_NAME_SIZE);
/* specific Link Layer parameters should be set here */
/* pass Link Layer parameters */
oInitMasterParms.dwSignature = ATECAT_SIGNATURE;
oInitMasterParms.dwSize = sizeof(EC_T_INIT_MASTER_PARMS);
oInitMasterParms.pLinkParms = &oLinkParmsSockRaw.linkParms;
/* more parameters should be set here */
/* initialize master */
emInitMaster(dwInstanceId, &oInitMasterParms);
```
### struct EC_T_LINK_PARMS
### Public Members
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSignature
[in] Signature of the adapter specific structure containing the [EC_T_LINK_PARMS](emll_init.html.md#d1/d58/struct_e_c___t___l_i_n_k___p_a_r_m_s) structure
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSize
[in] Size of the adapter specific structure containing the [EC_T_LINK_PARMS](emll_init.html.md#d1/d58/struct_e_c___t___l_i_n_k___p_a_r_m_s) structure
### [EC_T_LOG_PARMS](api_general_functions.html.md#_CPPv414EC_T_LOG_PARMS) LogParms
[in] Logging parameters
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szDriverIdent[EC_DRIVER_IDENT_NAME_SIZE]
[in] Name of Link Layer module (driver identification) for Link Layer Selection
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstance
[in] Instance of the adapter. If EC_LINKUNIT_PCILOCATION is set: contains PCI address.
### [EC_T_LINKMODE](emll_init.html.md#_CPPv413EC_T_LINKMODE) eLinkMode
[in] Mode of operation
### EC_T_CPUSET cpuIstCpuAffinityMask
[in] Interrupt service thread CPU affinity mask
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIstPriority
[in] Task priority of the interrupt service task (not used in polling mode)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwIstStackSize
[in] Task stack size
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLinkSpeed
[in] 10, 100, 1000 Mbit/s
### [EC_T_LINKLAYER_TIMINGTASK](emll_init.html.md#_CPPv425EC_T_LINKLAYER_TIMINGTASK) oLinkLayerTimingTask
[in] LinkLayer timimg task parameters
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szLoadPath[EC_DRIVER_PATH_SIZE]
[in] Path from which the libraries should be loaded
### enum EC_T_LINKMODE
*Values:*
### enumerator EcLinkMode_UNDEFINED
Link is in an undefined state, must be polling or interrupt
### enumerator EcLinkMode_INTERRUPT
Link is in interrupt mode and is triggered by interrupts
### enumerator EcLinkMode_POLLING
Link is in polling mode and is polled periodically
### struct EC_T_LINKLAYER_TIMINGTASK
### Public Members
### [EC_T_LINKLAYER_TIMING](emll_init.html.md#_CPPv421EC_T_LINKLAYER_TIMING) eLinkLayerTiming
[in] LinkLayer timing task mode
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCycleTimeNsec
[in] Cycle time between 2 pfnStartCycle calls in ns. Will be set by the master stack for the link layer.
### EC_T_LINK_STARTCYCLE_CALLBACK pfnStartCycle
[in] Callback function called cyclically according to dwCycleTimeNsec
### EC_T_VOID \*pvStartCycleContext
[in] Context passed to each pfnStartCycle call
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTtsSendOffsetUsec
[in] Time between pfnStartCycle call and TTS frame transmission
### EC_T_UINT64 nSystemTime
[in] System
### enum EC_T_LINKLAYER_TIMING
*Values:*
### enumerator eLinkLayerTiming_Undefined
Link Layer Timing is undefined must be TTS or TMR
### enumerator eLinkLayerTiming_TTS
Real-time Ethernet Driver Time Triggered Send
### enumerator eLinkLayerTiming_TMR
Real-time Ethernet Driver Timer
### enum EC_T_PHYINTERFACE
*Values:*
### enumerator ePHY_UNDEFINED
Undefined
### enumerator ePHY_FIXED_LINK
No PHY access at all
### enumerator ePHY_MII
MII 10 / 100 MBit
### enumerator ePHY_RMII
Reduced MII, 10 / 100 MBit
### enumerator ePHY_GMII
Gigabit MII, 10, 100, 1000 MBit
### enumerator ePHY_SGMII
Serial (SERDES) Gigabit MII, 10, 100, 1000 MBit
### enumerator ePHY_RGMII
Reduced Gigabit MII, 10, 100, 1000 MBit
### enumerator ePHY_OSDRIVER
Get interface type from OS
### enumerator ePHY_RMII_50MHZ
ePHY_RMII with 50 MHz clock mode
### enumerator ePhy_10GBASER
10GBASE-R (64b/66b) serial interface, 10 GBit
### enumerator ePhy_25GBASER
25GBASE-R (64b/66b) serial interface, 25 GBit
## Real-time Ethernet Driver instance selection via PCI location
For some operating systems it is possible to address the Real-time Ethernet Driver instance using its PCI address as an alternative. To do this, EC_LINKUNIT_PCILOCATION (0x01000000) and the PCI location must be set as [`EC_T_LINK_PARMS::dwInstance`](emll_init.html.md#_CPPv4N15EC_T_LINK_PARMS10dwInstanceE).
On Linux the PCI address can be shown using e.g.:
```console
$ lspci | grep Ethernet
```
```console
$ 00:19.0 Ethernet controller: Intel Corporation Ethernet Connection I217-LM (rev 04)
$ 04:00.0 Ethernet controller: Intel Corporation 82574L Gigabit Network Connection
$ 05:00.0 Ethernet controller: Intel Corporation 82574L Gigabit Network Connection
```
The format of [`EC_T_LINK_PARMS::dwInstance`](emll_init.html.md#_CPPv4N15EC_T_LINK_PARMS10dwInstanceE) using PCI bus address is:
0x01bbddff
: - bb Bus Number
- dd Device Number
- ff Function Number
```cpp
EC_T_LINK_PARMS::dwInstance = 0x01001900; //"0000:00:19.0"
```
On Windows the integer value displayed in properties dialog must be converted to HEX. E.g the number from the following dialog (PCI bus 11, device 0, function 0) corresponds to 0x010B0000 (bus 0x0B).
# emllbcmgenet.html.md
# Broadcom Genet - emllBcmGenet
The parameters to the Real-time Ethernet Driver Broadcom® Genet are setup-specific.
The function `CreateLinkParmsFromCmdLineBcmGenet()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_BCMGENET
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_BCMGENET.
### [EC_T_BCMGENET_TYPE](emllbcmgenet.html.md#_CPPv418EC_T_BCMGENET_TYPE) eSocType
Broadcom processor type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY interface type
### enum EC_T_BCMGENET_TYPE
*Values:*
### enumerator eBCMGENET_BCM2711
Broadcom BCM2711, Raspberry Pi 4
# emllbcmnetxtreme.html.md
# Broadcom NetXtreme - emllBcmNetXtreme
The parameters to the Real-time Ethernet Driver Broadcom® NetXtreme are setup-specific.
The function `CreateLinkParmsFromCmdLineBcmNetXtreme()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Link Layer instance.
### struct EC_T_LINK_PARMS_BCMNETXTREME
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_BCMNETXTREME.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBuffers
Receive buffer count. Must be a power of 2, maximum 1024.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxBuffers
Transmit buffer count. Must be a power of 2, maximum 1024.
## Supported PCI devices
Broadcom 571x PCI specific definitions (VendorId, DeviceId)
# emllbpf.html.md
# Berkeley Packet Filter - emllBPF
The Ethernet Driver BPF is always part of the EC-Master for QNX package. It uses already established Ethernet adapters, e.g. wm0, rt0, etc. It is strongly recommended to use a separate network adapter to connect EtherCAT® network adapters. If the main network adapter is used for both EtherCAT® network adapters and the local area network there may be a major impact on the local area network operation.
#### NOTE
The BPF Ethernet Driver cannot be used for real time applications and may need cycle time of 1 ms or higher.
The parameters to the Ethernet Driver BPF are setup-specific. The function `CreateLinkParmsFromCmdLineBPF()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Ethernet Driver instance.
### struct EC_T_LINK_PARMS_BPF
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_BPF.
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szIfName[EC_BPF_IF_NAME_SIZE]
Name of Ethernet Interface
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szPrefix[EC_BPF_IF_NAME_SIZE]
Optional prefix of the BPF instance path
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBuffers
Receive buffer count
# emllccat.html.md
# Beckhoff CCAT - emllCCAT
The parameters to the Real-time Ethernet Driver CCAT are setup-specific.
The function `CreateLinkParmsFromCmdLineCCAT()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
Because the link status cannot be read quickly from a register of the adapter, it will not be automatically refreshed like by the other Real-time Ethernet Drivers.
### struct EC_T_LINK_PARMS_CCAT
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_CCAT.
### [EC_T_CCAT_TYPE](emllccat.html.md#_CPPv414EC_T_CCAT_TYPE) eCcatType
CCAT connection type
### EC_T_UINT64 qwCcatBase
Physical address of register block, only for eCCAT_EIM
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwCcatSize
Size of register block, only for eCCAT_EIM
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBufferCnt
Receive buffer count, only for eCCAT_EIM
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxBufferCnt
Transmit buffer count, only for eCCAT_EIM
### enum EC_T_CCAT_TYPE
*Values:*
### enumerator eCCAT_PCI
CCAT connected to PCI bus
### enumerator eCCAT_EIM
CCAT connected via EIM. Used in ARM systems, no DMA
## Supported PCI devices
Beckhoff CCAT PCI specific definitions (VendorId, DeviceId)
# emllcmsiseth.html.md
# CMSIS - emllCmsisEth
The parameters to the Real-time Ethernet Driver CmsisEth are setup-specific.
The function `CreateLinkParmsFromCmdLineCmsisEth()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_CMSISETH
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_CMSISETH.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBuffersCnt
Receive buffer count
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBufferLen
Receive buffer size for a single Ethernet frame
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxBuffersCnt
Transmit buffer count
# emllcpsw.html.md
# Texas Instruments CPSW - emllCPSW
The parameters to the Real-time Ethernet Driver CPSW are setup-specific.
The function `CreateLinkParmsFromCmdLineCPSW()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_CPSW
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_CPSW.
### [EC_T_CPSW_TYPE](emllcpsw.html.md#_CPPv414EC_T_CPSW_TYPE) eCpswType
CPSW type
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPortPrio
0 (lowest), 1 (highest)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMaster
EC_TRUE: Initialize MAC
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bPhyRestartAutoNegotiation
EC_TRUE: Restart auto negotiation on initialization
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY connection type
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxInterrupt
Receive interrupt number (IRQ)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
Use buffers from DMA (EC_FALSE) or from heap for receive. AllocSend is not supported, when EC_TRUE. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyAccess
Don’t use MDIO to set up the PHY
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bAleBypass
Enable bAleBypass, similar to promiscuous mode
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwExtendRxFrameLength
Receive longer Rx Frames
### enum EC_T_CPSW_TYPE
*Values:*
### enumerator eCPSW_AM33XX
TI AM33xx (e.g. Beaglebone)
### enumerator eCPSW_AM387X
TI DM814x/AM387x (e.g. Mistral/TI 814X/387X BASE EVM)
### enumerator eCPSW_AM437X
TI AM437x
### enumerator eCPSW_AM57X
TI AM57x
## CPSW usage under Linux
Due to the lacking unbind-feature of the CPSW driver, the target’s Kernel must not load the CPSW driver when starting. If the CPSW was built as a module, it can be renamed or removed to ensure it never gets loaded. If it was compiled into the Kernel, the Kernel needs to be recompiled without it.
It is possible to use one CPSW port for Linux kernel (TCP/IP) and another CPSW port for EC-Master. To do this, the CPSW kernel driver must be patched.
Currently following Linux versions are supported:
- linux-4.1.6 from TI Linux SDK 2.0
- linux-4.4.4-rt11 from Lenze
- linux-3.10.93-rt101 from Canon
#### NOTE
A patch for other Linux versions can also be created on request.
The patch needs:
- Linux kernel with enabled CPSW driver.
- Patch applied to Linux kernel.
- EC_ETHERNET_PORT defined according to target in cpsw.c and davinci_mdio.c files.
- Kernel must be rebuilt and installed
After that Linux will have only 1 Ethernet device, another can be used by EC-Master.
#### NOTE
EtherCAT® ports should be used as “slave” since “master” is the Linux driver.
# emllcpswg.html.md
# Texas Instruments CPSWG for AM6x and Jacinto 7 - emllCPSWG
The parameters to the CPSWG Real-time Ethernet Driver are setup-specific.
The function `CreateLinkParmsFromCmdLineCPSWG()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_CPSWG
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_CPSWG.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY address
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY interface type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMaster
EC_TRUE: Initialize MAC
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxDmaDesCnt
Transmit DMA descriptor buffer count. Maximum 500.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxDmaDesCnt
Receive DMA descriptor buffer count. Maximum 500.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### enum EC_T_CPSWG_TYPE
*Values:*
### enumerator eCPSWG_AM654X
TI AM654x
### enumerator eCPSWG_TDA4X
TI TDA4x (Jacinto 7)
### enumerator eCPSWG_AM64X
TI AM64x
### enumerator eCPSWG_AM62X
TI AM62x
## CPSWG usage under Linux
The unbind feature of the am65-cpsw-nuss Linux driver isn’t supported and the atemsys kernel module must be assigned as driver for the platform device.
So the `"ethernet/am654-cpsw-nuss"` device tree node must be modified, by changing `compatible = "atemsys";` and adding `atemsys-Ident = "CPSWG";` and `atemsys-Instance = <0x1>;`, also remove or comment out `dma-coherent;`.
```dts
ethernet@46000000 {
compatible = "atemsys";
atemsys-Ident = "CPSWG";
atemsys-Instance = <0x1>;
...
#dma-coherent;
...
```
So the `"ethernet/am642-cpsw-nuss"` device tree node must be modified likewise.
Second port of am642-cpsw-nuss is not supported.
```dts
ethernet@8000000 {
compatible = "atemsys";
atemsys-Ident = "CPSWG";
atemsys-Instance = <0x1>;
...
#dma-coherent;
...
```
Currently following Linux versions are supported:
- ti-processor-sdk-linux-rt-am65xx-evm-07_01_00_18 (tested on AM65 IDK)
- ti-processor-sdk-linux-rt-am65xx-evm-08.06.00.47 (tested on AM65 IDK)
- ti-processor-sdk-linux-rt-j7-evm-08_06_01_02 (tested on SK-TDA4VM)
- ti-processor-sdk-linux-rt-j7-evm-08_06_01_02 (tested on SK-TDA4VM)
- ti-processor-sdk-linux-edgeai-j721e-evm-09_01_00_06 (tested on SK-TDA4VM)
- ti-processor-sdk-linux-rt-am64xx-evm-08.02.00.14 (tested on TMDS64GPEVM)
- ti-processor-sdk-linux-rt-am64xx-evm-09.02.00.08 (tested on TMDS64GPEVM)
- SolidRun ti_am64x_build/20240221 microsd-debian-bookworm-sr1 (tested on AM64 HummingBoard-T)
- toradex_ti-linux-6.1.y Linux/arm64 6.1.46 Kernel (tested on Toradex Verdin AM62)
# emlldpdk.html.md
# Linux DPDK - emllDpdk
The Real-time Ethernet Driver emllDpdk is based on the Data Plane Development Kit (DPDK V23.11). See [https://www.dpdk.org](https://www.dpdk.org) for more information.
It does not need the atemsys driver and uses Ethernet adapters that are bound to the DPDK interface. The network interface must be bound according to the interface type PCI or SOC.
The parameters to emllDpdk are setup-specific. The function `CreateLinkParmsFromCmdLineDpdk()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize emllDpdk.
### struct EC_T_LINK_PARMS_DPDK
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_DPDK.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPortId
DPDK port ID
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRxBufferCnt
Receive buffer count, 0: defaults to DPDK internal setting
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wTxBufferCnt
Transmit buffer count, 0: default to DPDK internal setting
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDontCheckLinkStatus
Don’t check link status (forced)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSetPromiscuousMode
Change promiscuous mode setting
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bEalInitDeinitByApp
DPDK EAL layer is initialized and deinitialized by user App
#### NOTE
- Root privileges are required.
- emllDpdk increases the stack size by DPDK_SEND_BURST_STACK_SIZE.
## Linux System Requirements
- Kernel configuration
In the Fedora OS and other common distributions, such as Ubuntu, or Red Hat Enterprise Linux, the vendor supplied kernel configurations can be used to run most DPDK applications.
For other kernel builds, options which should be enabled for DPDK include:
```default
HUGETLBFS
PROC_PAGE_MONITOR support
```
- Required Tools, Libraries and further system requirements can be checked under [https://doc.dpdk.org/guides/linux_gsg/sys_reqs.html](https://doc.dpdk.org/guides/linux_gsg/sys_reqs.html)
## Huge pages setup
Create huge pages (not persistent)
```console
$ mkdir -p /dev/hugepages
$ mountpoint -q /dev/hugepages || mount -t hugetlbfs nodev /dev/hugepages
$ echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
```
## DPDK for PCI Network Adapter
First, the driver may need to be loaded, as it may be unloaded per default.
```console
$ sudo modprobe uio_pci_generic
```
Next the network adapter needs to be bound with `dpdk-devbind.py`. Therefore, the PCI addresses have to be found out by calling
```console
$ ./usertools/dpdk-devbind.py --status
```
The output will look like this (here the addresses of the PCI ports are 02:00.0 and 02:00.1, the card is an Intel X710, to be bound to the DPDK i40e driver):
```default
Other Network adapters
======================
0000:02:00.0 'Ethernet Controller X710 for 10GBASE-T 15ff' unused=i40e,vfio-pci
0000:02:00.1 'Ethernet Controller X710 for 10GBASE-T 15ff' unused=i40e,vfio-pci
```
For each port to be bound to emllDpdk, call
```console
$ ./usertools/dpdk-devbind.py --bind=uio_pci_generic
```
Example:
```console
$ ./usertools/dpdk-devbind.py --bind=uio_pci_generic 02:00.0
```
Check [https://doc.dpdk.org/guides/linux_gsg/linux_drivers.html](https://doc.dpdk.org/guides/linux_gsg/linux_drivers.html) for more information on the drivers.
## DPDK for DPAA
### Port specific numbering
The LS1046A Ethernet Port IDs within the Linux device tree (`dts`) may be non-linear, e.g. 1, 5, 6, 10, whereas the corresponding DPDK Port IDs are linear (0, 1, 2, …).
The following example demonstrates how the DPDK Port ID can be determined from the Ethernet Port ID within the Linux device tree:
| DPDK | dts |
|--------|-------|
| 0 | 1 |
| 1 | 5 |
| 2 | 6 |
| 3 | 10 |
### Reassigning Ports to DPAA and Linux in DTB/DTS
The following changes make the LS1046A ports (i.e. ports 1, 5, 6, 10) available to the emllDpdk, the Linux boot file `/boot/fsl-ls1046a-frwy-sdk.dts/dtb`.
#### NOTE
ethernet@0 (Port 1) is known to be not assignable to emllDpdk for FRWY-LS1046A.
The section dpaa-extended-args must be extended:
```dts
chosen {
stdout-path = "serial0:115200n8";
name = "chosen";
dpaa-extended-args {
fman0-extd-args {
cell-index = <0>;
compatible = "fsl,fman-extended-args";
dma-aid-mode = "port";
fman0_rx0-extd-args {
cell-index = <0>;
compatible = "fsl,fman-port-1g-rx-extended-args";
vsp-window = <8 0>;
};
fman0_tx0-extd-args {
cell-index = <0>;
compatible = "fsl,fman-port-1g-tx-extended-args";
};
fman0_rx1-extd-args {
cell-index = <1>;
compatible = "fsl,fman-port-1g-rx-extended-args";
vsp-window = <8 0>;
};
fman0_tx1-extd-args {
cell-index = <1>;
compatible = "fsl,fman-port-1g-tx-extended-args";
};
};
fman1-extd-args {
cell-index = <1>;
compatible = "fsl,fman-extended-args";
dma-aid-mode = "port";
fman1_rx0-extd-args {
cell-index = <0>;
compatible = "fsl,fman-port-1g-rx-extended-args";
vsp-window = <8 0>;
};
fman1_tx0-extd-args {
cell-index = <0>;
compatible = "fsl,fman-port-1g-tx-extended-args";
};
fman1_rx1-extd-args {
cell-index = <1>;
compatible = "fsl,fman-port-1g-rx-extended-args";
vsp-window = <8 0>;
};
fman1_tx1-extd-args {
cell-index = <1>;
compatible = "fsl,fman-port-1g-tx-extended-args";
};
};
};
};
```
Furthermore some or all ports must be assigned to DPDK instead of the native Linux driver in the section `fsl,dpaa` as follows:
```dts
fsl,dpaa {
compatible = "fsl,ls1046a\\0fsl,dpaa\\0simple-bus";
dma-coherent;
phandle = <0x85>;
/* assign Port 1 (ethernet@0) to emllDpdk (all ports assigned to emllDpdk must be contiguous at the start) */
ethernet@0 {
compatible = "fsl,dpa-ethernet-init";
fsl,fman-mac = <0x34>;
dma-coherent;
fsl,bman-buffer-pools = <0x35 0x36 0x37>;
fsl,qman-frame-queues-rx = <0x50 0x01 0x51 0x01>;
fsl,qman-frame-queues-tx = <0x70 0x01 0x71 0x01>;
};
/* port listed in BSP, but not implemented */
ethernet@1 {
compatible = "fsl,dpa-ethernet";
fsl,fman-mac = <0x38>;
dma-coherent;
status = "disabled";
};
...
/* assign Port 10 (ethernet@9) to the native Linux driver */
ethernet@9 {
compatible = "fsl,dpa-ethernet";
fsl,fman-mac = <0x3e>;
dma-coherent;
};
...
};
```
## DPDK for ENETC4
DPDK for ENETC4 on the i.MX95 SoC currently requires a specifically customized DPDK version from NXP. Therefore, a specially created version `libemllDpdkEnetc4.so` exists which is linked against NXP DPDK 22.11.
To use this version of emllDpdk, the [`EC_T_LINK_PARMS::szDriverIdent`](emll_init.html.md#_CPPv4N15EC_T_LINK_PARMS13szDriverIdentE) of [`EC_T_LINK_PARMS_DPDK::linkParms`](emlldpdk.html.md#_CPPv4N20EC_T_LINK_PARMS_DPDK9linkParmsE) must be set to `EC_LINK_PARMS_IDENT_DPDK_ENETC4`:
```cpp
EC_T_LINK_PARMS_DPDK* pLinkParmsAdapter = EC_NULL;
/* ... */
OsStrcpy(pLinkParmsAdapter->linkparms.szDriverIdent, EC_LINK_PARMS_IDENT_DPDK_ENETC4);
```
#### SEE ALSO
`CreateLinkParmsFromCmdLineDpdk()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp)
### Additional requirements
- Kernel Module `kpage_ncache.ko` [https://github.com/nxp-qoriq/dpdk-extras](https://github.com/nxp-qoriq/dpdk-extras)
- devlink tool from iproute2 [https://github.com/mikedanese/iproute2/tree/master/devlink](https://github.com/mikedanese/iproute2/tree/master/devlink)
- NXP DPDK 22.11 [https://github.com/NXP/dpdk](https://github.com/NXP/dpdk)
### Setting up the ENETC4 Ethernet interfaces
The following steps describe the creation of VF (Virtual Function) and the binding of DPDK to it.
1. Load Kernel modules
```console
$ modprobe uio_pci_generic
$ modprobe kpage_ncache
```
2. Setup hugepages
```console
$ echo 448 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
```
3. Identify the PF(Physical Function) PCI address
```console
$ dpdk-devbind.py --status
```
The devices are displayed in the output under *Network devices using kernel driver*; in this case, 0001:00:00.0 is used
```default
Network devices using kernel driver
===================================
0001:00:00.0 'Device e101' if=end0 drv=fsl_enetc4 unused=
0001:00:08.0 'Device e101' if=end1 drv=fsl_enetc4 unused= *Active*
```
4. Configure queues. Set the ring count on the PF to 1 for VF0 and VF1 and reload to apply the new configuration
```console
$ devlink dev param set pci/0001:00:00.0 name si_num_rings cmode driverinit value 0101
$ devlink dev reload pci/0001:00:00.0
```
5. Create Virtual Function VF0
```console
$ echo 1 > /sys/bus/pci/devices/0001\:00\:00.0/sriov_numvfs
```
6. Identify the VF0 PCI address
```console
$ dpdk-devbind.py --status
```
The newly created devices are displayed in the output under *Other Network devices*; in this case, 0001:00:02.0
```default
Other Network devices
=====================
0001:00:02.0 'Device ef00' unused=uio_pci_generic
0001:00:10.0 'Device e101' unused=fsl_enetc4,uio_pci_generic
```
7. Bind VF0 to DPDK
```console
$ dpdk-devbind.py -b uio_pci_generic 0001:00:02.0
```
8. Enable trust for VF0
```console
$ ip link set end0 vf 0 trust on
```
#### SEE ALSO
[NXP RM00293](https://docs.nxp.com/bundle/RM00293/page/topics/data_plane_development_kit.html)
## Limitations
If the adapter needs to be used multiple times, for cable redundancy or calling [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS) multiple times,
the application must set [`EC_T_LINK_PARMS_DPDK::bEalInitDeinitByApp`](emlldpdk.html.md#_CPPv4N20EC_T_LINK_PARMS_DPDK19bEalInitDeinitByAppE) = EC_TRUE
and call rte_eal_init() and rte_eal_cleanup() itself.
To initialize DPDK following call is needed:
```default
rte_eal_init();
```
To deinitialize DPDK following calls are needed:
```default
rte_eth_dev_close(dwPortId);
rte_eal_cleanup();
```
# emlldw3504.html.md
# Synopsys DW3504 - emllDW3504
The parameters to the Real-time Ethernet Driver Synopsys DesignWare 3504-0 Universal 10/100/1000 Ethernet MAC (DW3504) are setup-specific.
The function `CreateLinkParmsFromCmdLineDW3504()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_DW3504
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_DW3504.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRegisterBasePhys
Physical base address of register block (8k)
### [EC_T_DW3504_TYPE](emlldw3504.html.md#_CPPv416EC_T_DW3504_TYPE) eDW3504Type
System on Chip type
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY connection type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxDmaDesCnt
Transmit DMA descriptor buffer count. Must be a power of 2, maximum 256.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxDmaDesCnt
Receive DMA descriptor buffer count. Must be a power of 2, maximum 256.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseCacheSync
Default use of CacheSync EC_FALSE, don’t call CacheSync on older systems EC_TRUE
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bUsePhyLib
Use PhyLib instead of Legacy PHY handling for eDW3504_CycloneV, eDW3504_LCES1 or eDW3504_RZN1, for all others the PhyLib is mandatory
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyAccess
Don’t use MDIO to set up the PHY
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxInterrupt
Receive interrupt number (IRQ)
### enum EC_T_DW3504_TYPE
*Values:*
### enumerator eDW3504_CycloneV
MAC on Cyclone V SoC
### enumerator eDW3504_LCES1
MAC on LCES1 SoC
### enumerator eDW3504_RZN1
MAC on Renesas RZN1
### enumerator eDW3504_STM32MP15x
MAC on STM32MP15x
### enumerator eDW3504_ATOM
MAC on Atom 6000
### enumerator eDW3504_STM32MP13x
MAC on STM32MP13x
### enumerator eDW3504_RK3328
MAC on Rockchip 3328 - Rock64
### enumerator eDW3504_RK3399
MAC on Rockchip 3399 - Orange Pi 4
### enumerator eDW3504_RK3588S
MAC on Rockchip 3588s - Orange Pi 5
### enumerator eDW3504_RK3568
MAC on Rockchip 3568 - Radxa Rock3 a
### enumerator eDW3504_SemidriveD9
MAC on Semidrive D9
### enumerator eDW3504_RK3576
MAC on Rockchip 3576 - Tronlong TL-3576-EVM
### enumerator eDW3504_RK3562
MAC on Rockchip 3562 - Embedfire LubanCat3
### enumerator eDW3504_AllWinnerT536
MAC on AllWinner T536
### enumerator eDW3504_RZN2
MAC on Renesas RZN2
### enumerator eDW3504_RK3506
MAC on Rockchip 3506
### enumerator eDW3504_IQ9075
MAC on Qualcomm Dragonwing IQ-9075 EVK
### enumerator eDW3504_NvidiaJetsonAgxOrin
MAC on NVIDIA Jetson AGX Orin Dev Kit
### enumerator eDW3504_IQ8275
MAC on Qualcomm Dragonwing IQ-8275 EVK
### enumerator eDW3504_RV1126B
MAC on Rockchip RV1126B
## Supported PCI devices
Synopsis DW3504 PCI specific definitions (VendorId, DeviceId)
# emlldwxgmac.html.md
# Synopsys DWXGMAC - emllDwXgmac
The parameters to the Real-time Ethernet Driver Synopsys DesignWare Cores XGMAC - 10G/25G Ethernet MAC are setup-specific.
The function `CreateLinkParmsFromCmdLineDwXgmac()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_DWXGMAC
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_DW3504
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY address
### [EC_T_DWXGMAC_TYPE](emlldwxgmac.html.md#_CPPv417EC_T_DWXGMAC_TYPE) eDwXgmacType
System on Chip type
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY connection type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxDmaDesCnt
Transmit DMA descriptor buffer count. Must be a power of 2, maximum 256
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxDmaDesCnt
Receive DMA descriptor buffer count. Must be a power of 2, maximum 256
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyAccess
Don’t use MDIO to set up the PHY
### enum EC_T_DWXGMAC_TYPE
*Values:*
### enumerator eDwXgmac_JetsonAgxOrin
MAC on Nvidia Jetson Agx Orin
### enumerator eDwXgmac_JetsonAgxThor
MAC on Nvidia Jetson Agx Thor
# emlletsec.html.md
# Freescale TSEC / eTSEC - emllETSEC
The parameters to the Real-time Ethernet Driver ETSEC are setup-specific. The function `CreateLinkParmsFromCmdLineETSEC()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_ETSEC
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_ETSEC.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRegisterBase
Physical base address of register block (4k)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwLocalMdioBase
Physical base address of local MDIO register block (4k). For the eTSEC V1 or TSEC this is the same as dwRegisterBase, for the eTSEC V2 it’s not.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyMdioBase
Physical base address of MDIO register block (4k). This is the MDIO base of the (e)TSEC where the PHY (MII bus) is physically connected to (MII interface is shared by (e)TSEC’s).
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY address on MII bus. ETSEC_FIXED_LINK if fixed link configuration.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTbiPhyAddr
Address of internal TBI PHY. Any address from [0..31] can be used here, but the address shouldn’t collide with any external PHY connected to the external MII bus.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFixedLinkVal
Only evaluated if dwPhyAddr == FIXED_LINK. Set to one of the ETSEC_LINKFLAG_\* macros. I.e. ETSEC_LINKFLAG_1000baseT_Full.
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyStationAddress[6]
MAC address
### EC_T_VOID \*oMiiBusMtx
This mutex protects the access to the (shared) MII bus. Set to 0 if mutex shouldn’t be used. The MII bus is shared between eTSEC instances. So this mutex should be created once and assigned here for all Linklayer instances.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxInterrupt
Receive interrupt number (IRQ)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_ETSEC_TYPE](emlletsec.html.md#_CPPv415EC_T_ETSEC_TYPE) eETSECType
System on Chip type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMaster
Full control over the MAC and need to initialize MAC and the connections to the PHYs
### enum EC_T_ETSEC_TYPE
*Values:*
### enumerator eETSEC_P2020RDB
MAC on Freescale P2020
### enumerator eETSEC_TWRP1025
MAC on Freescale TWRP1025
### enumerator eETSEC_ISTMPC8548
MAC on Freescale ISTMPC8548
### enumerator eETSEC_XJ_EPU20C
MAC on Freescale XJ EPU20C
### enumerator eETSEC_TWRLS1021A
MAC on Freescale TWRLS1021A
### enumerator eETSEC_TQMLS_LS102XA
MAC on Freescale TQMLS LS102XA
## ETSEC supported MAC’s
- TSEC (not tested): Legacy hardware. Should be supported, because eTSEC is compatible to TSEC if the enhanced functionality is not used.
- eTSEC v1 (tested): This chip is used for QorIQ (i.e. P2020E) and PowerQUICC devices (i.e. MPC8548). It has 4k of IO memory.
- eETSEC v2, also called vETSEC, v read as “virtualization” (tested): This chip is used for newer QorIQ devices (i.e. P1020). It has 12k of IO memory (4k MDIO, 4k Register group0, 4k Register group1)
## Shared MII bus
The driver will access the Ethernet PHY for the following reasons:
- Check for link (or timeout), if the driver instance is opened.
- Configure MAC according to the auto-negotiated PHY speed (mandatory).
- Check link (and reconfigure MAC) during cyclic run. Therefore `EC_LINKIOCTL_UPDATE_LINKSTATUS` should not be called explicitly in parallel!
#### NOTE
The external PHYs are connected physically to the MII bus of the first eTSEC (and/or eTSEC3, depending on SoC type). From SoC reference manuals:
“14.5.3.6.6 MII Management Configuration Register (MIIMCFG)
… Note that MII management hardware is shared by all eTSECs. Thus, only through the MIIM registers of eTSEC1 can external PHYs be accessed and configured.”
That means that the acontis TSEC / eTSEC driver will also mmap the register set of the corresponding eTSEC. The following initialization parameters are used to specify the MII settings:
1. Memory map of eTSEC which will manage the MII bus (connection of external PHY’s):
```cpp
poDrvSpecificParam->dwPhyMdioBase = dwCcsrbar + 0x24000;
```
1. Dummy address assigned to internal TBI PHY. Use any address (from 0 .. 31)
which will not collide with any of the physical PHY’s addresses:
```cpp
poDrvSpecificParam->dwTbiPhyAddr = 16;
```
## Locking
The optional lock is acquired each time the MDIO register (specified by poDrvSpecificParam->dwPhyMdioBase) are accessed:
```cpp
poDrvSpecificParam->oMiiBusMtx = EC_NULL;
/* implement locking by using return value of LinkOsCreateLock(eLockType_DEFAULT); */
```
## Link check
The driver’s API function EcLinkGetStatus (pfEcLinkGetStatus) is called by the EC-Master stack. On eTSEC the link status can’t be obtained directly by reading eTSEC registers without access to the MII bus (Use mutex, poll for completion). Accessing the bus would violate timing constraints and is therefore not possible.
The following IOCTL updates the link status and accesses the PHY. The IOCTL is blocking and may therefore not be called from the JobTask’s context.
I.e. use:
```cpp
dwRes = emIoCtl(( EC_IOCTL_LINKLAYER | EC_LINKIOCTL_UPDATE_LINKSTATUS), EC_NULL);
```
EcLinkGetStatus always returns the last known link status.
## Fixed Link
PHY access can be effectively disabled entirely to avoid concurrent access if link speed and mode are defined to be fixed. This functionality is mainly provided for L2-Switch-IC’s like Vertesse VSC7385 which haven’t any PHY and are attached to the eTSEC MAC with fixed speed and mode.
The driver’s open function will not wait until the link is up on EC-Master start up. Auto-negotiation of the following PHYs is not affected by this parameter and still active. There is no forced link and no PHY access at all.
Parameters for fixed link:
```cpp
pETSECParam->dwPhyAddr = ETSEC_FIXED_LINK;
pETSECParam->dwFixedLinkVal = ETSEC_LINKFLAG_1000baseT_Full | ETSEC_LINKFLAG_LINKOK;
```
# emllfslenetc.html.md
# NXP ENETC4 - emllFslEnetc
The parameters to the Real-time Ethernet Driver NXP ENETC4 (NETC, i.MX95) are setup-specific. The function `CreateLinkParmsFromCmdLineFslEnetc()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_FSLENETC
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_FSLENETC. dwInstance selects the ENETC PF (1 = first ENETC port).
### [EC_T_FSLENETC_TYPE](emllfslenetc.html.md#_CPPv418EC_T_FSLENETC_TYPE) eFslEnetcType
System on Chip type
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY address on the central NETC EMDIO bus
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY connection type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxDmaDesCnt
Transmit DMA descriptor buffer count. Must be a multiple of 8, maximum 256
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxDmaDesCnt
Receive DMA descriptor buffer count. Must be a multiple of 8, maximum 256
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyAccess
Don’t use MDIO to set up the PHY, link is always reported as up
### enum EC_T_FSLENETC_TYPE
*Values:*
### enumerator eFslEnetc_iMX95
ENETC4 MAC on NXP i.MX95
# emllfslfec.html.md
# Freescale FslFec - emllFslFec
The parameters to the Real-time Ethernet Driver FslFec are setup-specific. The function `CreateLinkParmsFromCmdLineFslFec()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_FSLFEC
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_FSLFEC
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBuffers
Receive buffer count
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxBuffers
Transmit buffer count
### [EC_T_FEC_TYPE](emllfslfec.html.md#_CPPv413EC_T_FEC_TYPE) eFecType
System on Chip type
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY interface type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bUseDmaBuffers
Use buffers from DMA (EC_TRUE) or from heap for receive and AllocSend not supported (EC_FALSE)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY Address
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPinMuxing
No clock configuration and pin muxing
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDontReadMacAddr
Read of MAC address disabled
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxInterrupt
Receive interrupt number (IRQ)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyAccess
EC_FALSE: Link layer should initialize PHY and read link status (connected/disconnected). EC_TRUE: Client is responsible of PHY initialization and clock initialization
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFlushFramesRequired
EC_FALSE: flush cyclic / acyclic frames queued at link layer
### enum EC_T_FEC_TYPE
*Values:*
### enumerator eFEC_IMX25
MAC on Freescale i.MX25 (ARM9; ARMv5)
### enumerator eFEC_IMX28
MAC on Freescale i.MX28 (ARM9; ARMv5)
### enumerator eFEC_IMX53
MAC on Freescale i.MX53 (ARM Cortex-A8; ARMv7-a)
### enumerator eFEC_IMX6
MAC on Freescale i.MX6 (ARM Cortex-A9 Single/Dual/Quad; ARMv7-a)
### enumerator eFEC_VF6
MAC on Freescale VYBRID VF6xx (ARM Cortex-A5 + Cortex-M4)
### enumerator eFEC_IMX7
MAC on Freescale i.MX7 (ARM Cortex-A9 Single/Dual/Quad; ARMv7-a)
### enumerator eFEC_IMX8
MAC on Freescale i.MX8 (ARM Cortex-A72/A53 Single/Dual/Quad; ARMv8-a)
### enumerator eFEC_IMX8M
MAC on Freescale i.MX8M Mini/Nano/Plus (ARM Cortex-A53 Single/Dual/Quad; ARMv8-a)
### enumerator eFEC_IMXRT1064
MAC on NXP i.MX RT 1064 (ARM Cortex-M7 )
### enumerator eFEC_IMX9
MAC on NXP i.MX93 (ARM Cortex-A55/M33 Single/Dual)
### enumerator eFEC_IMX8MP
MAC on NXP i.MX8MPLUS
# emllgem.html.md
# Cadence GEM/MACB - emllGEM
The parameters to the Real-time Ethernet Driver GEM are setup-specific. The function `CreateLinkParmsFromCmdLineGEM()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_GEM
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_GEM.
### [EC_T_GEM_RXSOURCE](emllgem.html.md#_CPPv417EC_T_GEM_RXSOURCE) eRxSource
Source of RX clock, control and data signals
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxInterrupt
Receive interrupt number (IRQ)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bUseDmaBuffers
Use buffers from DMA (EC_TRUE) or from heap for receive. AllocSend is not supported when EC_FALSE.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyAccess
EC_FALSE: Link layer should initialize PHY and read link status (connected/disconnected). EC_TRUE: Client is responsible of PHY initialization and clock initialization.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bUseGmiiToRgmiiConv
Use XILINX GMIITORGMII Converter (EC_TRUE)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwConvPhyAddr
PHY address used to communicate with converter. In Linux doc it is named “reg”.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxDmaDesCnt
Transmit DMA descriptor buffer count. Must be a power of 2, maximum 256.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxDmaDesCnt
Receive DMA descriptor buffer count. Must be a power of 2, maximum 256.
### [EC_T_GEM_TYPE](emllgem.html.md#_CPPv413EC_T_GEM_TYPE) eGemType
System on Chip type
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY connection type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPinMuxing
No clock configuration and pin muxing
### EC_T_GEM_CLK_DIV_TYPE eClkDivType
Change Ref Clock settings
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseCacheSync
Default use of CacheSync EC_FALSE, don’t call CacheSync on older systems EC_TRUE
### enum EC_T_GEM_RXSOURCE
*Values:*
### enumerator eGemRxSource_MIO
MIO as source for RX clock, control and data signals
### enumerator eGemRxSource_EMIO
EMIO as source for RX clock, control and data signals
### enum EC_T_GEM_TYPE
*Values:*
### enumerator eGemType_Zynq7000
Xilinx Zynq 7000
### enumerator eGemType_ZynqUltrascale
Xilinx Zynq Ultrascale
### enumerator eGemType_BCM2712
Broadcom BCM2712, Raspberry Pi 5
### enumerator eGemType_PolarFire
Microchip PolarFire SoC
# emllhpe.html.md
# INtime HPE - emllHPE
emllHPE is part of EC-Master for INtime. emllHPE uses the INtime High-Performance Ethernet (HPE) interface.
The parameters to emllHPE are setup-specific. The function `CreateLinkParmsFromCmdLineHPE()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_HPE
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_HPE.
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_HPE_ADAPTER_NAME_SIZE]
Name of Ethernet Interface, e.g. “ie1g0”
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBufferCnt
Receive buffer count
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxBufferCnt
Transmit buffer count
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisableForceBroadcast
Don’t change target MAC address to FF:FF:FF:FF:FF:FF
# emlli8255x.html.md
# Intel Pro/100 - emllI8255x
The parameters to the Real-time Ethernet Driver Intel Pro/100 are setup-specific.
The function `CreateLinkParmsFromCmdLinei8255x()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_I8255X
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_I8255X.
```cpp
#include "EcLink.h"
EC_T_LINK_PARMS_I8255X oLinkParmsAdapter;
OsMemset(&oLinkParmsAdapter, 0, sizeof(EC_T_LINK_PARMS_I8255X));
oLinkParmsAdapter.linkParms.dwSignature = EC_LINK_PARMS_SIGNATURE_I8255X;
oLinkParmsAdapter.linkParms.dwSize = sizeof(EC_T_LINK_PARMS_I8255X);
OsStrncpy(oLinkParmsAdapter.linkParms.szDriverIdent,
EC_LINK_PARMS_IDENT_I8255X, MAX_DRIVER_IDENT_LEN - 1);
oLinkParmsAdapter.linkParms.dwInstance = 1;
oLinkParmsAdapter.linkParms.eLinkMode = EcLinkMode_POLLING;
oLinkParmsAdapter.linkParms.dwIstPriority = dwIstPriority;
```
## Supported PCI devices
Intel PRO-100 PCI specific definitions (VendorId, DeviceId)
# emllicss.html.md
# Texas Instruments ICSS - emllICSS
The parameters to the Real-time Ethernet Driver ICSS are setup-specific. The function `CreateLinkParmsFromCmdLineICSS()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_ICSS
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_ICSS.
### [EC_T_LINK_ICSS_BOARD](emllicss.html.md#_CPPv420EC_T_LINK_ICSS_BOARD) eBoardType
TI System on Chip board type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMaster
Initialize whole PRUSS subsystem, not only port. This flag is always required when the link layer is used on a single ICSS port. This flag is also required, when the link layer is used in “Redundancy mode” and two ICSS ports are used. In this case, first port should be master, and second port should be slave.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoMacAddr
EC_TRUE: No MAC address registers access
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPhyAddr
PHY address
### [EC_T_PHYINTERFACE](emll_init.html.md#_CPPv417EC_T_PHYINTERFACE) ePhyInterface
PHY connection type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyReset
No hardware reset of the PHY
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bUseAllSendQueues
Use the additional 3 queues with lower priority to send more frames per cycle
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bLegacyFirmware
For am57xx use legacy ICSS firmware from pdk_am57xx_1_0_6, instead of pdk_am57xx_1_0_17 with patch for Rx error issue, see [https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1022410/am5746-rx_error_offset-conditions/3788558#3788558](https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1022410/am5746-rx_error_offset-conditions/3788558#3788558)
### enum EC_T_LINK_ICSS_BOARD
*Values:*
### enumerator EcLinkIcssBoard_Unsupported
### enumerator EcLinkIcssBoard_am572x
TI AM572x
### enumerator EcLinkIcssBoard_am571x
TI AM571x
### enumerator EcLinkIcssBoard_am3359
TI AM3359
### enumerator EcLinkIcssBoard_am572x_emerson
TI AM572x on Emerson board
### enumerator EcLinkIcssBoard_am574x
TI AM574x
## TTS Feature
Real-time Ethernet Driver PRU ICSS can optionally use Time-Triggered Send feature [https://www.ti.com/lit/pdf/tidubz1](https://www.ti.com/lit/pdf/tidubz1)
To test it, you need to build a demo application with INCLUDE_TTS macro. Additionally, you need to set the bTts flag and configure other tts parameters in [`EC_T_LINK_PARMS_ICSS`](emllicss.html.md#_CPPv420EC_T_LINK_PARMS_ICSS) structure. Please note, we have already TTS Demo applications for some of the operating systems (for ex. Linux and TI RTOS).
dwTtsSendTimeUsec time is determined experimentally. It depends on how long your own real project prepares cyclic and acyclic frames to be sent in the current cycle.
The main purpose of the TTS feature is to reduce jitter to 40 ns (nanoseconds). To measure jitter accurately you need to have special software and hardware. For example:
- Old version of Wire Shark, ex. 1.8.4
- Dissect plugin for Wire Shark (this plugin is available only for this version of WireShark)
- ET2000 device to insert accurate timestamps with nanoseconds resolution.
Details can be found here:
[https://infosys.beckhoff.com/index.php?content=../content/1031/et2000/1309654283.html&id=](https://infosys.beckhoff.com/index.php?content=../content/1031/et2000/1309654283.html&id=)
## TI AM335x ICEV2
After the two 100 MBit ports have been deactivated, there are no longer any Ethernet ports that can be used for TCP/IP. The board cannot work in mixed mode, i.e. there is no CPSW+ICSS support. It is also necessary to configure the board to start in ICSS rather than CPSW mode. Set both jumpers on the board to ICSS mode.
#### SEE ALSO
[http://processors.wiki.ti.com/index.php/AM335x_Industrial_Communication_Engine_EVM_Rev2_1_HW_User_Guide](http://processors.wiki.ti.com/index.php/AM335x_Industrial_Communication_Engine_EVM_Rev2_1_HW_User_Guide)
## TI AM57xx IDK
After the four 100 MBit ports of the ICSS have been deactivated, the other two 1 GBit ports (CPSW) remain active and can be used for other purposes (e.g. TCP / IP).
## AM5728 IDK and AM5718 IDK boards and Technical Limitations
The main difference between these two boards is number of available ICSS ports. AM5728 IDK supports only two 100 Mbit ports: port 3 and 4. It is a technical limitation of this board. On AM5718 IDK all four 100 Mbit ports are available for EtherCAT® purposes.
#### NOTE
Real-time Ethernet Driver PRUICSS can use at most 2 ports together (in redundancy mode) and these two ports should correspond to the same PRUSS. I.e. Port 3 and 4 OR Port 1 and 2, but not Port 1 and 4, Port 1 and 3 and etc. This technical limitation exists, because PRU firmware for PRU0 and PRU1 uses the same memory areas of OCMC Memory. In the future, this limitation can be removed.
# emllicssg.html.md
# Texas Instruments ICSSG - emllICSSG on AM654x
The parameters to the ICSSG Real-time Ethernet Driver are setup-specific. The function `CreateLinkParmsFromCmdLineICSSG()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_ICSSG
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_ICSSG.
### [EC_T_LINK_ICSSG_BOARD](emllicssg.html.md#_CPPv421EC_T_LINK_ICSSG_BOARD) eBoardType
TI System on Chip board type
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMaster
Initialize whole PRUSS subsystem, not only port. This flag is always required when the link layer is used on a single ICSSG port. This flag is also required, when the link layer is used in “Redundancy mode” and two ICSSG ports are used. In this case, first port should be master, and second port should be slave.
### enum EC_T_LINK_ICSSG_BOARD
*Values:*
### enumerator EcLinkIcssgBoard_Unsupported
### enumerator EcLinkIcssgBoard_am654x
TI AM654x
## TI AM654x IDK
Support for ICSSG on AM654x is currently limited to TI AM654x IDK/EVK with TI RTOS/Sysbios in polling mode.
# emllintelgbe.html.md
# Intel Pro/1000 - emllIntelGbe
The parameters to the Real-time Ethernet Driver Intel Pro/1000 are setup-specific.
The function “CreateLinkParmsFromCmdLineIntelGbe” in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_INTELGBE
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_INTELGBE.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRxBufferCnt
Receive buffer count, 0: default to 96
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wRxBufferSize
Receive buffer size for a single Ethernet frame. 0: buffer optimized for standard Ethernet frame.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wTxBufferCnt
Transmit buffer count, 0: default to 96
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wTxBufferSize
Transmit buffer size for a single Ethernet frame. 0: buffer optimized for standard Ethernet frame.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisableLocks
Disable locks
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwAutoNegTimeout
Timeout [ms] for auto negotiation
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyCtrlOnConnect
EC_TRUE: No PHY control (e.g. PHY reset, PHY PM settings, Gbits Ctrl) on link connection detected
NICs equipped with 82577, 82579 or 82567 may need HardCodedPhySettings. This must be set after [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS), before using the NIC, e.g.:
```cpp
{
emIoCtl(dwInstanceId, EC_IOCTL_LINKLAYER_MAIN + EC_LINKIOCTL_FORCELINKMODE, EC_NULL + 0x20103, sizeof(EC_T_DWORD), EC_NULL, 0, EC_NULL);
OsSleep(1000);
}
```
## TTS Feature
The IntelGbe Real-time Ethernet Driver can optionally use Time-Triggered Send (TTS) feature. Ethernet/EtherCAT® frames are sent and time stamped according to the NIC timer instead of the CPU timer. Which is usually more accurate.
#### SEE ALSO
[`EC_T_LINKLAYER_TIMINGTASK`](emll_init.html.md#_CPPv425EC_T_LINKLAYER_TIMINGTASK), [`EC_T_LINKLAYER_TIMING`](emll_init.html.md#_CPPv421EC_T_LINKLAYER_TIMING)
## Supported PCI devices
Intel PRO-1000 PCI specific definitions (VendorId, DeviceId)
# emlllan743x.html.md
# Microchip LAN743x - emlllan743x
The parameters to the Real-time Ethernet Driver LAN743x are setup-specific.
The function `CreateLinkParmsFromCmdLineLAN743x()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_LAN743X
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_LAN743X.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBuffers
Receive buffer count. Must be a power of 2, maximum 1024.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxBuffers
Transmit buffer count. Must be a power of 2, maximum 1024.
## Supported PCI devices
Microchip LAN743x PCI specific definitions (VendorId, DeviceId)
# emllmultiplier.html.md
# Beckhoff CUxxxx Multiplier - emllMultiplier
The parameters to the Multiplier Real-time Ethernet Driver are setup-specific. The function “CreateLinkParmsFromCmdLineMultiplier” in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_MULTIPLIER
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_MULTIPLIER.
### [EC_T_MULTIPLIER_TYPE](emllmultiplier.html.md#_CPPv420EC_T_MULTIPLIER_TYPE) eMultiplierType
Type of the Multiplier Ethernet port
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPort
Used CU2508 downlink port
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) \*pHwLinkParms
Link parameters of network adapter connected to the uplink of the Multiplier
### enum EC_T_MULTIPLIER_TYPE
*Values:*
### enumerator eMultiplier_Cu2508
Beckhoff CU2508 port multiplier
### enumerator eMultiplier_Et2000
Beckhoff ET2000 industrial Ethernet multi-channel probe
## Configuration with EC-Engineer
This configuration is valid for one downlink port. For each used CUxxxx multiplier downlink port, a new configuration should be arranged.
- Start EC-Engineer in Offline Configuration modus.
- Add the CU2508 Ethernet Port as your first SubDevice.
- Append the SubDevices that you are going to connect to the port.
# emllndis.html.md
# Windows NDIS - emllNdis
As default EC-Master for Windows contains `emllNdis.dll` to use a native Windows driver for EtherCAT®.
The acontis ECAT Protocol Driver is needed to use the Ethernet Driver NDIS and can be installed from
- `Bin/Windows/x64/EcatNdisSetup-x86_64Bit.msi` or
- `Bin/Windows/x86/EcatNdisSetup-x86_32Bit.msi`
respectively depend on the Windows Operating System Type of 64 Bit or 32 Bit.
IPv4 must be installed for the network adapter as the Ethernet Driver NDIS uses the IP address to identify the network adapter.
The parameters to the Ethernet Driver NDIS are setup-specific. The function `CreateLinkParmsFromCmdLineNDIS()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Ethernet Driver instance.
### struct EC_T_LINK_PARMS_NDIS
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_NDIS.
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_NDIS_ADAPTER_NAME_SIZE]
ServiceName of network adapter, see HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\NetworkCards in registry (zero terminated)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyIpAddress[4]
IP address of network adapter
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisablePromiscuousMode
Disable adapter promiscuous mode
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisableForceBroadcast
Don’t change target MAC address to FF:FF:FF:FF:FF:FF
In case of problems while using the Ethernet Driver, it is advised to set the windows registry entry DontSetPromiscuousMode of the ECAT NDIS Protocol driver. This option is available since V3.1.3.02 of the driver.
This can be done through the following steps:
- Install ECAT NDIS Protocol driver (V3.1.3.02 or newer version)
- Open the registry editor
- Switch to Computer\\HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\Ecatndis, or just look for Ecatndis in the editor
- Create a new DWORD entry named DontSetPromiscuousMode
- Set the value of DontSetPromiscuousMode to 1
- Close the registry editor and restart your computer
# emllpcap.html.md
# Windows WinPcap - emllPcap
An Ethernet Driver based on the WinPcap library is shipped with the EC-Master. This Ethernet Driver is implemented using a network filter driver that enables the software to send and receive raw Ethernet frames. Using this Ethernet Driver any Windows standard network drivers can be used.
The Windows network adapter card has to be assigned a unique IP address (private IP address range). This IP address is used by the EtherCAT® WinPcap Ethernet Driver driver to select the appropriate adapter.
It is recommended to use a separate network adapter to connect EtherCAT® devices. If the network adapter is used for both EtherCAT® and the local area network, it may significantly impact local area network operation.
A static private IP address (e.g., 192.168.x.y) must be assigned to the EtherCAT® network adapter.
The parameters to the Ethernet Driver WinPcap are setup-specific. The function `CreateLinkParmsFromCmdLineWinPcap()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Ethernet Driver instance.
### struct EC_T_LINK_PARMS_WINPCAP
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_WINPCAP.
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyIpAddress[4]
IP address
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szAdapterId[MAX_LEN_WINPCAP_ADAPTER_ID]
Adapter ID, format: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFilterInput
Filter input if EC_TRUE. This is needed on some system if the winpcap library notify the sent frames to the network adapter.
## WinPcap, Npcap support
At least WinPcap version 4.1.2 or Npcap 0.07 r17 must be used. WinPcap version 4.1.2 is the preferred library.
The EC-Master installer installs WinPcap by default.
If using Npcap 0.07 r17, the WinPcap API-compatible mode must be chosen:
# emllr6040.html.md
# RDC R6040 - emllR6040
The parameters to the Real-time Ethernet Driver RDC R6040 are setup-specific. The function `CreateLinkParmsFromCmdLineR6040()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_R6040
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_R6040.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxDmaDesCnt
Transmit DMA descriptor buffer count. Must be a power of 2, maximum 256.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxDmaDesCnt
Receive DMA descriptor buffer count. Must be a power of 2, maximum 256.
## Supported PCI devices
RDC R6040 PCI specific definitions (VendorId, DeviceId)
# emllremote.html.md
# emllRemote
The emllRemote is used to tunnel EtherCAT® frames within a TCP socket between EC-Master and EC-Simulator.
The parameters to the Remote Driver are setup-specific. The function `CreateLinkParmsFromCmdLineRemote()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the driver instance.
### struct EC_T_LINK_PARMS_REMOTE
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_REMOTE.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSocketType
Socket type. Must be set to 1 (emrassocktype_tcp).
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abySrcIpAddress[4]
Source adapter IP address (listen)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSrcPort
Source port number (listen)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyDstIpAddress[4]
Destination adapter IP address (connect)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDstPort
Destination port number (connect)
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyMac[6]
MAC address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBufferCnt
Frame buffer count for interrupt service thread (IST)
While EC-Master listens on the given port using emllRemote, the EC-Master can connect to it using emllRemote.
EcSimulatorHilDemo command line example:
: ```console
$ EcSimulatorHilDemo -remote 1 0 0.0.0.0 10001 0.0.0.0 0 -f eni.xml
```
EcMasterDemo command line example:
: ```console
$ EcMasterDemo -remote 1 1 0.0.0.0 0 127.0.0.1 10001
```
# emllrtl8169.html.md
# Realtek RTL8169 - emllRTL8169
The parameters to the Real-time Ethernet Driver Realtek RTL8169 are setup-specific. The function `CreateLinkParmsFromCmdLineRTL8169()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_RTL8169
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_RTL8169.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bAckErrInIrq
Acknowledge errors in interrupt handler
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBuffers
Receive buffer count. Must be a power of 2, maximum 1024.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxBuffers
Transmit buffer count. Must be a power of 2, maximum 1024.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNoPhyAccess
Don’t use MDIO to set up the PHY
## RTL8169 usage under Linux
Because the Linux Kernel module de-initializes the PHY on unloading, Linux must be prevented from loading the r8169 module on startup.
## Supported PCI devices
RealTek RTL8169 PCI specific definitions (VendorId, DeviceId)
# emllrzt1.html.md
# Renesas RZ/T1 - emllRZT1
The parameters to the Real-time Ethernet Driver Renesas RZ/T1 are setup-specific.
The function `CreateLinkParmsFromCmdLineRZT1()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_RZT1
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_RZT1.
# emllsheth.html.md
# Renesas SHEth - emllSHEth
The parameters to the Renesas Real-time Ethernet Driver SuperH are setup-specific.
The function `CreateLinkParmsFromCmdLineSHEth()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_SHETH
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_SHETH.
### [EC_T_SHETH_TYPE](emllsheth.html.md#_CPPv415EC_T_SHETH_TYPE) eType
System on Chip type
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyStationAddress[6]
MAC address
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBaseAddr
Physical address of register block
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byPhyAddr
PHY address
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bNotUseDmaBuffers
EC_FALSE: Use buffers from DMA for receive (default), EC_TRUE: use buffers from heap for receive. EcLinkAllocSendFrame is not supported if bNotUseDmaBuffers = EC_TRUE.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTxDmaDesCnt
Transmit DMA descriptor buffer count. Must be a power of 2, maximum 256.
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxDmaDesCnt
Receive DMA descriptor buffer count. Must be a power of 2, maximum 256.
### enum EC_T_SHETH_TYPE
*Values:*
### enumerator eSHEth_R8A777X
Renesas R8A777X
### enumerator eSHEth_R8A779X
Renesas R8A779X
### enumerator eSHEth_SH7724
Renesas SH7724
### enumerator eSHEth_SH7757
Renesas SH7757
### enumerator eSHEth_SH7757_GIGA
Renesas SH7757_GIGA
### enumerator eSHEth_SH7734
Renesas SH7734
### enumerator eSHEth_SH7763
Renesas SH7763
### enumerator eSHEth_R8A7740
Renesas R8A7740
### enumerator eSHEth_R7S72100
Renesas R7S72100
### enumerator eSHEth_SH7619
Renesas SH7619
### enumerator eSHEth_SH771X
Renesas SH771X
### enumerator eSHEth_R8A77400
Renesas R8A77400
### enumerator eSHEth_R8A77435
Renesas R8A77435
### enumerator eSHEth_R8A77430
Renesas R8A77430
### enumerator eSHEth_R8A77450
Renesas R8A77450
### enumerator eSHEth_RX72N
Renesas RX72N
### enumerator eSHEth_RZG2L
Renesas RZG2L
## SHEth link status update
On some targets like Armadillo A800 eva the link status can’t be obtained directly by reading the MAC PHY status register without access to the MII bus. Accessing the bus would violate timing constraints and is therefore not possible.
The following IOCTL updates the link status and accesses the PHY. The IOCTL is blocking and may therefore not be called from the JobTask’s context.
```cpp
dwRes = emIoCtl((EC_IOCTL_LINKLAYER | EC_LINKIOCTL_UPDATE_LINKSTATUS), EC_NULL);
```
`ecLinkGetStatus()` always retuns the last known link status.
## SHEth usage under Linux
Due to the lacking unbind-feature of the SuperH driver, the target’s Kernel must not load the SuperH driver when starting. If the SuperH was built as a module, it can be renamed to ensure it never gets loaded. If it was compiled into the Kernel, the Kernel needs to be recompiled without it.
# emllsnarf.html.md
# VxWorks SNARF - emllSNARF
Using the EC-Master stack’s SNARF Real-time Ethernet Driver it is possible to use any of the standard network drivers shipped with VxWorks.
In VxWorks every network adapter is identified using a short string and a unit number in case of multiple identical network adapters. The unit numbers start with a value of 0.
For example the string for the Intel Pro/100 network adapter driver is “fei”. The first unit is identified using the string “fei0”:
The network adapter driver has to be loaded prior to initializing the EC-Master stack.
Using the Real-time Ethernet Driver SNARF has some disadvantages. As the VxWorks network layering is involved in this architecture, the drivers are usually not optimized for realtime behavior and the needed CPU time is often too high to reach cycle times less than 300 to 500 microseconds. Additionally there is an impact if in parallel to EtherCAT® traffic the VxWorks application needs to use a second network card for transferring TCP/IP data. The single tNetTask is shared by all network drivers.
Using a dedicated EtherCAT® driver these disadvantages can be overcome.
The parameters to the Real-time Ethernet Driver SNARF are setup-specific. The function `CreateLinkParmsFromCmdLineSNARF()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_SNARF
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_SNARF.
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_SNARF_ADAPTER_NAME_SIZE]
SNARF adapter name (zero terminated)
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBuffers
Receive buffer count, only used in RTP context, 0: default to 20
```cpp
#include "EcLink.h"
EC_T_LINK_PARMS_SNARF oLinkParmsAdapter;
OsMemset(&oLinkParmsAdapter, 0, sizeof(EC_T_LINK_PARMS_SNARF));
oLinkParmsAdapter.linkParms.dwSignature = EC_LINK_PARMS_SIGNATURE_SNARF;
oLinkParmsAdapter.linkParms.dwSize = sizeof(EC_T_LINK_PARMS_SNARF);
OsStrncpy(oLinkParmsAdapter.linkParms.szDriverIdent,
EC_LINK_PARMS_IDENT_SNARF, MAX_DRIVER_IDENT_LEN - 1);
OsStrncpy(oLinkParmsAdapter.szAdapterName, "fei0", MAX_DRIVER_IDENT_LEN - 1);
```
# emllsockraw.html.md
# Linux SockRaw - emllSockRaw
emllSockRaw is part of EC-Master for Linux. emllSockRaw uses the network interface of the native driver, e.g., eth0, eth1, etc.
The network adapter must be exclusively used for EtherCAT® and cannot be used for LAN (local area network) at the same time.
Because the native Linux driver for the network adapter type is typically not fully real-time capable, it cannot be used for real time applications. If possible, an acontis Real-time Ethernet Driver, e.g. emllIntelGbe, should be used instead.
emllSockRaw does not need the atemsys driver.
#### NOTE
Root privileges are required. A cycle time of 4 ms or higher may be needed.
To run the application without root privileges, set the Linux capability ‘cap_net_raw’ to the application.
: ```console
$ sudo setcap 'cap_net_raw+pe' ./EcMasterDemo
```
To run python scripts without root privileges, create a Python environment and set the Linux capability ‘cap_net_raw’ to the python interpreter.
: ```console
$ cd Bin/Linux
$ python3 -m venv --copies PyEnv/
$ source PyEnv/bin/activate
$ sudo setcap 'cap_net_raw+pe' PyEnv/bin/python3
```
The parameters to emllSockRaw are setup-specific. The function `CreateLinkParmsFromCmdLineSockRaw()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the parameters.
### struct EC_T_LINK_PARMS_SOCKRAW
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_SOCKRAW.
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_SOCKRAW_ADAPTER_NAME_SIZE]
Native ETH device name, e.g. “eth0” (zero terminated)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisableForceBroadcast
Don’t change target MAC address to FF:FF:FF:FF:FF:FF
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bReplacePaddingWithNopCmd
Prevent adding Ethernet padding to work-around EtherCAT corruption bugs from native Linux driver(s)
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bUsePacketMmapRx
Use PACKET_MMAP PACKET_RX_RING for receive
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSetCoalescingParms
Set Coalescing parameters to enhance the link layer performance
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bSetPromiscuousMode
Enable promiscuous mode at network adapter
# emllsockxdp.html.md
# Linux SockXdp - emllSockXdp
The Real-time Ethernet Driver SockXdp does not need the atemsys driver and uses already established Ethernet adapters, e.g. eth0, eth1, etc. It is strongly recommended to use a separate network adapter to connect EtherCAT® network adapters. If the main network adapter is used for both EtherCAT® network adapters and the local area network there may be a major impact on the local area network operation.
#### NOTE
Root privileges are required.
The parameters to the Real-time Ethernet Driver SockXdp are setup-specific. The function `CreateLinkParmsFromCmdLineSockXdp()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_SOCKXDP
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_SOCKXDP.
### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szAdapterName[EC_SOCKXDP_ADAPTER_NAME_SIZE]
Native ETH device name, e.g. “eth0” (zero terminated)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wQueueId
Used NIC Queue Id
### [EC_T_XDP_MODE](emllsockxdp.html.md#_CPPv413EC_T_XDP_MODE) eXdpMode
XDP mode
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bDisableForceBroadcast
Don’t change target MAC address to FF:FF:FF:FF:FF:FF
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bReplacePaddingWithNopCmd
Prevent adding Ethernet padding to work-around EtherCAT corruption bugs from native Linux driver(s)
### enum EC_T_XDP_MODE
*Values:*
### enumerator eXDP_SKB_MODE
Generic XDP, XDP runs in the standard network stack. This is the fallback mode if native XDP is not supported
### enumerator eXDP_DRV_MODE
Native XDP, Runs XDP directly in the NIC driver. This is the recommended mode for the best performance
### enumerator eXDP_HW_MODE
Offloaded XDP, XDP programs are offloaded to the network card itself, running on the NIC firmware, not tested
### enumerator eXDP_DRV_ZEROCOPY
Native XDP with ZEROCOPY
## Linux System Requirements
To use the XDP Real-time Ethernet Driver the following system requirements need to be met:
- Your kernel have to support XDP, check if the following entry is activated in your `.config` file.
: `CONFIG_XDP_SOCKETS=y`
If it is not activated you need to rebuild your kernel with `CONFIG_XDP_SOCKETS`.
## Getting started
- Download libxdp Version 1.4.3 from [https://github.com/xdp-project/xdp-tools](https://github.com/xdp-project/xdp-tools) and install it.
- Download libbpf Version 1.5.0 from [https://github.com/libbpf/libbpf](https://github.com/libbpf/libbpf) and install it.
- Update the linux drivers of the NIC that would be used
- If the NIC supports XDP, turn off xdp generic mode:
: ```console
$ ip link set dev eth0 xdpgeneric off
```
- If the NIC have multiple queue support, use one queue instead of multiple queues:
: ```console
$ ethtool -L eth0 combined 1
```
# emlltemac.html.md
# AMD Tri-Mode Ethernet Media Access Controller (TEMAC)
The parameters to the TEMAC Real-time Ethernet Driver are setup-specific. The function `CreateLinkParmsFromCmdLineTemac()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_TEMAC
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_TEMAC
### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRxBufferCnt
Receive buffer count, 0: default to 100
## Encustra Mercury_XU5_PE1
Support for FPGA designs with TEMAC with XAE_SOFT_TEMAC_LOW_SPEED and XPAR_AXI_FIFO.
# emlltienetcpswg.html.md
# Texas Instruments CPSWG for AM6x and Jacinto 7 based on Enet LLD - emllTiEnetCpswg
The parameters to the TiEnetCpswg Real-time Ethernet Driver are setup-specific. The function `CreateLinkParmsFromCmdLineTiEnetCpswg()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_TIENETCPSWG
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_TIENETCPSWG.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMaster
EC_TRUE: Initialize MAC
## TI J784S4X EVM
Support for TiEnetCpswg on J784s4 is currently limited to TI J784S4X EVM with FreeRTOS in polling mode.
It’s working with ti-processor-sdk-rtos-j784s4-evm-08_06_01_03.
# emlltieneticssg.html.md
# Texas Instruments ICSSG for AM6x and Jacinto 7 based on Enet LLD - emllTiEnetIcssg
The parameters to the Real-time Ethernet Driver TiEnetIcssg are setup-specific. The function `CreateLinkParmsFromCmdLineTiEnetIcssg()` in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_TIENETICSSG
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_TIENETICSSG.
### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bMaster
EC_TRUE: Initialize MAC
### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byPhyAddr
PHY address
### EC_T_TIENETICSSG_TYPE eTiEnetIcssgType
SoC/board variant (selects ICSSG vs ICSSM behavior / defaults)
## TI AM64x EVM
Working with MCU Plus SDK AM64x 08.01.00.36 and MCU Plus SDK AM64x 11.00.00.15
## TI AM243x LP and TI AM243x EVM
Working with MCU Plus SDK AM243x 08.01.00.36 and MCU Plus SDK AM243x 11.00.00.15
## TI AM263x
Working with MCU Plus SDK AM263x 11.00.00.19
# emllvlan.html.md
# Virtual Local Area Network - emllVlan
The parameters to the VLAN Real-time Ethernet Driver are setup-specific. The function “CreateLinkParmsFromCmdLineVlan” in [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) demonstrates how to initialize the Real-time Ethernet Driver instance.
### struct EC_T_LINK_PARMS_VLAN
### Public Members
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) linkParms
Common link parameters. Signature must be set to EC_LINK_PARMS_SIGNATURE_MULTIPLIER.
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wVlanId
VLAN Identifier (VID)
### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wVlanPrio
VLAN Priority code point (PCP)
### [EC_T_LINK_PARMS](emll_init.html.md#_CPPv415EC_T_LINK_PARMS) \*pHwLinkParms
Link parameters of network adapter connected to the uplink of the Multiplier
### EC_T_VLAN_MODE eVlanMode
Vlan switch operation mode
## Switch Configuration
Ensure that the Spanning Tree Protocol (STP) is disabled on the ports used for EtherCAT, because it can lead to permanent frame loss.
# error-codes.html.md
# Error Codes
### Groups
| **No.** | **Group** | **Abbr.** | **Description** |
|-----------|--------------------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Application Error | APP | Error within application, running the MainDevice
E.g. API function call with invalid parameters |
| 2 | EtherCAT® network information file problem | ENI | MainDevice configuration XML file mismatches SubDevice configuration on bus
E.g. Bus Topology Scan cannot detect all SubDevices configured within network information file |
| 3 | MainDevice parameter configuration | CFG | MainDevice configuration parameters erroneous
E.g. mailbox command queue not large enough |
| 4 | Bus/SubDevice Error | SLV | SubDevice error
E.g. Intel Pro/1000 NIC could not be found |
| 6 | Remote API | RAS | Remote API error
E.g. connection to Remote API server is not possible from client |
| 7 | Internal software error | ISW | MainDevice internal error
E.g. MainDevice state machine in undefined state |
| 8 | DC MainDevice Sync | DCM | DC SubDevice and host time synchronization |
| 9 | Pass-Through-Server | PTS | Initialization/De-Initialization errors |
| 10 | System Setup | SYS | Errors from Operating System or obviously due to System Setup |
# error-codes_aoe.html.md
# ADS over EtherCAT® (AoE) Error Codes
### EC_E_AOE_NO_RTIME
0x9813000D: AoE: No Rtime
### EC_E_AOE_LOCKED_MEMORY
0x9813000E: AoE: Allocation locked memory
### EC_E_AOE_MAILBOX
0x9813000F: AoE: Insert mailbox error
### EC_E_AOE_WRONG_HMSG
0x98130010: AoE: Wrong receive HMSG
### EC_E_AOE_BAD_TASK_ID
0x98130011: AoE: Bad task ID
### EC_E_AOE_NO_IO
0x98130012: AoE: No IO
### EC_E_AOE_UNKNOWN_AMS_COMMAND
0x98130013: AoE: Unknown ADS command
### EC_E_AOE_WIN32
0x98130014: AoE: Win 32 error
### EC_E_AOE_LOW_INSTALL_LEVEL
0x98130015: AoE: Low installation level
### EC_E_AOE_NO_DEBUG
0x98130016: AoE: No debug available
### EC_E_AOE_AMS_SYNC_WIN32
0x98130017: AoE: Sync Win 32 error
### EC_E_AOE_AMS_SYNC_TIMEOUT
0x98130018: AoE: Sync Timeout
### EC_E_AOE_AMS_SYNC_AMS
0x98130019: AoE: Sync AMS error
### EC_E_AOE_AMS_SYNC_NO_INDEX_MAP
0x9813001A: AoE: Sync no index map
### EC_E_AOE_TCP_SEND
0x9813001B: AoE: TCP send error
### EC_E_AOE_HOST_UNREACHABLE
0x9813001C: AoE: Host unreachable
### EC_E_AOE_INVALIDAMSFRAGMENT
0x9813001D: AoE: Invalid AMS fragment
### EC_E_AOE_NO_LOCKED_MEMORY
0x9813001E: AoE: No allocation locked memory
### EC_E_AOE_MAILBOX_FULL
0x9813001F: AoE: Mailbox full
\\newpage
# error-codes_coe.html.md
# CAN application protocol over EtherCAT® (CoE) SDO Error Codes
### EC_E_SDO_ABORTCODE_TOGGLE
0x98110040: SLV: SDO: Toggle bit not alternated (CoE abort code 0x05030000 of slave)
### EC_E_SDO_ABORTCODE_TIMEOUT
0x98110041: SLV: SDO: Protocol timed out (CoE abort code 0x05040000 of slave)
### EC_E_SDO_ABORTCODE_CCS_SCS
0x98110042: SLV: SDO: Client/server command specifier not valid or unknown (CoE abort code 0x05040001 of slave)
### EC_E_SDO_ABORTCODE_BLK_SIZE
0x98110043: SLV: SDO: Invalid block size (block mode only) (CoE abort code 0x05040002 of slave)
### EC_E_SDO_ABORTCODE_SEQNO
0x98110044: SLV: SDO: Invalid sequence number (block mode only) (CoE abort code 0x05040003 of slave)
### EC_E_SDO_ABORTCODE_CRC
0x98110045: SLV: SDO: CRC error (block mode only) (CoE abort code 0x05040004 of slave)
### EC_E_SDO_ABORTCODE_MEMORY
0x98110046: SLV: SDO: Out of memory (CoE abort code 0x05040005 of slave)
### EC_E_SDO_ABORTCODE_ACCESS
0x98110047: SLV: SDO: Unsupported access to an object (CoE abort code 0x06010000 of slave)
### EC_E_SDO_ABORTCODE_WRITEONLY
0x98110048: SLV: SDO: Attempt to read a write only object (CoE abort code 0x06010001 of slave)
### EC_E_SDO_ABORTCODE_READONLY
0x98110049: SLV: SDO: Attempt to write a read only object (CoE abort code 0x06010002 of slave)
### EC_E_SDO_ABORTCODE_INDEX
0x9811004A: SLV: SDO: Object does not exist in the object dictionary (CoE abort code 0x06020000 of slave)
### EC_E_SDO_ABORTCODE_PDO_MAP
0x9811004B: SLV: SDO: Object cannot be mapped to the PDO (CoE abort code 0x06040041 of slave)
### EC_E_SDO_ABORTCODE_PDO_LEN
0x9811004C: SLV: SDO: The number and length of the objects to be mapped would exceed PDO length (CoE abort code 0x06040042 of slave)
### EC_E_SDO_ABORTCODE_P_INCOMP
0x9811004D: SLV: SDO: General parameter incompatibility reason (CoE abort code 0x06040043 of slave)
### EC_E_SDO_ABORTCODE_I_INCOMP
0x9811004E: SLV: SDO: General internal incompatibility in the device (CoE abort code 0x06040047 of slave)
### EC_E_SDO_ABORTCODE_HARDWARE
0x9811004F: SLV: SDO: Access failed due to a hardware error (CoE abort code 0x06060000 of slave)
### EC_E_SDO_ABORTCODE_DATA_LENGTH_NOT_MATCH
0x98110050: SLV: SDO: Data type does not match, length of service parameter does not match (CoE abort code 0x06070010 of slave)
### EC_E_SDO_ABORTCODE_DATA_LENGTH_TOO_HIGH
0x98110051: SLV: SDO: Data type does not match, length of service parameter too high (CoE abort code 0x06070012 of slave)
### EC_E_SDO_ABORTCODE_DATA_LENGTH_TOO_LOW
0x98110052: SLV: SDO: Data type does not match, length of service parameter too low (CoE abort code 0x06070013 of slave)
### EC_E_SDO_ABORTCODE_OFFSET
0x98110053: SLV: SDO: Sub-index does not exist (CoE abort code 0x06090011 of slave)
### EC_E_SDO_ABORTCODE_VALUE_RANGE
0x98110054: SLV: SDO: Value range of parameter exceeded (only for write access) (CoE abort code 0x06090030 of slave)
### EC_E_SDO_ABORTCODE_VALUE_TOO_HIGH
0x98110055: SLV: SDO: Value of parameter written too high (CoE abort code 0x06090031 of slave)
### EC_E_SDO_ABORTCODE_VALUE_TOO_LOW
0x98110056: SLV: SDO: Value of parameter written too low (CoE abort code 0x06090032 of slave)
### EC_E_SDO_ABORTCODE_MINMAX
0x98110057: SLV: SDO: Maximum value is less than minimum value (CoE abort code 0x06090036 of slave)
### EC_E_SDO_ABORTCODE_GENERAL
0x98110058: SLV: SDO: General error (CoE abort code 0x08000000 of slave)
### EC_E_SDO_ABORTCODE_TRANSFER
0x98110059: SLV: SDO: Data cannot be transferred or stored to the application (CoE abort code 0x08000020 of slave)
### EC_E_SDO_ABORTCODE_TRANSFER_LOCAL_CONTROL
0x9811005A: SLV: SDO: Data cannot be transferred or stored to the application because of local control (CoE abort code 0x08000021 of slave)
### EC_E_SDO_ABORTCODE_TRANSFER_DEVICE_STATE
0x9811005B: SLV: SDO: Data cannot be transferred or stored to the application because of the present device state (CoE abort code 0x08000022 of slave)
### EC_E_SDO_ABORTCODE_DICTIONARY
0x9811005C: SLV: SDO: Object dictionary dynamic generation fails or no object dictionary is present (e.g. object dictionary is generated from file and generation fails because of an file error) (CoE abort code 0x08000023 of slave)
### EC_E_SDO_ABORTCODE_UNKNOWN
0x9811005D: SLV: SDO: Unknown code (Unknown CoE abort code of slave)
### EC_E_SDO_ABORTCODE_MODULE_ID_LIST_NOT_MATCH
0x9811005E: Detected Module Ident List (0xF030) and Configured Module Ident list (0xF050) does not match
### EC_E_SDO_ABORTCODE_SI_NOT_WRITTEN
0x98130004: SLV: SDO: Sub Index cannot be written, SI0 must be 0 for write access (CoE abort code 0x06010003 of slave)
### EC_E_SDO_ABORTCODE_CA_TYPE_MISM
0x98130005: SLV: SDO: Complete access not supported for objects of variable length such as ENUM object types (CoE abort code 0x06010004 of slave)
### EC_E_SDO_ABORTCODE_OBJ_TOO_BIG
0x98130006: SLV: SDO: Object length exceeds mailbox size (CoE abort code 0x06010005 of slave)
### EC_E_SDO_ABORTCODE_PDO_MAPPED
0x98130007: SLV: SDO: Object mapped to RxPDO, SDO Download blocked (CoE abort code 0x06010006 of slave)
\\newpage
# error-codes_dcm.html.md
# DCM Error Codes
### DCM_E_ERROR
0x981201C0: Unspecific DCM Error
### DCM_E_NOTINITIALIZED
0x981201C1: Not initialized
### DCM_E_MAX_CTL_ERROR_EXCEED
0x981201C2: DCM controller - synchronization out of limit
### DCM_E_NOMEMORY
0x981201C3: Not enough memory
### DCM_E_INVALID_HWLAYER
0x981201C4: Hardware layer - (BSP) invalid
### DCM_E_TIMER_MODIFY_ERROR
0x981201C5: Hardware layer - error modifying timer
### DCM_E_TIMER_NOT_RUNNING
0x981201C6: Hardware layer - timer not running
### DCM_E_WRONG_CPU
0x981201C7: Hardware layer - function called on wrong CPU
### DCM_E_INVALID_SYNC_PERIOD
0x981201C8: Invalid DC sync period length (invalid clock master?)
### DCM_E_INVALID_SETVAL
0x981201C9: DCM controller SetVal too small
### DCM_E_DRIFT_TO_HIGH
0x981201CA: DCM controller - Drift between local timer and ref clock to high
### DCM_E_BUS_CYCLE_WRONG
0x981201CB: DCM controller - Bus cycle time (dwBusCycleTimeUsec) doesn’t match real cycle
### DCX_E_NO_EXT_CLOCK
0x981201CC: DCX controller - No external synchronization clock found
### DCM_E_INVALID_DATA
0x981201CD: DCM controller - Invalid data
\\newpage
# error-codes_foe.html.md
# File Transfer over EtherCAT® (FoE) Error Codes
### EC_E_FOE_ERRCODE_NOTDEFINED
0x98110060: SLV: ERROR FoE: not defined (FoE Error Code 0 (0x8000) of slave)
### EC_E_FOE_ERRCODE_NOTFOUND
0x98110061: SLV: ERROR FoE: not found (FoE Error Code 1 (0x8001) of slave)
### EC_E_FOE_ERRCODE_ACCESS
0x98110062: SLV: ERROR FoE: access denied (FoE Error Code 2 (0x8002) of slave)
### EC_E_FOE_ERRCODE_DISKFULL
0x98110063: SLV: ERROR FoE: disk full (FoE Error Code 3 (0x8003) of slave)
### EC_E_FOE_ERRCODE_ILLEGAL
0x98110064: SLV: ERROR FoE: illegal (FoE Error Code 4 (0x8004) of slave)
### EC_E_FOE_ERRCODE_PACKENO
0x98110065: SLV: ERROR FoE: packet number wrong (FoE Error Code 5 (0x8005) of slave)
### EC_E_FOE_ERRCODE_EXISTS
0x98110066: SLV: ERROR FoE: already exists (FoE Error Code 6 (0x8006) of slave)
### EC_E_FOE_ERRCODE_NOUSER
0x98110067: SLV: ERROR FoE: no user (FoE Error Code 7 (0x8007) of slave)
### EC_E_FOE_ERRCODE_BOOTSTRAPONLY
0x98110068: SLV: ERROR FoE: bootstrap only (FoE Error Code 8 (0x8008) of slave)
### EC_E_FOE_ERRCODE_NOTINBOOTSTRAP
0x98110069: SLV: ERROR FoE: Downloaded file name is not valid in Bootstrap state (FoE Error Code 9 (0x8009) of slave)
### EC_E_FOE_ERRCODE_INVALIDPASSWORD
0x9811006A: SLV: ERROR FoE: no rights (FoE Error Code 10 (0x800A) of slave)
### EC_E_FOE_ERRCODE_PROGERROR
0x9811006B: SLV: ERROR FoE: program error (FoE Error Code 11 (0x800B) of slave)
### EC_E_FOE_ERRCODE_INVALID_CHECKSUM
0x9811006C: FoE: Wrong checksum
### EC_E_FOE_ERRCODE_INVALID_FIRMWARE
0x9811006D: SLV: ERROR FoE: Firmware does not fit for Hardware (FoE Error Code 13 (0x800D) of slave)
### EC_E_FOE_ERRCODE_NO_FILE
0x9811006F: SLV: ERROR FoE: No file to read (FoE Error Code 15 (0x800F) of slave)
### EC_E_NO_FOE_SUPPORT_BS
0x9811010F: APP: ERROR FoE: Protocol not supported in boot strap (e.g. Application requested FoE in Bootstrap although slave does not support this)
### EC_E_FOE_ERRCODE_MAX_FILE_SIZE
0x9811017A: APP: ERROR FoE: File is bigger than max file size (e.g. Slave returned more data than the buffer provided by application can store.)
### EC_E_FOE_ERRCODE_FILE_HEAD_MISSING
0x98130001: SLV: ERROR FoE: File header does not exist (FoE Error Code 16 (0x8010) of slave)
### EC_E_FOE_ERRCODE_FLASH_PROBLEM
0x98130002: SLV: ERROR FoE: Flash problem (FoE Error Code 17 (0x8011) of slave)
### EC_E_FOE_ERRCODE_FILE_INCOMPATIBLE
0x98130003: SLV: ERROR FoE: File incompatible (FoE Error Code 18 (0x8012) of slave)
\\newpage
# error-codes_generic.html.md
# Generic Error Codes
### EC_E_NOERROR
0x00000000: No Error
### EC_E_ERROR
0x98110000: Unspecific Error
### EMRAS_E_ERROR
0x98110180: Unspecific RAS Error
### EC_E_NOTSUPPORTED
0x98110001: APP: Feature not supported (e.g. function or property not available)
### EC_E_INVALIDINDEX
0x98110002: APP: Invalid index (e.g. CoE: invalid SDO index)
### EC_E_INVALIDOFFSET
0x98110003: ISW: Invalid offset (e.g. invalid offset while accessing Process Data Image)
### EC_E_CANCEL
0x98110004: APP: Cancel (e.g. EtherCAT stack should abort current mailbox transfer)
### EC_E_INVALIDSIZE
0x98110005: APP: Invalid size
### EC_E_INVALIDDATA
0x98110006: ISW: Invalid data (multiple error sources)
### EC_E_NOTREADY
0x98110007: ISW: Not ready (multiple error sources)
### EC_E_BUSY
0x98110008: APP: Busy (e.g. EtherCAT stack is currently busy and not available to process the API request. The function may be called again later)
### EC_E_ACYC_FRM_FREEQ_EMPTY
0x98110009: ISW: Cannot queue acyclic EtherCAT command (Acyclic command queue is full. Possible solution: Increase of configuration value dwMaxQueuedEthFrames)
### EC_E_NOMEMORY
0x9811000A: CFG: No memory left (e.g. memory full / fragmented))
### EC_E_INVALIDPARM
0x9811000B: APP: Invalid parameter (e.g. API function called with erroneous parameter set)
### EC_E_NOTFOUND
0x9811000C: APP: Not found (e.g. Network Information File ENI not found or API called with invalid slave ID)
### EC_E_DUPLICATE
0x9811000D: ISW: Duplicated fixed address detected (handled internally)
### EC_E_INVALIDSTATE
0x9811000E: ISW: Invalid state (EtherCAT stack not initialized or not configured)
### EC_E_TIMER_LIST_FULL
0x9811000F: ISW: Cannot add slave to timer list (slave timer list full)
### EC_E_TIMEOUT
0x98110010: Timeout
### EC_E_OPENFAILED
0x98110011: ISW: Open failed
### EC_E_SENDFAILED
0x98110012: LLA: Frame send failed
### EC_E_INSERTMAILBOX
0x98110013: CFG: Insert Mailbox error (internal limit MAX_QUEUED_COE_CMDS: 20)
### EC_E_INVALIDCMD
0x98110014: ISW: Invalid Command (Unknown mailbox command code)
### EC_E_UNKNOWN_MBX_PROTOCOL
0x98110015: ISW: Unknown Mailbox Protocol Command (Unknown Mailbox protocol or mailbox command with unknown protocol association)
### EC_E_ACCESSDENIED
0x98110016: ISW: Access Denied (e.g. master internal software error)
### EC_E_IDENTIFICATIONFAILED
0x98110017: ENI: Identification failed (e.g. identification command failed)
### EC_E_LOCK_CREATE_FAILED
0x98110018: SYS: Create lock failed (e.g. OsCreateLockTyped failed)
### EC_E_VERSION_MISMATCH
0x98110019: APP: Version mismatch for loaded library
### EC_E_PRODKEY_INVALID
0x9811001A: CFG: Product Key Invalid (e.g. application using protected version of the stack, which stops operation after the evaluation time limit reached if a license is not provided)
### EC_E_WRONG_FORMAT
0x9811001B: ENI: Wrong configuration format (e.g. Network information file empty or malformed), SLV: Malformed EEPROM content
### EC_E_FEATURE_DISABLED
0x9811001C: APP: Feature disabled (e.g. Application tried to perform a missing or disabled API function)
### EC_E_SHADOW_MEMORY
0x9811001D: Shadow memory requested in wrong mode
### EC_E_BUSCONFIG_MISMATCH
0x9811001E: ENI: Bus configuration mismatch (e.g. Network information file and currently connected bus topology does not match)
### EC_E_CONFIGDATAREAD
0x9811001F: ENI: Error reading configuration file (e.g. Network information file could not be read)
### EC_E_ENI_NO_SAFEOP_OP_SUPPORT
0x98110020: Configuration doesn’t support SAFEOP and OP requested state
### EC_E_XML_CYCCMDS_MISSING
0x98110021: ENI: Cyclic commands are missing (e.g. Network information file does not contain cyclic commands)
### EC_E_XML_ALSTATUS_READ_MISSING
0x98110022: ENI: AL_STATUS register read missing in XML file for at least one state (e.g. Read of AL Status register is missing in cyclic part of given network information file)
### EC_E_MCSM_FATAL_ERROR
0x98110023: ISW: Fatal internal McSm (master control state machine is in an undefined state)
### EC_E_SLAVE_ERROR
0x98110024: SLV: Slave error (e.g. A slave error was detected. See also EC_NOTIFY_STATUS_SLAVE_ERROR and EC_NOTIFY_SLAVE_ERROR_STATUS_INFO)
### EC_E_FRAME_LOST
0x98110025: SLV: Frame lost, IDX mismatch (EtherCAT [frame(s)](api_general_functions.html.md#d3/d63/group___e_c___l_o_g___l_e_v_e_l_s_1ga85d15f307312582e5c0a12f1c39a2d0d) lost on bus, means the response was not received. In case this error shows frequently a problem with the wiring could be the cause)
### EC_E_CMD_MISSING
0x98110026: SLV: At least one EtherCAT command is missing in the received frame (e.g. received EtherCAT frame incomplete)
### EC_E_CYCCMD_WKC_ERROR
0x98110027: Cyclic command WKC error
### EC_E_INVALID_DCL_MODE
0x98110028: APP: IOCTL EC_IOCTL_DC_LATCH_REQ_LTIMVALS invalid in DCL auto read mode (this function cannot be used if DC Latching is running in mode “Auto Read”)
### EC_E_AI_ADDRESS
0x98110029: SLV: Auto increment address increment mismatch (e.g. Network information file and bus topology doesn’t match any more. Error shows only, if an already recognized slave isn’t present any more)
### EC_E_INVALID_SLAVE_STATE
0x9811002A: APP: Slave in invalid state, e.g. not in OP (API not callable in this state) (mailbox commands are not allowed in current slave state)
### EC_E_SLAVE_NOT_ADDRESSABLE
0x9811002B: SLV: Station address lost (or slave missing) - FPRD to AL_STATUS failed (e.g. Slave had a power cycle)
### EC_E_CYC_CMDS_OVERFLOW
0x9811002C: ENI: Too many cyclic commands in XML configuration file (e.g. [EC_T_INIT_MASTER_PARMS.dwMaxAcycFramesQueued](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_1ae90efbf60aa12acbd95ab39a3f0b10a0) too small)
### EC_E_LINK_DISCONNECTED
0x9811002D: SLV: Ethernet link cable disconnected (e.g. EtherCAT bus segment not connected to network interface)
### EC_E_MASTERCORE_INACCESSIBLE
0x9811002E: RAS: Master core not accessible (e.g. Connection to remote server was terminated or master instance has been stopped on remote side)
### EC_E_COE_MBXSND_WKC_ERROR
0x9811002F: SLV: CoE mailbox send: working counter (e.g. CoE mailbox couldn’t be read on slave, slave didn’t read out mailbox since last write)
### EC_E_COE_MBXRCV_WKC_ERROR
0x98110030: SLV: CoE mailbox receive: working counter (e.g. CoE mailbox couldn’t be read from slave)
### EC_E_NO_MBX_SUPPORT
0x98110031: APP: No mailbox support (e.g. Slave does not support mailbox access)
### EC_E_NO_COE_SUPPORT
0x98110032: ENI: CoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware)
### EC_E_NO_EOE_SUPPORT
0x98110033: ENI: EoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware)
### EC_E_NO_FOE_SUPPORT
0x98110034: ENI: FoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware)
### EC_E_NO_SOE_SUPPORT
0x98110035: ENI: SoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware)
### EC_E_NO_VOE_SUPPORT
0x98110036: ENI: VoE protocol not supported (e.g. Configuration error or slave information file doesn’t match slave firmware)
### EC_E_EVAL_VIOLATION
0x98110037: ENI: Configuration violates Evaluation limits (obsolete)
### EC_E_EVAL_EXPIRED
0x98110038: CFG: Evaluation Time limit reached (e.g. License not provided and evaluation period (1 hour) of protected version exceeded)
### EC_E_LICENSE_MISSING
0x98110039: License key invalid or missing
### EC_E_CFGFILENOTFOUND
0x98110070: CFG: Network configuration file not found (e.g. path to configuration file (XML) was wrong or the file is not available)
### EC_E_EEPROMREADERROR
0x98110071: SLV: Command error while EEPROM upload (read slave EEPROM)
### EC_E_EEPROMWRITEERROR
0x98110072: SLV: Command error while EEPROM download (write slave EEPROM)
### EC_E_XML_CYCCMDS_SIZEMISMATCH
0x98110073: ENI: Cyclic command wrong size (too long) (size in network configuration file (XML) does not match size of process data)
### EC_E_XML_INVALID_INP_OFF
0x98110074: ENI: Invalid input offset in cyclic command, please check InputOffs
### EC_E_XML_INVALID_OUT_OFF
0x98110075: ENI: Invalid output offset in cyclic command, please check OutputOffs
### EC_E_PORTCLOSE
0x98110076: Port close failed
### EC_E_PORTOPEN
0x98110077: Port open failed
### EC_E_SLAVE_NOT_PRESENT
0x9811010E: APP / SLV: command not executed (slave not present on bus) (e.g. slave disappeared or was never present)
### EC_E_EEPROMRELOADERROR
0x98110110: Command error while EEPROM reload
### EC_E_SLAVECTRLRESETERROR
0x98110111: Command error while Reset Slave Controller
### EC_E_SYSDRIVERMISSING
0x98110112: SYS: Cannot open system driver (e.g. system driver was not loaded)
### EC_E_BUSCONFIG_TOPOCHANGE
0x9811011E: Bus configuration not detected, Topology changed (e.g. Topology changed while scanning bus)
### EC_E_EOE_MBX_WKC_ERROR
0x9811011F: EoE: Mailbox receive: working counter
### EC_E_FOE_MBX_WKC_ERROR
0x98110120: FoE: Mailbox receive: working counter
### EC_E_SOE_MBX_WKC_ERROR
0x98110121: SoE: mailbox receive: working counter
### EC_E_AOE_MBX_WKC_ERROR
0x98110122: AoE: Mailbox receive: working counter
### EC_E_VOE_MBX_WKC_ERROR
0x98110123: SLV: VoE mailbox send: working counter (VoE mailbox couldn’t be written)
### EC_E_EEPROMASSIGNERROR
0x98110124: SLV: EEPROM assignment failed
### EC_E_MBX_ERROR_TYPE
0x98110125: SLV: Unknown mailbox error code received in mailbox
### EC_E_REDLINEBREAK
0x98110126: SLV: Redundancy line break (e.g. cable break between slaves or between EtherCAT network adapter and first slave)
### EC_E_XML_INVALID_CMD_WITH_RED
0x98110127: ENI: Invalid EtherCAT command in cyclic frame with redundancy (e.g. BRW commands are not allowed with redundancy)
### EC_E_XML_PREV_PORT_MISSING
0x98110128: ENI: -tag is missing (e.g. if the auto increment address is not the first slave on the bus we check if a previous port tag OR a hot connect tag is available)
### EC_E_XML_DC_CYCCMDS_MISSING
0x98110129: DC enabled and DC cyclic commands missing (e.g. access to 0x0900)
### EC_E_DLSTATUS_IRQ_TOPOCHANGED
0x98110130: SLV: Data link (DL) status interrupt because of changed topology (automatically handled by master)
### EC_E_PTS_IS_NOT_RUNNING
0x98110131: PTS: Pass Through Server is not running (Pass-Through-Server was tried to be enabled/disabled or stopped without being started)
### EC_E_PTS_IS_RUNNING
0x98110132: PTS: Pass Through Server is running (obsolete, replaced by EC_E_ADS_IS_RUNNING)
### EC_E_ADS_IS_RUNNING
0x98110132: PTS: ADS adapter (Pass Through Server) is running (API call conflicts with ADS state (running))
### EC_E_PTS_THREAD_CREATE_FAILED
0x98110133: PTS: Could not start the Pass Through Server
### EC_E_PTS_SOCK_BIND_FAILED
0x98110134: PTS: The Pass Through Server could not bind the IP address with a socket (e.g. Possibly because the IPaddress (and Port) is already in use or the IP-address does not exist)
### EC_E_PTS_NOT_ENABLED
0x98110135: PTS: The Pass Through Server is running but not enabled
### EC_E_PTS_LL_MODE_NOT_SUPPORTED
0x98110136: PTS: The Link Layer mode is not supported by the Pass Through Server (e.g. The Master is running in interrupt mode but the Pass-Through-Server only supports polling mode)
### EC_E_VOE_NO_MBX_RECEIVED
0x98110137: SLV: No VoE mailbox received yet from specific slave
### EC_E_DC_REF_CLOCK_SYNC_OUT_UNIT_DISABLED
0x98110138: DC (time loop control) unit of reference clock disabled
### EC_E_DC_REF_CLOCK_NOT_FOUND
0x98110139: SLV: Reference clock not found! May happen if reference clock is removed from network.
### EC_E_MBX_CMD_WKC_ERROR
0x9811013B: SLV: Mailbox command working counter error (e.g. Mailbox init command Retry Count exceeded)
### EC_E_NO_AOE_SUPPORT
0x9811013C: APP / SLV: AoE: Protocol not supported (e.g. Application calls AoE-API although not implemented at slave)
### EC_E_AOE_INV_RESPONSE_SIZE
0x9811013D: AoE: Invalid AoE response received
### EC_E_AOE_ERROR
0x9811013E: AoE: Common AoE device error
### EC_E_AOE_SRVNOTSUPP
0x9811013F: AoE: Service not supported by server
### EC_E_AOE_INVALIDGRP
0x98110140: AoE: Invalid index group
### EC_E_AOE_INVALIDOFFSET
0x98110141: AoE: Invalid index offset
### EC_E_AOE_INVALIDACCESS
0x98110142: AoE: Reading/writing not permitted
### EC_E_AOE_INVALIDSIZE
0x98110143: AoE: Parameter size not correct
### EC_E_AOE_INVALIDDATA
0x98110144: AoE: Invalid parameter [value(s)](api_general_functions.html.md#d3/d63/group___e_c___l_o_g___l_e_v_e_l_s_1ga85d15f307312582e5c0a12f1c39a2d0d)
### EC_E_AOE_NOTREADY
0x98110145: AoE: Device not in a ready state
### EC_E_AOE_BUSY
0x98110146: AoE: Device busy
### EC_E_AOE_INVALIDCONTEXT
0x98110147: AoE: Invalid context
### EC_E_AOE_NOMEMORY
0x98110148: AoE: Out of memory
### EC_E_AOE_INVALIDPARM
0x98110149: AoE: Invalid parameter [value(s)](api_general_functions.html.md#d3/d63/group___e_c___l_o_g___l_e_v_e_l_s_1ga85d15f307312582e5c0a12f1c39a2d0d)
### EC_E_AOE_NOTFOUND
0x9811014A: AoE: Not found
### EC_E_AOE_SYNTAX
0x9811014B: AoE: Syntax error in command or file
### EC_E_AOE_INCOMPATIBLE
0x9811014C: AoE: Objects do not match
### EC_E_AOE_EXISTS
0x9811014D: AoE: Object already exists
### EC_E_AOE_SYMBOLNOTFOUND
0x9811014E: AoE: Symbol not found
### EC_E_AOE_SYMBOLVERSIONINVALID
0x9811014F: AoE: Symbol version invalid
### EC_E_AOE_INVALIDSTATE
0x98110150: AoE: Server in invalid state
### EC_E_AOE_TRANSMODENOTSUPP
0x98110151: AoE: AdsTransMode not supported
### EC_E_AOE_NOTIFYHNDINVALID
0x98110152: AoE: Notification handle invalid
### EC_E_AOE_CLIENTUNKNOWN
0x98110153: AoE: Notification client not registered
### EC_E_AOE_NOMOREHDLS
0x98110154: AoE: No more notification handles
### EC_E_AOE_INVALIDWATCHSIZE
0x98110155: AoE: Size for watch to big
### EC_E_AOE_NOTINIT
0x98110156: AoE: Device not initialized
### EC_E_AOE_TIMEOUT
0x98110157: AoE: Device has a timeout
### EC_E_AOE_NOINTERFACE
0x98110158: AoE: Query interface failed
### EC_E_AOE_INVALIDINTERFACE
0x98110159: AoE: Wrong interface required
### EC_E_AOE_INVALIDCLSID
0x9811015A: AoE: Class ID invalid
### EC_E_AOE_INVALIDOBJID
0x9811015B: AoE: Object ID invalid
### EC_E_AOE_PENDING
0x9811015C: AoE: Request pending
### EC_E_AOE_ABORTED
0x9811015D: AoE: Request aborted
### EC_E_AOE_WARNING
0x9811015E: AoE: Signal warning
### EC_E_AOE_INVALIDARRAYIDX
0x9811015F: AoE: Invalid array index
### EC_E_AOE_SYMBOLNOTACTIVE
0x98110160: AoE: Symbol not active -> release handle and try again
### EC_E_AOE_ACCESSDENIED
0x98110161: AoE: Access denied
### EC_E_AOE_INTERNAL
0x98110162: AoE: Internal error
### EC_E_AOE_TARGET_PORT_NOT_FOUND
0x98110163: AoE: Target port not found
### EC_E_AOE_TARGET_MACHINE_NOT_FOUND
0x98110164: AoE: Target machine not found
### EC_E_AOE_UNKNOWN_CMD_ID
0x98110165: AoE: Unknown command ID
### EC_E_AOE_PORT_NOT_CONNECTED
0x98110166: AoE: Port not connected
### EC_E_AOE_INVALID_AMS_LENGTH
0x98110167: AoE: Invalid AMS length
### EC_E_AOE_INVALID_AMS_ID
0x98110168: AoE: invalid AMS Net ID
### EC_E_AOE_PORT_DISABLED
0x98110169: AoE: Port disabled
### EC_E_AOE_PORT_CONNECTED
0x9811016A: AoE: Port already connected
### EC_E_AOE_INVALID_AMS_PORT
0x9811016B: AoE: Invalid AMS port
### EC_E_AOE_NO_MEMORY
0x9811016C: AoE: No memory
### EC_E_AOE_VENDOR_SPECIFIC
0x9811016D: AoE: Vendor specific AoE device error
### EC_E_XML_AOE_NETID_INVALID
0x9811016E: ENI: AoE: Invalid NetID (e.g. Error from Configuration Tool)
### EC_E_MAX_BUS_SLAVES_EXCEEDED
0x9811016F: CFG: Error: Maximum number of bus slave has been exceeded (The maximum number of preallocated bus slave objects is too small. The maximum number can be adjusted by the master initialization parameter EC_T_INITMASTERPARMS.dwMaxBusSlaves)
### EC_E_MBXERR_SYNTAX
0x98110170: SLV: Mailbox error: Syntax of 6 octet Mailbox header is wrong (Slave error mailbox return value: 0x01)
### EC_E_MBXERR_UNSUPPORTEDPROTOCOL
0x98110171: SLV: Mailbox error: The Mailbox protocol is not supported (Slave error mailbox return value: 0x02)
### EC_E_MBXERR_INVALIDCHANNEL
0x98110172: SLV: Mailbox error: Field contains wrong value (Slave error mailbox return value: 0x03)
### EC_E_MBXERR_SERVICENOTSUPPORTED
0x98110173: SLV: Mailbox error: The addressed service in the mailbox protocol is not supported (Slave error mailbox return value: 0x04)
### EC_E_MBXERR_INVALIDHEADER
0x98110174: SLV: Mailbox error: The mailbox protocol header of the mailbox protocol is wrong (Slave error mailbox return value: 0x05)
### EC_E_MBXERR_SIZETOOSHORT
0x98110175: SLV: Mailbox error: Length of received mailbox data is too short (Slave error mailbox return value: 0x06)
### EC_E_MBXERR_NOMOREMEMORY
0x98110176: SLV: Mailbox error: Mailbox protocol can not be processed because of limited resources (Slave error mailbox return value: 0x07)
### EC_E_MBXERR_INVALIDSIZE
0x98110177: SLV: Mailbox error: The length of data is inconsistent (Slave error mailbox return value: 0x08)
### EC_E_DC_SLAVES_BEFORE_REF_CLOCK
0x98110178: ENI: Slaves with DC configured present on bus before reference clock (e.g. The first DC Slave was not configured as potential reference clock)
### EC_E_DATA_TYPE_CONVERSION_FAILED
0x98110179: Data type conversion failed
### EC_E_LINE_CROSSED
0x9811017B: Line crossed (cabling wrong)
### EC_E_LINE_CROSSED_SLAVE_INFO
0x9811017C: Line crossed at slave (obsolete)
### EC_E_ADO_NOT_SUPPORTED
0x9811017E: SLV: ADO for slave identification not supported (e.g. Request ID mechanism (ADO 0x134) not supported by slave)
### EC_E_FRAMELOSS_AFTER_SLAVE
0x9811017F: Frameloss after Slave (opening port destroys communication)
### EC_E_OEM_SIGNATURE_MISMATCH
0x98130008: ENI, OEM: Manufacturer signature mismatch
### EC_E_ENI_ENCRYPTION_WRONG_VERSION
0x98130009: ENI, OEM: ENI encryption algorithm version not supported
### EC_E_ENI_ENCRYPTED
0x9813000A: OEM: Loading encrypted ENI needs OEM key
### EC_E_OEM_KEY_MISMATCH
0x9813000B: RAS, APP: OEM key mismatch
### EC_E_OEM_KEY_MISSING
0x9813000C: APP: OEM key access needs OEM key set (e.g. Application must call esSetOemKey (HiL) or set EC_T_LINK_PARMS_SIMULATOR::qwOemKey (SiL))
### EC_E_S2SMBX_NOT_CONFIGURED
0x98130020: S2S: Not Configured
### EC_E_S2SMBX_NO_MEMORY
0x98130021: S2S: No Memory
### EC_E_S2SMBX_NO_DESCRIPTOR
0x98130022: S2S: No Descriptor
### EC_E_S2SMBX_DEST_SLAVE_NOT_FOUND
0x98130023: S2S: Destination Slave not found
### EC_E_MASTER_RED_STATE_INACTIVE
0x98130024: APP: Master Redundancy State is INACTIVE (e.g. API not allowed in current Master Redundancy State)
### EC_E_MASTER_RED_STATE_ACTIVE
0x98130025: APP: Master Redundancy State is ACTIVE (e.g. API not allowed in current Master Redundancy State)
### EC_E_JUNCTION_RED_LINE_BREAK
0x98130026: Junction redundancy line break
### EC_E_VALIDATION_ERROR
0x98130027: Validation error (validation data mismatch)
### EC_E_TIMEOUT_WAITING_FOR_DC
0x98130028: Timeout waiting for DC
### EC_E_TIMEOUT_WAITING_FOR_DCM
0x98130029: Timeout waiting for DCM
### EC_E_SIGNATURE_MISMATCH
0x98130030: Signature mismatch
### EC_E_PDIWATCHDOG
0x98130031: PDI watchdog expired
### EC_E_BAD_CONNECTION
0x98130032: Bad connection
### EC_E_XML_INCONSISTENT
0x98130033: ENI: Inconsistent content
# error-codes_ras.html.md
# Remote API Error Codes
### EC_E_SOCKET_DISCONNECTED
0x9811017D: RAS: Socket disconnected (e.g. IP connection terminated or lost)
### EMRAS_E_INVALIDCOOKIE
0x98110181: RAS: Invalid Cookie (e.g.obsolete)
### EMRAS_E_MULSRVDISMULCON
0x98110183: RAS: Connect 2nd server denied because Multi Server support is disabled (obsolete)
### EMRAS_E_LOGONCANCELLED
0x98110184: RAS: Logon canceled (Server-side connection reject while opening a client connection.)
### EMRAS_E_INVALIDVERSION
0x98110186: RAS: Invalid Version (Connection reject because of using mismatching protocol versions on client and server side)
### EMRAS_E_INVALIDACCESSCONFIG
0x98110187: RAS: Access configuration is invalid (e.g. SPoC access configuration invalid)
### EMRAS_E_ACCESSLESS
0x98110188: RAS: No access to this call at this access level (e.g. a higher SPoC access level is needed to use the called Remote API function)
### EMRAS_E_INVALIDDATARECEIVED
0x98110189: RAS: Invalid data received (communication corrupted)
### EMRAS_EVT_SERVERSTOPPED
0x98110191: RAS: Server stopped (e.g. connection dropped because of Remote API Server stop)
### EMRAS_EVT_WDEXPIRED
0x98110192: RAS: Watchdog expired (e.g. connection dropped because of missing keep-alive messages)
### EMRAS_EVT_RECONEXPIRED
0x98110193: RAS: Reconnect expired (obsolete)
### EMRAS_EVT_CLIENTLOGON
0x98110194: RAS Server: Client logged on
### EMRAS_EVT_RECONNECT
0x98110195: RAS: obsolete
### EMRAS_EVT_SOCKCHANGE
0x98110196: RAS: Socket exchanged after reconnect (obsolete)
### EMRAS_EVT_CLNTDISC
0x98110197: RAS: Client disconnect
### EMRAS_E_ACCESS_NOT_FOUND
0x98110198: RAS: Access not configured for this call (e.g. SPoC access configuration missing)
### EMRAS_E_TOKEN_MISSING
0x98110199: RAS: Token missing
### EMRAS_E_TOKEN_INVALID
0x9811019A: RAS: Token invalid
### EMRAS_E_TOKEN_DENIED
0x9811019B: RAS: Token denied
### EMRAS_E_TLS_CERTIFICATE_ERROR
0x9811019C: RAS: TLS certificate error
### EMRAS_E_TLS_PRIVATEKEY_ERROR
0x9811019D: RAS: TLS private key error
### EMRAS_E_TLS_HANDSHAKE_FAILED
0x9811019E: RAS: TLS handshake failed
\\newpage
# error-codes_soe.html.md
# Servo Drive Profil over EtherCAT® (SoE) Error Codes
### EC_E_SOE_ERRORCODE_INVALID_ACCESS
0x98110078: ERROR SoE: Invalid access to element 0
### EC_E_SOE_ERRORCODE_NOT_EXIST
0x98110079: ERROR SoE: Does not exist
### EC_E_SOE_ERRORCODE_INVL_ACC_ELEM1
0x9811007A: ERROR SoE: Invalid access to element 1
### EC_E_SOE_ERRORCODE_NAME_NOT_EXIST
0x9811007B: ERROR SoE: Name does not exist
### EC_E_SOE_ERRORCODE_NAME_UNDERSIZE
0x9811007C: ERROR SoE: Name undersize in transmission
### EC_E_SOE_ERRORCODE_NAME_OVERSIZE
0x9811007D: ERROR SoE: Name oversize in transmission
### EC_E_SOE_ERRORCODE_NAME_UNCHANGE
0x9811007E: ERROR SoE: Name unchangeable
### EC_E_SOE_ERRORCODE_NAME_WR_PROT
0x9811007F: ERROR SoE: Name currently write-protected
### EC_E_SOE_ERRORCODE_UNDERS_TRANS
0x98110080: ERROR SoE: Attribute undersize in transmission
### EC_E_SOE_ERRORCODE_OVERS_TRANS
0x98110081: ERROR SoE: Attribute oversize in transmission
### EC_E_SOE_ERRORCODE_ATTR_UNCHANGE
0x98110082: ERROR SoE: Attribute unchangeable
### EC_E_SOE_ERRORCODE_ATTR_WR_PROT
0x98110083: ERROR SoE: Attribute currently write-protected
### EC_E_SOE_ERRORCODE_UNIT_NOT_EXIST
0x98110084: ERROR SoE: Unit does not exist
### EC_E_SOE_ERRORCODE_UNIT_UNDERSIZE
0x98110085: ERROR SoE: Unit undersize in transmission
### EC_E_SOE_ERRORCODE_UNIT_OVERSIZE
0x98110086: ERROR SoE: Unit oversize in transmission
### EC_E_SOE_ERRORCODE_UNIT_UNCHANGE
0x98110087: ERROR SoE: Unit unchangeable
### EC_E_SOE_ERRORCODE_UNIT_WR_PROT
0x98110088: ERROR SoE: Unit currently write-protected
### EC_E_SOE_ERRORCODE_MIN_NOT_EXIST
0x98110089: ERROR SoE: Minimum input value does not exist
### EC_E_SOE_ERRORCODE_MIN_UNDERSIZE
0x9811008A: ERROR SoE: Minimum input value undersize in transmission
### EC_E_SOE_ERRORCODE_MIN_OVERSIZE
0x9811008B: ERROR SoE: Minimum input value oversize in transmission
### EC_E_SOE_ERRORCODE_MIN_UNCHANGE
0x9811008C: ERROR SoE: Minimum input value unchangeable
### EC_E_SOE_ERRORCODE_MIN_WR_PROT
0x9811008D: ERROR SoE: Minimum input value currently write-protected
### EC_E_SOE_ERRORCODE_MAX_NOT_EXIST
0x9811008E: ERROR SoE: Maximum input value does not exist
### EC_E_SOE_ERRORCODE_MAX_UNDERSIZE
0x9811008F: ERROR SoE: Maximum input value undersize in transmission
### EC_E_SOE_ERRORCODE_MAX_OVERSIZE
0x98110090: ERROR SoE: Maximum input value oversize in transmission
### EC_E_SOE_ERRORCODE_MAX_UNCHANGE
0x98110091: ERROR SoE: Maximum input value unchangeable
### EC_E_SOE_ERRORCODE_MAX_WR_PROT
0x98110092: ERROR SoE: Maximum input value currently write-protected
### EC_E_SOE_ERRORCODE_DATA_NOT_EXIST
0x98110093: ERROR SoE: Data item does not exist
### EC_E_SOE_ERRORCODE_DATA_UNDERSIZE
0x98110094: ERROR SoE: Data item undersize in transmission
### EC_E_SOE_ERRORCODE_DATA_OVERSIZE
0x98110095: ERROR SoE: Data item oversize in transmission
### EC_E_SOE_ERRORCODE_DATA_UNCHANGE
0x98110096: ERROR SoE: Data item unchangeable
### EC_E_SOE_ERRORCODE_DATA_WR_PROT
0x98110097: ERROR SoE: Data item currently write-protected
### EC_E_SOE_ERRORCODE_DATA_MIN_LIMIT
0x98110098: ERROR SoE: Data item less than minimum input value limit
### EC_E_SOE_ERRORCODE_DATA_MAX_LIMIT
0x98110099: ERROR SoE: Data item exceeds maximum input value limit
### EC_E_SOE_ERRORCODE_DATA_INCOR
0x9811009A: ERROR SoE: Data item incorrect
### EC_E_SOE_ERRORCODE_PASWD_PROT
0x9811009B: ERROR SoE: Data item protected by password
### EC_E_SOE_ERRORCODE_TEMP_UNCHANGE
0x9811009C: ERROR SoE: Data item temporary unchangeable (in AT or MDT)
### EC_E_SOE_ERRORCODE_INVL_INDIRECT
0x9811009D: ERROR SoE: Invalid indirect
### EC_E_SOE_ERRORCODE_TEMP_UNCHANGE1
0x9811009E: ERROR SoE: Data item temporary unchangeable (parameter or opmode)
### EC_E_SOE_ERRORCODE_ALREADY_ACTIVE
0x9811009F: ERROR SoE: Command already active
### EC_E_SOE_ERRORCODE_NOT_INTERRUPT
0x98110100: ERROR SoE: Command not interruptible
### EC_E_SOE_ERRORCODE_CMD_NOT_AVAIL
0x98110101: ERROR SoE: Command not available (in this phase)
### EC_E_SOE_ERRORCODE_CMD_NOT_AVAIL1
0x98110102: ERROR SoE: Command not available (invalid parameter)
### EC_E_SOE_ERRORCODE_DRIVE_NO
0x98110103: ERROR SoE: Response drive number not identical with requested drive number
### EC_E_SOE_ERRORCODE_IDN
0x98110104: ERROR SoE: Response IDN not identical with requested IDN
### EC_E_SOE_ERRORCODE_FRAGMENT_LOST
0x98110105: ERROR SoE: At least one fragment lost
### EC_E_SOE_ERRORCODE_BUFFER_FULL
0x98110106: ERROR SoE: RX buffer full (EtherCAT call with to small data-buffer)
### EC_E_SOE_ERRORCODE_NO_DATA
0x98110107: ERROR SoE: No data state
### EC_E_SOE_ERRORCODE_NO_DEFAULT_VALUE
0x98110108: ERROR SoE: No default value
### EC_E_SOE_ERRORCODE_DEFAULT_LONG
0x98110109: ERROR SoE: Default value transmission too long
### EC_E_SOE_ERRORCODE_DEFAULT_WP
0x9811010A: ERROR SoE: Default value cannot be changed, read only
### EC_E_SOE_ERRORCODE_INVL_DRIVE_NO
0x9811010B: ERROR SoE: Invalid drive number
### EC_E_SOE_ERRORCODE_GENERAL_ERROR
0x9811010C: ERROR SoE: General error
### EC_E_SOE_ERRCODE_NO_ELEM_ADR
0x9811010D: ERROR SoE: No element addressed
\\newpage
# gettingstarted.html.md
# Getting Started
This chapter helps you get EC-Master up and running quickly. It gives a brief overview of the MainDevice stack’s architecture, explains how to configure the EtherCAT® network (ENI) and the operating system, and shows how to compile and run the pre-compiled EcMasterDemo example application.
# gettingstarted_architecture.html.md
# EC-Master Architecture
The EC-Master EtherCAT® MainDevice stack is implemented in C++ and can be easily ported to any embedded OS platforms using an appropriate C++ compiler. The API functions are C language interfaces, thus the MainDevice stack can be used in ANSI-C as well as in C++ environments.
The MainDevice stack is divided into modules, see diagram and descriptions below:
- EtherCAT® MainDevice Core: In the core module cyclic (process data update) and acyclic (mailbox) EtherCAT® commands are sent and received. Among others there exist some state machines to handle for example the mailbox protocols.
- Configuration Layer: The EtherCAT® MainDevice is configured using an XML file whose format is fixed in the EtherCAT® specification ETG.2100. EC-Master contains an OS independent XML parser.
- Real-time Ethernet Driver Layer: This layer exchanges Ethernet frames between the MainDevice and the SubDevices. If hard real-time requirements exist, this layer has to be optimized for the network adapter card in use.
- OS Layer: All OS dependent system calls are encapsulated in a small OS layer. Most functions are that easy that they can be implemented using simple C macros.
# gettingstarted_compiling.html.md
# Compiling the EcMasterDemo
The following main rules can be used to generate the example applications for all operating systems.
- `` is a placeholder for the operating system used.
- `` is a placeholder for the architecture. Different architectures are supported.
## EtherCAT® MainDevice Software Development Kit (SDK)
The EtherCAT® MainDevice development kit is needed to write applications based on the MainDevice stack.
The MainDevice stack is shipped as a library which is linked together with the application.
The following components are supplied together with an SDK:
: ```default
/Bin
/Doc
/SDK
/SDK/INC
/SDK/LIB
/SDK/FILES
/Sources/Common
```
`/Bin`
: Executables containing the MainDevice stack
`/Doc`
: Documentation
`/Examples`
: One or more example applications using a predefined EtherCAT® configuration. It is easily adaptable to different configurations using an appropriate EtherCAT® configuration XML file.
`/SDK`
: EtherCAT® Software Development Kit containing libraries and header files to build C/C++-applications
`/SDK/INC`:
: Header files to be included with the application
`/SDK/LIB`:
: Libraries to be linked with the application
`/SDK/FILES`:
: Additional files for platform integration (e.g. Windows CE registry files)
`/Sources/Common`:
: Shared .cpp-files
## Include search path
The header files are located in the following directories:
: ```default
/SDK/INC
/SDK/INC///Sources/Common
```
## Libraries
The libraries are located in the following directories:
: ```default
/SDK/LIB//
```
# gettingstarted_eni-configuration.html.md
# EtherCAT® Network Configuration (ENI)
The EtherCAT® MainDevice has to know about the EtherCAT® bus topology and the cyclic/acyclic frames to exchange with the SubDevices.
This configuration is determined in a configuration file which has to be available in the EtherCAT® Network Information Format (ENI).
This format is completely independent from EtherCAT® SubDevice vendors, from EtherCAT® MainDevice vendors and from EtherCAT® configuration tools. Thus interoperability between those vendors is guaranteed.
Additionally some static configuration parameters have to be defined like the identification of the network adapter card to use, the priority of the EtherCAT® MainDevice timer task etc.
# gettingstarted_os-configuration.html.md
# Operating system configuration
The main task is to setup the operating system to support the appropriate network adapter for EtherCAT® usage and for some systems real-time configuration may be needed.
The operating system-specific settings and configurations are described in [Platform and Operating Systems (OS)](os.html.md#platform-and-operating-systems-os).
# gettingstarted_running-demo.html.md
# Running EcMasterDemo
The EcMasterDemo is available “out of the box” for different operating systems. It is an EC-Master example application that handles the following tasks:
- Showing basic EtherCAT® communication
- MainDevice stack initialization into OPERATIONAL state
- Process Data operations for e.g. Beckhoff EL2004, EL1004 and EL4132
- Periodic diagnosis task
- Periodic Job Task in polling mode
- Logging
Start the EcMasterDemo from the command line to put the EtherCAT® network into operation. At least a Real-time Ethernet Driver must be specified.
```doscon
> EcMasterDemo -ndis 192.168.157.2 1 -f eni.xml -t 0 -v 3
```
#### SEE ALSO
- [Example application](software-integration_example-application.html.md#example-application) for detailed explanation
## Command line parameters
### EcMasterDemo [-f ENI-FileName] [-t time] [-b cycle time] [-a affinity] [-v level] [-perf [level]] [-log prefix [msg cnt]] [-lic key] [-oem key] [-fingerprint method] [-maxbusslaves cnt] [-flash address] [-sp [port]] [-rec [prefix [frame cnt]]] [-junctionred]
The parameters are as follows:
### -f
Path to ENI file
### -t