Checking Axis Existence in SIMOTION Scout with _getStateOfTo

Overview

In SIMOTION projects engineered with SCOUT, every motion axis, cam, encoder, and following object is represented by a Technology Object (TO). Whether you build a reusable motion library, a flexible warm-restart sequence, or a machine with optional secondary axes, the program must frequently verify that a given TO has actually been instantiated in the project configuration. Issuing motion commands against an unconfigured TO can fault the axis, lock system resources, or abort program execution.

The cleanest way to test for TO existence from within a Structured Text (ST) source is the SIMOTION system function _getStateOfTo. The function returns a structured diagnostic record that allows the application to distinguish between a TO that is present, a TO that is present but inactive, and a TO that is missing from the project altogether.

Prerequisites

• SCOUT (or TIA Portal with SIMOTION Option) with an online connection to the controller.
• A SIMOTION D, SIMOTION P, or SIMOTION C runtime with the relevant Technology Packages installed (Cam, CamExt, Path, or Pos).
• User rights that allow editing, compiling, and downloading ST sources.
• The project must have been compiled and downloaded at least once after the TO was added; otherwise, the runtime is unaware of the new configuration.
• Familiarity with the ST editor and the watch/recipe functions of SCOUT for online testing.

SIMOTION Technology Objects and Existence Semantics

A Technology Object bundles configuration data, runtime data, and diagnostic data for one motion entity. SIMOTION differentiates several TO classes:

The existence of a TO is a project-level property. A TO is considered existing when its configuration has been compiled and downloaded to the runtime. A TO is considered active when it has been instantiated on the controller and enabled for motion commands. These two states are independent: a TO can exist but be inactive (deactivated or in restart).

The _getStateOfTo System Function

_getStateOfTo is a SIMOTION system function that returns the runtime state of any technology object. The full function signature is shown below:

FUNCTION _getStateOfTo : StructRetGetStateOfTo
VAR_INPUT
    TO_Instance               : ANY_OBJECT_TO;
    reqActDeactGetStateMode   : DINT;
    commandId                 : DINT;
    nextCommand               : DINT;
END_VAR

The function operates asynchronously when configured with REQUEST_TRUE. That is, the call returns immediately and the actual state becomes available after the controller finishes processing the command.

Parameter Reference

The StructRetGetStateOfTo Return Structure

The function returns a structure that contains the result of the asynchronous call. Typical members include:

Return Code Reference

The hexadecimal code returned in functionResult tells the application whether the TO exists. Two codes are central to the existence check:

Other diagnostic codes may appear when the runtime rejects the call for reasons unrelated to existence (for example, command ID already in use, or the TO exists but is in restart). Refer to the SCOUT Online Help for _getStateOfTo for the complete enumeration applicable to your Technology Package.

Minimal ST Implementation

The SCOUT project generator provides a working template. The interface section declares the required Technology Package and the return variable; the implementation section calls _getStateOfTo with the parameters documented above.

INTERFACE
USEPACKAGE Cam;
VAR_GLOBAL
    myRetStructRetGetStateOfTo : StructRetGetStateOfTo;
END_VAR
PROGRAM example;
END_INTERFACE

IMPLEMENTATION
PROGRAM example
    myRetStructRetGetStateOfTo := _getStateOfTo(
        TO_Instance               := Axis_1,
        reqActDeactGetStateMode   := REQUEST_TRUE,
        commandId                 := _getcommandID(),
        nextCommand               := WHEN_COMMAND_DONE);
END_PROGRAM
END_IMPLEMENTATION

This minimal example triggers the check once. To react to the result, the program must poll the asynchronous job until commandIdState indicates completion.

Reusable FB Wrapper with Asynchronous Polling

Wrap _getStateOfTo in a function block so the call can be reused across projects. The wrapper exposes a Boolean AxisExists flag and an Integer Status field for diagnostic HMI screens.

INTERFACE
USEPACKAGE Cam;

FUNCTION_BLOCK fbCheckAxisExist;
    VAR_INPUT
        AxisRef : ANY_OBJECT_TO;
        Execute : BOOL;
    END_VAR
    VAR_OUTPUT
        AxisExists : BOOL;
        Status     : DINT;
        Done       : BOOL;
        Busy       : BOOL;
        Error      : BOOL;
    END_VAR
    VAR
        State : StructRetGetStateOfTo;
        CmdId : DINT;
        RTrig : R_TRIG;
    END_VAR
END_INTERFACE

IMPLEMENTATION
FUNCTION_BLOCK fbCheckAxisExist;
    RTrig(CLK := Execute);

    IF RTrig.Q THEN
        CmdId     := _getcommandID();
        Busy      := TRUE;
        Done      := FALSE;
        Error     := FALSE;
        AxisExists := FALSE;

        State := _getStateOfTo(
                    TO_Instance               := AxisRef,
                    reqActDeactGetStateMode   := REQUEST_TRUE,
                    commandId                 := CmdId,
                    nextCommand               := WHEN_COMMAND_DONE);
    END_IF;

    IF Busy THEN
        State := _getStateOfTo(
                    TO_Instance               := AxisRef,
                    reqActDeactGetStateMode   := REQUEST_FALSE,
                    commandId                 := CmdId,
                    nextCommand               := WHEN_COMMAND_DONE);
    END_IF;

    Status     := State.functionResult;
    Done       := State.commandIdState = COMMAND_DONE;
    Error      := (Status <> 16#00000000) AND Done;

    IF Done THEN
        Busy       := FALSE;
        AxisExists := (Status = 16#00000000);
    END_IF;
END_FUNCTION_BLOCK;
END_IMPLEMENTATION

The rising edge of Execute issues a new check; the polling loop refreshes the state every cycle until the command completes. The AxisExists flag latches once Done becomes TRUE and remains valid until the next rising edge of Execute.

Checking Multiple Axes at Warm Restart

For machines with optional axes (for example, a second feeder that is only installed on certain variants), create one instance of fbCheckAxisExist per TO and trigger all of them in the warm-restart sequence. A typical pattern:

1. Declare a global array of fbCheckAxisExist instances, one per optional TO.
2. In the warm-restart task, set Execute := TRUE for every instance at the same scan.
3. Wait until every Done flag has been set (use a simple WHILE loop or a state machine).
4. Copy the AxisExists Booleans to a global structure that the HMI and the application program can read.

The resulting structure can drive HMI visibility (hide HMI tags for axes that do not exist) and gate motion commands (only call _enableAxis on a TO that the runtime actually knows).

Integration with MCC Charts

Although MCC charts cannot call _getStateOfTo directly, an ST program can publish its AxisExists flag to a unit variable or a global Boolean. The MCC chart then references that Boolean as a transition condition or as a block enable signal. This pattern keeps the MCC logic readable while delegating the existence check to ST.

Integration with HMI / WinCC flexible

Bind the global AxisExists structure to HMI tags. Suggested visualizations:

• Display a green/yellow traffic-light icon next to each axis name on the operator screen.
• Suppress alarm lists that reference non-existing axes to avoid operator confusion.
• Use the flag to drive a recipe step that warns the operator about an optional axis not being detected.

Project Generator Sample Application

Siemens publishes a complete sample project that demonstrates _getStateOfTo with the Cam Technology Package. The example is available from the Siemens Industry Online Support portal under entry 51339107. To integrate the sample:

1. Open SCOUT and load your project.
2. Choose Project > Use Project Generator.
3. Browse to the application example and add it to your project tree.
4. Compile and download the project to the SIMOTION controller.
5. Open the ST source delivered with the example and inspect the call signature, then adapt it to your TOs.

Verification and Commissioning Procedure

1. Compile the project and download it to the SIMOTION controller.
2. Go online and open the watch table for your fbCheckAxisExist instance.
3. For a configured TO, confirm Status == 16#00000000 and AxisExists == TRUE.
4. Rename the TO in the project tree, recompile, and re-test. Status must change to 16#FFFF8090 and AxisExists must drop to FALSE.
5. Force the Execute input several times to verify the rising-edge trigger and the latching of the result.
6. Bind Status and AxisExists to the HMI and confirm visual feedback.

Edge Cases and Troubleshooting Matrix

Performance and Task Placement

_getStateOfTo is non-blocking and safe to call frequently. Polling the asynchronous job in a high-priority cyclic task can nevertheless increase CPU load. Recommended practice:

• Trigger the check once during warm restart and cache the result for the remainder of the cycle.
• Re-trigger only when the operator selects a different recipe or when the configuration is reloaded.
• If continuous polling is unavoidable, place the FB in a background or slow cyclic task (50 ms to 100 ms).

Library Reuse Across Projects

Package the wrapper FB and its global structures in a SCOUT library. The library can be referenced from any project, so a single well-tested implementation supports the entire fleet. Keep the technology package version specified in the library in sync with the target project; mismatched USEPACKAGE versions cause compilation errors that are easy to miss.

Safety Considerations

The existence check is a runtime diagnostic, not a safety function. Never rely on _getStateOfTo in a SIMOTION Safety Integrated (F-CPU) context. For functional safety, configure the Safety TO independently and use the certified safety function blocks to verify safety-relevant axes.

Related System Functions

For comparison, several adjacent SIMOTION system functions can supplement _getStateOfTo:

Combine _getStateOfTo with these functions to build a complete startup, runtime, and shutdown sequence that respects the TO lifecycle.

Frequently Asked Questions