自订虚拟马达

自订虚拟马达（Custom Simulated Motor）功能允许使用者在 KINGSTAR 的虚拟轴上模拟自订马达行为。要使用此功能，使用者必须准备一个使用者应用程式以及一个自订虚拟马达 RTDLL。KINGSTAR 提供了一组 API 与实作范例，以支援使用者开发应用程式与自订 RTDLL。

注意：自 KINGSTAR 4.5.4 及以后版本支援自订虚拟马达功能。

本节内容：

工作流程
在 RTDLL 中实作自订虚拟马达
在 KINGSTAR 中使用自订虚拟马达
- C++ 实作范例
- .NET 实作范例

工作流程

以下为使用自订虚拟马达功能的基本流程：

建立使用者应用程式
使用下列 API 来建立自订应用程式，详细资讯请参阅「在 KINGSTAR 中使用自订虚拟马达」中的 C++ 与 .NET 实作范例：
- LoadCustomMotorLibrary：将自订虚拟马达 RTDLL 载入 KINGSTAR。
- ConfigureAxisEx：配置虚拟轴的设定，并将该轴关联到自订虚拟马达。
- GetAxisMotorType：检查虚拟马达类型。
- KINGSTAR Motion APIs：与自订虚拟马达进行互动。

实作自订虚拟马达 RTDLL

为了在 KINGSTAR 中使用自订虚拟马达，必须将其实作为 RTDLL。其中，RTDLL 必须实作以下函式，以便 KINGSTAR 载入并执行马达虚拟行为。有关实作的详细资讯，请参阅「在 RTDLL 中实作自订虚拟马达」。

需求函式：CreateSimMotor, DestroySimMotor, RunSimMotor, GetSimMotorData, ResetSimMotorData

点击以查看程式码片段

复制

// 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 将透过 RunSimMotor 传递运动目标设定给 RTDLL，以执行自订虚拟马达。
KINGSTAR Motion 将透过 GetSimMotorData 从自订虚拟马达撷取实际数据。

在 RTDLL 中实作自订虚拟马达

概述

若要将自订虚拟马达与 KINGSTAR 整合，您必须将其实作为 RTDLL，以使 KINGSTAR 能够载入并执行马达虚拟行为。

注意：请确保 RTDLL 实作不会产生错误，且不建议在 RTDLL 中使用 KINGSTAR API。开发前请详阅「重要指引」。

开始使用

使用 KsUserApp 范例程式码（请联系 KINGSTAR 技术支援以取得 KsUserApp）。
导览至 KsCustomSimulatedMotorRTDLL 专案，作为参考实作。

专案结构

档案	用途	是否需要修改
DllMain.cpp	RTDLL 入口点	不可修改
CustomSimulatedMotorRTDLL.h	整合至 KINGSTAR 的函式宣告	不可修改
CustomSimulatedMotorRTDLL.cpp	使用 BasicSimulatedMotor 的范例实作	可依需求自订
BasicSimulatedMotor.h	基本虚拟马达类别宣告	可依需求自订
BasicSimulatedMotor.cpp	基本虚拟马达类别实作	可依需求自订

实作步骤

分析范例程式码：
审阅范例实作以了解整体结构与工作流程。
修改 RTDLL 实作：
使用您的自订马达逻辑更新 CustomSimulatedMotorRTDLL.cpp。
实作马达行为：
自订 BasicSimulatedMotor.h 与 BasicSimulatedMotor.cpp 以符合您的马达特性。

重要指引

开发您的 RTDLL 实作时，请遵守以下要求：

无错误执行：
实作绝不能产生错误或抛出异常。
API 限制：
不建议在 RTDLL 中使用 KINGSTAR API。
编译设定：
建议在量产（Release）模式下编译 RTDLL，以确保在生产环境中获得最佳效能。

在 KINGSTAR 中使用自订虚拟马达

此章节说明如何使用 KINGSTAR C 与 .NET API 整合并执行自订虚拟马达，以下为整合标准流程：

初始化 KINGSTAR 子系统：
使用 Create 建立 KINGSTAR 环境。
载入自订马达函式库：
呼叫 LoadCustomMotorLibrary 并提供 RTDLL 路径。成功回传后，会取得该 RTDLL 的函式库 ID。
设定虚拟轴：
使用 SetConfiguredAxesCount 定义虚拟轴数量。
配置轴设定：
呼叫 ConfigureAxisEx 将轴与您的自订虚拟马达关联。
注意：.NET API 中对应函式名称为 ConfigureAxis。
设定运动参数：
依需求设定轴运动参数。
执行马达虚拟行为：
执行虚拟轴测试实例。
清除：
执行完成后，停止并销毁 KINGSTAR 子系统。

C++ 与 .NET API 范例专案提供详细的实作范例，请见以下内容。

C++ 实作范例

开始使用

使用 KsUserApp 范例程式码（请联系 KINGSTAR 技术支援以取得 KsUserApp）。
开启 KsCustomSimulatedMotorAppCPP 专案。

专案元件

档案	用途	是否需要修改
CustomSimulatedMotorApi.h	自订虚拟马达 API 宣告	不可修改
main.cpp	完整流程范例	可依需求自订

执行 C++ 范例

设定 KINGSTAR Runtime 环境：
1. 从 KINGSTAR 控制台开启 Runtime 设定。
2. 若已将 NIC 指派给 KINGSTAR，请释放它以确保 KINGSTAR 在虚拟模式下执行。
准备您的 RTDLL：
1. 编译 KsCustomSimulatedMotorRTDLL 专案。
2. 将编译好的 RTDLL 部署至您的目标目录。
设定范例专案：
1. 在 Visual Studio 中开启范例专案。
2. 将 CUSTOM_SIMULATED_MOTOR_RTDLL_FILE_PATH 常数更新为指向您 RTDLL 的绝对 ASCII 路径。
编译并执行：
1. 编译范例专案。
2. 执行执行档并验证主控台输出。

建立自订 C++ 应用程式

产生专案范本：
使用 RTX64 Project Wizard 建立一个新的 C++ 专案。
设定连结器相依性：
1. WIN32 配置：在连结器设定中加入 ksapi.lib。
2. RTSS 配置：在连结器设定中加入 ksapi_rtss.lib。
汇入 API 标头档：
从范例专案中将 CustomSimulatedMotorApi.h 复制到您的专案中。
实作您的逻辑：
以范例工作流程为基础，根据您的特定需求自订马达测试逻辑。

.NET 实作范例

以下范例使用 KINGSTAR .NET Local API。

开始使用

使用 KsUserApp 范例程式码（请联系 KINGSTAR 技术支援以取得 KsUserApp）。
开启 KsCustomSimulatedMotorAppDotNet 专案。

专案元件

档案	用途	是否需要修改
Program.cs	完整工作流程范例	可依需求自订

执行 .NET 范例

设定 KINGSTAR Runtime 环境：
1. 从 KINGSTAR 控制台开启 Runtime 设定。
2. 若已将 NIC 指派给 KINGSTAR，请释放它以确保 KINGSTAR 在虚拟模式下执行。
准备您的 RTDLL：
1. 编译 KsCustomSimulatedMotorRTDLL 专案。
2. 将编译好的 RTDLL 部署至您的目标目录。
设定范例专案：
1. 在 Visual Studio 中开启范例专案。
2. 将 CUSTOM_SIMULATED_MOTOR_RTDLL_FILE_PATH 更新为指向您 RTDLL 的绝对 ASCII 路径。
编译并执行：
1. 编译范例专案。
2. 执行执行档并验证主控台输出。

建立自订 .NET 应用程式

产生专案范本：
使用 Visual Studio 建立一个新的 .NET 专案。
设定引用：
1. 对于使用 KINGSTAR .NET Local API 的专案，加入：
  1. IntervalZero.KINGSTAR.Base
  2. IntervalZero.KINGSTAR.Local
2. 对于使用 KINGSTAR .NET OpcUa API 的专案，加入：
  1. IntervalZero.KINGSTAR.Base
  2. IntervalZero.KINGSTAR.OpcUa.Client
实作您的逻辑：
以范例工作流程为基础，根据您的特定需求自订马达测试逻辑。