KINGSTAR subsystem status check upon multi-application enabling

The KINGSTAR subsystem can be linked to multiple applications simultaneously. Users are able to develop diverse applications with different languages, such as C/C++ and .NET, and then connect all the applications to a single KINGSTAR subsystem. Since KINGSTAR supports the OPC UA standard communication protocol, you can remotely connect your applications to the KINGSTAR subsystem through OPC UA.

NOTE:  Starts from KINGSTAR 4.4, the dlls include the .NET API and .NET Class interfaces that can be used from a remote computer.

The diagram below illustrates that multiple applications developed using different languages can be linked to a single KINGSTAR subsystem concurrently. Here, we will refer to the computer that has KINGSTAR Runtime installed as the local computer, while the other computer without KINGSTAR Runtime installed as the remote computer. Due to the local computer has already installed the KINGSTAR Runtime, through core allocation, the computer has been divided into two systems, RTX64 and Windows. The KINGSTAR subsystem operates on the RTX64 system. Assuming we have developed two applications each on the RTX64 and Windows systems: App 1 and App 2 (RTX64); App 3 and App 4 (Windows). Additionally, on the remote computer, we have developed App 5 and App 6. All these applications can be linked to the KINGSTAR subsystem on the local computer.

When linking the applications to the KINGSTAR subsystem, we would first execute certain procedures. These procedures include initiating the real-time subsystem (RTSS) of RTX64, followed by starting the KINGSTAR subsystem or EtherCAT network. Let's say if we want to link 3 applications (App 1, App 2, App 3) to the KINGSTAR subsystem together. In this scenario, when App 1 connects to the KINGSTAR subsystem initially, it triggered the activation of both the RTSS and KINGSTAR subsystems. Subsequently, when App 2 wants to connect to the KINGSTAR subsystem, there is no need to initiate the RTSS and KINGSTAR subsystems again. Similarly, when App 3 seeks to connect to the KINGSTAR subsystem, it's unnecessary to activate the RTSS and KINGSTAR subsystems once again.

This is why we need a mechanism for the applications to check the current status of the KINGSTAR subsystem before connecting to it. By doing so, applications can determine the appropriate actions to take next. Such a mechanism can be achieved by using the KINGSTAR APIs. You can utilize the KINGSTAR APIs to retrieve all the variables, including KINGSTAR subsystem status, from the global KINGSTAR memory region. The global KINGSTAR memory region is controlled by the KINGSTAR subsystem and is provided for all the applications to communicate with each other.

The example below illustrates the basic process of connecting to the KINGSTAR subsystem. It also demonstrates how to utilize the APIs for configuring the subsystem and controlling the EtherCAT network and motion devices. When calling Create, it will automatically check whether the KINGSTAR subsystem is started. You can use GetStatus to check for the EtherCAT state.

Example

//////////////////////////////////////////////////////////////////
//
// This code snippet demonstrates a basic flow of how to link to
// KINGSTAR subsystem and use the APIs to configure subsystem and
// control the EtherCAT network and motion devices.
//
//////////////////////////////////////////////////////////////////

KsError nRet = errNoError;
KsCommandStatus Command = { 0 };
SubsystemStatus Subsystem = { ecatOffline, ecatOffline, 0, 0, 0, {ecatOffline}, {ecatOffline}, {axisOffline} };

// Link to the KINGSTAR subsystem.
// If the KINGSTAR subsystem does not exist, it would create a new KINGSTAR subsystem.
// You have to call this API first before you use other KINGSTAR functions.
nRet = Create(0, 0);

// Check if the subsystem is started.
// A new KINGSTAR subsystem is not started by default.
nRet = GetStatus(&Subsystem, NULL);
if (Subsystem.State == ecatOP)
{
    RtPrintf("EtherCAT already started: %x\n", nRet);
}
else if (nRet == errNoError && Subsystem.State == ecatOffline)
{
    // When the subsystem state is ecatOffline, you can use below APIs to configure settings:
    //
    // Subsystem Configuration APIs
    // Axis Variable APIs
    // AddModuleConfiguration()
    // RemoveModuleConfiguration()
    // SetConfigurationAxseCount()
    // SetConfigurationIoCount()
    //
    // If you just want to use the default setting, skip this part and start the subsystem.

    // Start the subsystem. It would change the subsystem state to ecatOP.
    // This function is asynchronous so the network is not started yet when it returns.
    // Use WaitForCommand() for synchronization.
    Command = WaitForCommand(30, TRUE, Start());
}

// Now the subsystem state is ecatOP, you can use below APIs to control the subsystem and devices:
//
// Subsystem Control
// Slave Control
// Axis Control
// IO Control
// Heartbeat
// COM API
// Motion API
//
// You can also change the subsystem state or slave state.
// Please check "Usable EtherCAT states" section and the API pages to find out
// which functions you can use in different states.

// Stop the EtherCAT network before destroying KINGSTAR Subsystem or before re-configuration.
Command = WaitForCommand(5, FALSE, Stop());
if (Command.Error)
{
    RtPrintf("Stop Failed: %d\n", Command.ErrorId);
}

// Terminates the KINGSTAR Subsystem if there is no other application connected to it.
nRet = Destroy();
if (nRet != errNoError)
{
    RtPrintf("Destroy Failed: %x\n", nRet);
}