Using the E-CAT APIs

In this section, we will introduce how to create an E-CAT application using the real-time E-CAT APIs.

Creating an E-CAT Application

You may use the E-CAT APIs in RTSS or Windows applications:

• To build RTSS applications, include the header RtecatApi.h in your project and link with the library RtecatApi.lib.
• To build Windows applications, include the header RtecatApi.h in your project and link with the library RtecatApi_W64.lib.

Managing a MainDevice Instance

The RtecatCreateMainDevice function is the foundational step to start an E-CAT application. It must be called before any other E-CAT API functions can be used. Upon successful execution, RtecatCreateMainDevice creates a MainDevice instance and returns a MainDevice handle. This handle is the root for obtaining handles to all other objects (such as SubDevice, axis, and module) within the MainDevice.

Once the MainDevice is created, you can use the RtecatStart and RtecatStop functions to start and stop the E-CAT link associated with the MainDevice instance. The link must be started before accessing any objects within the MainDevice.

At the end of the E-CAT application, you must follow the steps to terminate the MainDevice:

1. Use RtecatCloseHandle to close the object handles derived from a MainDevice, such as SubDevice, axis, or module handles, before using RtecatDestroyMainDevice.

Note: We recommend you close the object handles derived from a MainDevice once they are no longer in use.

2. To terminate the MainDevice instance, use RtecatDestroyMainDevice. This will automatically close its handle.

Manipulating Objects within a MainDevice through Handles

To access the objects within a MainDevice, you need to use the MainDevice handle.

For example, you need to input a MainDevice handle when opening an axis object by calling the RtecatOpenAxisByIndex function, which will return an axis handle. You can then access the axis' information through its handle. For instance, if you want to get an axis status by calling the RtecatGetAxisStatus function, you need to input the axis handle.

When you no longer need to use the object handles, you must use RtecatCloseHandle to close them.

Identifying Synchronous and Asynchronous Commands

Each E-CAT API function is designed with a specific command type, either a synchronous or asynchronous command.

• Synchronous commands: execute immediately and return a result upon completion.
  • Example: RtecatOpenAxisByIndex and RtecatGetAxisStatus.
• Asynchronous commands: take time to complete. They allow for background execution and require status checking or waiting.
  • To check the status of a single command, call RtecatGetCommandStatus. To check the status of multiple commands, call RtecatGetCommandsStatus.
  • To wait for completion of the commands, call RtecatWaitForCommand.
  • Example: RtecatStart and RtecatStop.

  Note: You can identify an asynchronous command by its return value. If a function returns an RTECAT_COMMAND_STATUS structure, it is an asynchronous command.

Example

RTECAT_HANDLE mainDevice = { 0 };
RtecatCreateMainDevice(&mainDevice, 0, 0);
 
RtecatSetConfiguredAxisCount(mainDevice, 1);

// Start the E-CAT MainDevice and wait a set time for the Asynchronous command to return 
RTECAT_COMMAND_STATUS startCmd = RtecatStart(mainDevice);
startCmd = RtecatWaitForCommand(30, true, startCmd);  
 
// Alternatively start the E-CAT MainDevice and sleep and then check status 
 
if (startCmd.State != ecatCommandDone)
{
    RtecatDestroyMainDevice(mainDevice);
    return;
}

RTECAT_HANDLE axisHandle = { 0 };
// Synchronous command executes immediately
RtecatOpenAxisByIndex(mainDevice, &axisHandle, 0);
 
RTECAT_AXIS_STATUS axisSts = { 0 };
RtecatGetAxisStatus(axisHandle, &axisSts);
 
RtecatCloseHandle(axisHandle);
 
RTECAT_COMMAND_STATUS stopCmd = RtecatStop(mainDevice);
stopCmd = RtecatWaitForCommand(10, true, stopCmd);
 
RtecatDestroyMainDevice(mainDevice);
 
return;