RtecatRequestSubDeviceState

RtecatRequestSubDeviceState requests a SubDevice to go into a specified EtherCAT state.

Syntax

Copy 
RTECAT_COMMAND_STATUS RtecatRequestSubDeviceState(
  [in]    RTECAT_HANDLE SubDevice,
  [in]    RTECAT_ETHERCAT_STATE State  
);

Parameters

[in] SubDevice

A handle to a SubDevice. To retrieve the corresponding handle, use RtecatOpenSubDeviceByIndex, RtecatOpenSubDeviceByStationAddress, or RtecatOpenSubDeviceByExplicitId.

[in] State

The requested EtherCAT state.

Return Values

The function returns an RTECAT_COMMAND_STATUS structure. If an error occurs, field State of the structure is set to ecatCommandError and the error code is stored in field ErrorId (see RTECAT_ERROR for error values). If the function succeeds, ErrorId is set to ecatErrNoError (which is represented by the value 0). If the function fails, it stores a different error value.

Possible return values:

Return value Meaning

ecatErrNoError

The function succeeded.

ecatErrWrongParameter

One of the following conditions occurred:

  • Parameter SubDevice is invalid.
  • Field State is less than or equal to ecatStateOffline, or it's not allowed in the current MainDevice state.

ecatErrMainDeviceNotReady

The MainDevice is not ready.

Passing the returned command status to RtecatGetCommandStatus updates the command’s status. If an error occurs during the execution of the command in the system, RtecatGetCommandStatus will record the error in the returned command status. For more details, see RTECAT_ERROR.

Remarks

RtecatRequestSubDeviceState is an asynchronous function that takes time to complete. It allows for background execution and requires you to check its status by calling RtecatGetCommandStatus or wait for it to complete by calling RtecatWaitForCommand.

The sequential order of an EtherCAT device state transition includes the following:

If the current state of a SubDevice is Op and the requested state is PreOp, the SubDevice will process the state change as:

If the current state of a SubDevice is Init and the requested state is Op, the SubDevice will process the state change as:

Requirements

Minimum supported version Header Library

wRTOS 1.0 SDK

RtecatApi.h

RtecatApi_W64.lib (Windows), RtecatApi.lib (RTSS)

See Also: