Custom Simulated Motor

The Custom Simulated Motor feature allows users to simulate custom motor behavior on simulated axes in KINGSTAR. To use this feature, users must prepare a user application and a custom simulated motor RTDLL. KINGSTAR provides a set of APIs and implementation samples to support the development of user applications and custom RTDLL.

NOTE: The Custom Simulated Motor feature is supported in KINGSTAR 4.5.4 and later.

IN THIS SECTION:

Workflow
Implementing Custom Simulated Motor in RTDLL
Using Custom Simulated Motors in KINGSTAR
- C++ Implementation Sample
- .NET Implementation Sample

Workflow

This basic workflow outlines how to use the Custom Simulated Motor feature:

Create a user application
Use the following APIs to create a custom application. For details, refer to the C++ and .NET implementation samples in Using Custom Simulated Motors in KINGSTAR.
- LoadCustomMotorLibrary: Loads the custom simulated motor RTDLL into KINGSTAR.
- ConfigureAxisEx: Configures the settings of a simulated axis and associates the axis with a custom simulated motor.
- GetAxisMotorType: Checks the simulated motor type.
- KINGSTAR Motion APIs: Interact with the custom simulated motor.

Implement a custom simulated motor RTDLL

To use your custom simulated motor in KINGSTAR, you must implement it as an RTDLL. The RTDLL must implement the following functions for KINGSTAR to load and execute your motor simulation. For more details on implementation, see Implementing Custom Simulated Motor in RTDLL.

Required functions: CreateSimMotor, DestroySimMotor, RunSimMotor, GetSimMotorData, ResetSimMotorData

Click to see code snippet

Copy

// Create simulated motor that will be used by KINGSTAR motion runtime.
//
// Parameters:
// * Index: Axis index
// * SimulatedAxisDetails: Pointer to a structure that contains simulated axis details
//
// Returns: Handle to custom simulated motor
__declspec (dllexport) HANDLE __stdcall CreateSimMotor(
    size_t Index, const McSimulatedAxisDetails* SimulatedAxisDetails);
 
// Destroy simulated motor. This function will be used when KINGSTAR motion runtime cleans up its
// internal resource, and you can use it to clean internal simulated motor resources.
//
// Parameters:
// * MotorHandle: Simulated motor handle
__declspec (dllexport) void __stdcall DestroySimMotor(HANDLE MotorHandle);
 
// Run simulated motor. This function will be used by KINGSTAR motion runtime to run your
// simulated motor logic.
//
// Parameters:
// * MotorHandle: Simulated motor handle
// * ControlMode: Axis control mode
// * TargetPosition: Interpolated position when axis is run in position mode, unit: count
// * TargetVelocity:
//  - Interpolated velocity when axis is run in position mode, unit: count/s
//  - PID velocity when axis is run in velocity mode, unit: count/s
// * TargetTorque: PID torque when axis is run in torque mode, unit: % of rated torque
// * TorqueOffset: Torque offset, unit: % of rated torque
__declspec (dllexport) void __stdcall RunSimMotor(
    HANDLE MotorHandle,
    McControlMode ControlMode,
    double TargetPosition,
    double TargetVelocity,
    double TargetTorque,
    double TorqueOffset
);
 
// Get data from simulated motor. This function will be used by KINGSTAR motion runtime to
// get simulated data.
//
// Parameters:
// * MotorHandle: Simulated motor handle
// * ActualPrimaryPosition: Output pointer of actual primary position, unit: count
// * ActualSecondaryPosition: Output pointer of actual secondary position, unit: count
// * ActualVelocity: Output pointer of actual velocity, unit: count/s
// * ActualTorque: Output pointer of actual torque, unit: % of rated torque
__declspec (dllexport) void __stdcall GetSimMotorData(
    HANDLE MotorHandle,
    double* ActualPrimaryPosition,
    double* ActualSecondaryPosition,
    double* ActualVelocity,
    double* ActualTorque
);
 
// Reset motor data. This function will be used when axis state is axisDisabled or axisStandstill.
// It can be used to reset internal variables in simulation logic.
//
// Parameters:
// * MotorHandle: Simulated motor handle
// * AxisState: Axis state
__declspec (dllexport) void __stdcall ResetSimMotorData(HANDLE MotorHandle, AxisState AxisState);

KINGSTAR Motion will pass motion target settings to the RTDLL through RunSimMotor to run custom simulated motor.
KINGSTAR Motion will retrieve actual data from the custom simulated motor through GetSimMotorData.

Implementing Custom Simulated Motor in RTDLL

Overview

To integrate a custom simulated motor with KINGSTAR, you must implement it as an RTDLL. This enables KINGSTAR to load and execute the motor simulation.

NOTE: RTDLL implementations must be error-free, and it is not recommended to use KINGSTAR APIs within the RTDLL. Review Important Guidelines before starting development.

Getting Started

Use the KsUserApp sample code. Please contact KINGSTAR Support to obtain KsUserApp.
Navigate to the KsCustomSimulatedMotorRTDLL project, which serves as a reference implementation.

Project Structure

File	Purpose	Modification required
DllMain.cpp	RTDLL entry point	Do NOT modify
CustomSimulatedMotorRTDLL.h	Function declarations for KINGSTAR integration	Do NOT modify
CustomSimulatedMotorRTDLL.cpp	Sample implementation using BasicSimulatedMotor	Customize as needed
BasicSimulatedMotor.h	Basic motor simulator class declaration	Customize as needed
BasicSimulatedMotor.cpp	Basic motor simulator class implementation	Customize as needed

Implementation Steps

Analyze the sample code:
Review the sample implementation to understand the overall structure and workflow.
Modify the RTDLL implementation:
Update CustomSimulatedMotorRTDLL.cpp with your custom motor logic.
Implement motor behavior:
Customize BasicSimulatedMotor.h and BasicSimulatedMotor.cpp to match your motor's characteristics.

Important Guidelines

When developing your RTDLL implementation, adhere to the following requirements:

Error-free execution:
The implementation must not generate errors or throw exceptions.
API restrictions:
It is not recommended to use KINGSTAR APIs within the RTDLL.
Build configuration:
It is recommended to compile the RTDLL in Release mode to ensure optimal performance in production environments.

Using Custom Simulated Motors in KINGSTAR

This section describes how to integrate and run custom simulated motors using both KINGSTAR C and .NET APIs. The integration process follows a standardized workflow:

Initialize the KINGSTAR Subsystem:
Use Create to establish the KINGSTAR environment.
Load the custom motor library:
Call LoadCustomMotorLibrary with your RTDLL path. If there are no errors, this returns a library ID for the specified RTDLL.
Configure simulated axes:
Use SetConfiguredAxesCount to define the number of simulated axes.
Set up axis configuration:
Call ConfigureAxisEx to associate an axis with your custom simulated motor.
Note: In the .NET API, this function is named ConfigureAxis.
Configure motion parameters:
Set up axis motion settings according to your requirements.
Execute motor simulation:
Run your simulated axis test scenarios.
Cleanup:
Stop and destroy the KINGSTAR Subsystem when execution is complete.

Detailed implementation examples are provided in both C++ and .NET API sample projects below.

C++ Implementation Sample

Getting Started

Use the KsUserApp sample code. Please contact KINGSTAR Support to obtain KsUserApp.
Open the KsCustomSimulatedMotorAppCPP project.

Project Components

File	Purpose	Modification required
CustomSimulatedMotorApi.h	Custom simulated motor API declarations	Do NOT modify
main.cpp	Complete workflow example	Customize as needed

Running the C++ Sample

Configure the KINGSTAR Runtime environment:
1. Open Runtime Settings from the KINGSTAR Control Panel.
2. If a NIC is assigned to KINGSTAR, release it to ensure KINGSTAR runs in simulation mode.
Prepare your RTDLL:
1. Build the KsCustomSimulatedMotorRTDLL project.
2. Deploy the compiled RTDLL to your target directory.
Configure the sample project:
1. Open the sample project in Visual Studio.
2. Update the CUSTOM_SIMULATED_MOTOR_RTDLL_FILE_PATH constant with the absolute ASCII path to your RTDLL.
Build and execute:
1. Compile the sample project.
2. Run the executable and verify the console output.

Creating a Custom C++ Application

Generate a project template:
Use the RTX64 Project Wizard to create a new C++ project.
Configure linker dependencies:
1. WIN32 configuration: Add ksapi.lib to the linker settings.
2. RTSS configuration: Add ksapi_rtss.lib to the linker settings.
Import API headers:
Copy CustomSimulatedMotorApi.h from the sample project into your project.
Implement your logic:
Use the sample workflow as a foundation and customize the motor testing logic for your specific requirements.

.NET Implementation Sample

The following example uses KINGSTAR .NET Local APIs.

Getting Started

Use the KsUserApp sample code. Please contact KINGSTAR Support to obtain KsUserApp.
Open the KsCustomSimulatedMotorAppDotNet project.

Project Components

File	Purpose	Modification required
Program.cs	Complete workflow example	Customize as needed

Running the .NET Sample

Configure the KINGSTAR Runtime environment:
1. Open Runtime Settings from the KINGSTAR Control Panel.
2. If a NIC is assigned to KINGSTAR, release it to ensure KINGSTAR runs in simulation mode.
Prepare your RTDLL:
1. Build the KsCustomSimulatedMotorRTDLL project.
2. Deploy the compiled RTDLL to your target directory.
Configure the sample project:
1. Open the sample project in Visual Studio.
2. Update CUSTOM_SIMULATED_MOTOR_RTDLL_FILE_PATH with the absolute ASCII path to your RTDLL.
Build and execute:
1. Compile the sample project.
2. Run the executable and check console output.

Creating a Custom .NET Application

Generate a project template:
Use Visual Studio to create a new .NET project.
Configure references:
1. For projects using KINGSTAR .NET Local API, add:
  1. IntervalZero.KINGSTAR.Base
  2. IntervalZero.KINGSTAR.Local
2. For projects using KINGSTAR .NET OpcUa API, add:
  1. IntervalZero.KINGSTAR.Base
  2. IntervalZero.KINGSTAR.OpcUa.Client
Implement your logic:
Use the sample workflow as a foundation and customize the motor testing logic for your specific requirements.