KMAPI/zh-hans

From SoftMC-Wiki
< KMAPI
Revision as of 09:07, 6 July 2017 by Chi (talk | contribs)
Jump to: navigation, search
语言: [[::KMAPI|English]]  • [[::KMAPI/zh-hans|中文（简体）‎]]

概述

KMAPI软件包允许您使用流行的编程语言（例如基于TCP / IP和UDP的Visual Basic）与softMC进行通信。 KMAPI通过TCP / IP连接完全访问系统的命令行界面。通过UDP连接（也称为UDP快速数据）提供快速访问频繁更改的数据（如轴设定点和反馈）。

您可以在here查看完整的KMAPI文档。

介绍

当KMAPI驱动器和控制器连接您的程序时，KMAPI解决了几个问题，包括：

  • 发送命令（和接收响应）
  • 读取和设置放大器或控制器变量
  • 发送和检索文件
  • 错误处理

KMAPI通过提供功能库来解决这些问题，允许用户根据设备（放大器，控制器，轴，组）来描述系统，然后单独与这些设备进行通信。
KMAPI的核心是设备表的概念。 设备表是由KMAPI为用户管理的数据存储（数据库。
设备表由程序员填充设备，允许程序员在设备表中的任何设备上执行命令。 使用的通信技术的大部分细节是隐藏的，使程序员专注于高级编程而不是通信协议。

一般信息

KMAPI可用于Windows NT，并兼容各种32位编程工具，包括Microsoft Visual Basic和Microsoft Visual C ++。
KMAPI作为Windows DLL提供，可以被大多数Windows编程语言访问。
大多数KMAPI函数返回一个错误代码，指示程序员请求的操作成功。 错误的全文描述通常与错误相关联，可以通过KMAPI调用进行访问。

入门

以下C＃代码是执行以下任务的最小控制台应用程序：

  • 初始化库
  • 创建'控制器' - 用于通信的软件组件
  • 发送命令并读取响应
  • 关闭通信

该软件以C＃编写，并使用KMAPI.DLL与KMTCPIP.EXE通信服务器进行通信，等效的C ++ / C程序将看起来几乎相同，但必须使用KMAPI32.DLL。


注意：使用这些:

  1. 添加对kmapi.dll引用到您的项目
  2. 参数1的形式应为："IP:10.4.20.55,5004" - 'IP:'，IP设置为mc地址，端口可以为5001/4 /
  3. 参数2是一个MC命令，首先尝试一个简单的命令，如"?ver"
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace KMAPIDemo {
  class Program {
    private static IntPtr device = IntPtr.Zero;

    static void Main(string[] args) {
      if (args.Length != 2)
        return;
      string ipAddress = args[0];
      string cmdToExecute = args[1];
      // *******************************
      // *** initialize and connect ***
      // *******************************
      int retVal = KMAPI.IKMInitialize(); // Initialize the API
      if (retVal != 0) {// if fail
        Console.WriteLine(string.Format("Error: Connection error (IKMInitialize): {0}", retVal));
        return;     // fail
      }
      uint connectionType = 7;  // COMM_TCPIP_DEDICATED = 7 - dedicated device => pre defined ip address
      try {
        device = KMAPI.IKMCreateController(KMAPI.PROD_GPMAC,
            "someName", // dummy
            connectionType,
            1,
            ipAddress);
      } catch (Exception e) {
        KMAPI.IKMTerminate();
        Console.WriteLine(string.Format("Error: Connection error (IKMCreateController): {0}", e.Message));
        return;
      }
      if (device == IntPtr.Zero) {  // if fail
        KMAPI.IKMTerminate();
        Console.WriteLine("Error: Connection error (IKMCreateController): device = 0");
        return;
      }
      // *******************************
      // *** Execute some commands ***
      // *******************************
      const int BuffSz = 100000;
      char[] responseBuff = new char[BuffSz];
      retVal = KMAPI.IKMExecuteCmdResponse(device, cmdToExecute, responseBuff, BuffSz);
      if (retVal != 0)  // fail
        Console.WriteLine("failed");
      else {
        string response = new string(responseBuff);
        int idx0 = response.IndexOf("\0");
        if (idx0 > 0)
          response = response.Substring(0, idx0);
        Console.WriteLine(string.Format("Command '{0}' => response '{1}'", cmdToExecute, response));
      }
      // *****************
      // *** shut down ***
      // *****************
      retVal = KMAPI.IKMDestroyDevice(device); // terminate KMAPI
      if (retVal != 0) {  // if fail
        Console.WriteLine("Error when destroying device");
        return;   // fail
      }
      device = IntPtr.Zero;
      retVal = KMAPI.IKMTerminate();
      if (retVal != 0) {  // if fail
        Console.WriteLine("Error when terminating");
        return;   // fail
      }

    }
  }
}


错误信息

大多数KMAPI函数返回错误代码。 成功的KMAPI函数返回KM_ERR_OK。 错误发生在设备本身或KMAPI中。
当消息发生在KMAPI内时，返回错误代号，可以将其与KMAPI头文件（C / C ++）或全局文件（Visual Basic）中的错误列表进行比较。
此外，KMAPI还会为可以通过调用KMErrorGetMessage检索的错误分配一条消息。当错误发生在设备（驱动器或控制器）中时，KMAPI“解析”消息，并存储包括设备给出的错误消息和错误代号的相关信息。
可以通过类似于Win32 KMAPI GetLastError函数的KMErrorGetDeviceMessage检索最后一个错误信息。
最后，可以通过KMErrorGetOriginalDeviceMessage检索作为最初发送错误消息的文本的设备。

发送/检索文件

为了发送和检索文件，KMAPI分别为用户提供KMPutFile和KMGetFile两种功能。
除了设备句柄参数之外，当调用这些函数之一时，必须发送文件的路径和实际命令。

高级异步消息处理

一些控制器和驱动器生成与特定命令无关的消息，称为异步消息。
异步消息的一些示例是超速警告，限制开关闭合和来自softMC任务的运行时错误消息。
收到这些消息后，KMAPI将它们转换成Windows消息（事件），程序员可以请求将其发送到其应用程序。 默认情况下，KMAPI在模态对话框（通过Win32 MessageBox功能）中显示每个异步消息。
如果程序员想要不同地处理这些消息，则KMAsyncSetHandlerKMAPI功能允许将窗口注册为这些消息的目的地。
可以使用KMAsyncGetHandler保存以前的错误处理程序，程序员可以根据需要恢复它。 像所有Windows消息一样，WM_KM_ASYNC有两个参数：wParam和lParam。
lParam包含缓冲区的句柄，其中包含KMAPI接收到的异步消息。
程序员可以使用KMAsyncGetMessage从KMAPI获取异步消息。

异步消息和Microsoft Visual Basic

Visual Basic不提供直接处理Windows消息的简单机制。
为了克服这个限制，提供了一种称为KMAPI的自定义控件，其具有表示异步消息的接收的事件。
窗体上放置该控制自动初始化KMAPI(KMInitialize)并注册为异步消息的形式。

库参考

KMAPI初始化

KMInitialize

准备使用KMAPI:

C/C++ KMErrorCode KMInitialize ( void )
Visual Basic KMInitialize() As Long
C# System.Int32 IKMInitialize ()



返回值 如果成功初始化KMAPI，KM_ERR_OK。如果不能创建异步消息窗口，KM_ERR_WINDOWS_API。
如果应用程序上下文未成功创建， KM_ERR_MEM_LOCK。
备注 在调用任何其他KMAPI函数之前，必须调用KMInitialize函数。
参见 KMTerminate
例子 参考 Example #1

KMTerminate

为执行正确的应用程序终止清理所需的KMAPI。


C/C++ KMErrorCode KMTerminate ( void )
Visual Basic KMTerminate() As Long
C# IKMInitialize ()



返回值 如果KMAPI成功终止，KM_ERR_OK。如果应用程序上下文不能被锁定或删除，KM_ERR_MEM_LOCK。
如果在应用程序上下文注册表中找不到应用程序上下文，KM_ERR_NO_CONTEXT。
备注 必须在使用KMAPI终止的应用程序前调用KMTerminate函数。
参见 KMInitialize
例子 参考 Example #1

设备管理

KMCreateController

C/C++ KMDevice KMCreateController (KMProductType controllerProduct, LPSTR controllerName, KMCommType controllerCommType, short controllerID, LPSTR commOptions)
Visual Basic KMCreateController (ByVal controllerProduct As Integer, ByVal controllerName$, ByVal controllerCommType As Integer, ByVal controllerID As Integer, ByVal commOptions$) As Long
C# System.IntPtr IKMCreateController (System.UInt32 controllerProduct, System.String controllerName, System.UInt32 controllerCommType, System.UInt32 controllerID, System.String commOptions)



controllerProduct 要创建的控制器的类型
controllerName 控制器的字符串名称
controllerCommType API如何与控制器通信（请参阅通讯类型说明）
controllerID 控制器的地址
commOptions 控制器使用的COM端口
返回值 指向控制器的句柄。
备注 controllerProduct查看产品类型说明.
controllerName是为了方便用户而提供的，KMAPI不在内部使用
controllerCommType查看通信类型说明.
commOptions是一个通用参数，用于许多用途。 目前，只有类型COMM_TCPIP的连接使用此参数。 如果选择了COMM_TCPIP，则commOptions参数允许用户通过IP地址，控制器名称，序列号或DIP开关设置指定要连接的控制器。
commOptions的格式如下:
  • “IP: xx.xx.xx.xx”其中xx.xx.xx.xx是IP地址（例如“192.10.34.6”）。
  • “NM: yyyyy”其中yyyyy是由用户分配给控制器的Sys.Name属性的名称
  • “SN：XXXXX-XXX”，其中XXXXX-XXX是出厂时分配给控制器的序列号，并打印在型号标签上。
  • “DP：XXXXXX”，其中XXXXXX是支持的控制器上DIP开关设置的值（十进制）。 这对用户配置地址很有用。

当通过串口连接时，IP地址总是被指定为91.0.0.2。
如果不使用commOptions，则该参数应为空字符串（“”）。
KMCreateController代表用户分配内存。 必须通过KMDestroyDevice在程序终止前释放该内存。
controllerDevice的范围为1 - 9

参见 ____
例子 参考 Example #1

设备访问

KMExecuteCmd

向设备发送命令。


C/C++ KMErrorCode KMExecuteCmd (KMDevice device, LPSTR cmdStr)
Visual Basic KMExecuteCmd (ByVal device As Long, ByVal cmdStr$) As Long
C# System.Int32 IKMExecuteCmd (System.IntPtr device , System.String cmdStr)



device 处理正在发送命令的设备
cndStr 发送命令。
返回值 如果命令成功发送，KM_ERR_OK
备注 将未修改命令cmdStr发送到由设备指定的设备。 应该与没有响应的命令一起使用。
参见 KMExecuteCmdResponse
例子 See Example #1

KMExecuteCmdResponse

向设备发送命令并等待响应。

C/C++ KMErrorCode KMExecuteCmdResponse (KMDevice device, LPSTR cmdStr, LPSTR outStr, DWORD outSize)
Visual Basic KMExecuteCmdResponse (ByVal device As Long, ByVal cmdStr$, ByVal outStr$, ByVal outSize As Long) As Long
C# System.Int32 IKMExecuteCmdResponse (System.IntPtr device , System.String cmdStr , char[] outStr , System.UInt32 outSize)



device 处理正在发送命令的设备。
cndStr 发送的命令
outStr 缓冲区的响应。
outSize outStr缓冲区的大小。
返回值 如果命令成功发送，KM_ERR_OK
备注 将未修改的命令cmdStr发送到 设备 指定的设备。 应该与具有响应的命令一起使用。
参见 KMExecuteCmd
例子 See Example #1

Example #1

该程序显示如何初始化KMAPI，在每个设备上创建设备和访问变量。

C/C++ example 1.1.png
Visual Basic example 1.2.png

KMGetFile

从设备检索文件。


C/C++ KMErrorCode KMGetFile (KMDevice device, LPSTR cmdStr, LPSTR filename)
Visual Basic KMGetFile (ByVal device As Long, ByVal cmdStr$, ByVal filename$) As Long
C# System.Int32 IKMGetFile (System.IntPtr device, System.String cmdStr, System.String fileName)



device 处理正在检索的设备文件。
cmdStr 用于使设备发送文件的命令字符串。
filename 将文件保存到主机上的文件名。
返回值 如果命令成功发送，KM_ERR_OK
备注 cmdStr和filename参数中的文件名（如果有的话）不一定要匹配。
参见 KMPutFile
例子 参考 Example #2

KMPutFile

将文件发送到设备。


C/C++ KMErrorCode KMPutFile (KMDevice device, LPSTR cmdStr, LPSTR filename)
Visual Basic KMPutFile(ByVal device As Long, ByVal cmdStr$, ByVal filename$) As Long
C# System.Int32 IKMPutFile (System.IntPtr device, System.String cmdStr, System.String fileName)



device 处理正在发送文件的设备
cmdStr 用于使设备检索文件的命令字符串
filename 主机上文件的文件名
返回值 如果命令成功发送，KM_ERR_OK
备注 cmdStr和filename参数中的文件名（如果有的话）不一定要匹配。
参见 KMGetFile
例子 参考 Example #2

Example #2

该程序显示如何通过KMAPI向/从设备（控制器或放大器）发送和检索文件。

C/C++ example 2.1.png
Visual Basic example 2.2.png

错误处理

错误处理是创建健壮性应用程序的最重要元素之一。
KMAPI提供全面的错误处理，允许程序员正确处理所有情况。使用KMAPI错误可能会发生在以下阶段：

  • KMAPI内部
    • 主机耗尽内存
  • API和设备之间的通信
    • 设备无法及时响应
  • 设备内部
    • 由于限位开关打开，不能进行移动

KMAPI中的每个功能都返回一个结果，几乎总是类型为KMErrorCode（Visual Basic用户的Long）。 每个错误类型都在错误代码中很好地识别。
以下是处理从KMAPI返回的错误的正确方法的示例:

C/C++ error 1.1.png
Visual Basic error 1.2.png

错误代码

以下是KMAPI可以返回的错误代码的列表。


Error code Description Value (hex)
KM_ERR_OK H00000000
KM_ERR_BAD HFFFFFFFF
KM_ERR_BAD_CRC H00800001
KM_ERR_TIME_OUT H00800002
KM_ERR_BAD_DEVICE_ID H00800003
KM_ERR_DEVICE_NOT_INSTALLED H00800004
KM_ERR_LOCK_FAILED H00800005
KM_ERR_NO_DATA H00800006
KM_ERR_ASYNC H00800008
KM_ERR_FAIL_SEND_MSG H00800009
KM_ERR_FAIL_ACK_NAK H0080000A
KM_ERR_FAIL_ACCEPT H0080000B
KM_ERR_FAIL_PROTOCOL H0080000C
KM_ERR_FAIL_RESPOND H0080000D
KM_ERR_UNKNOWN_MESSAGE H0080000E
KM_ERR_MEM_LOCK H0080000F
KM_ERR_FAIL_CREATE_FILE H00800010
KM_ERR_FAIL_OPEN_FILE H00800011
KM_ERR_FAIL_FIND_FILE H00800012
KM_ERR_UNEXPECTED_EOF H00800013
KM_ERR_NO_CONTEXT H00800014
KM_ERR_MEM_ALLOC H00800015
KM_ERR_INVALID_PRODUCT H00800016
KM_ERR_SYSTEM H00800017
KM_ERR_FAIL_FIND_NAME H00800018
KM_ERR_INVALID_TYPE H00800019
KM_ERR_NO_DEFAULT H0080001A
KM_ERR_NO_MAX_MIN H0080001B
KM_ERR_BAD_IRQ_NUMBER H0080001C
KM_ERR_INVALID_FORMAT H0080001D
KM_ERR_NOT_IMPLEMENTED H0080001E
KM_ERR_FAIL_FIND_MSG H0080001F
KM_ERR_NOT_DEVICE H00800020
KM_ERR_FAILED_OPEN_DEVICE H00800021
KM_ERR_INVALID_VALUE H00800022
KM_ERR_INVALID_DEVICE_CONTEXT H00800023
KM_ERR_GROUP_MAX_EXCEEDED H00800024
KM_ERR_AXIS_ALREADY_IN_GROUP H00800025
KM_ERR_FAIL_FIND_DEVICE H00800026
KM_ERR_FAIL_WRITE_FILE H00800027
KM_ERR_FAIL_READ_FILE H00800028
KM_ERR_CONFIG_ALREADY_EXISTS H00800029
KM_ERR_DEVICE_ALREADY_EXISTS H0080002A
KM_ERR_FAIL_PRODUCT_DLL H0080002B
KM_ERR_WINDOWS_API H0080002C
KM_ERR_VARIABLE_NOT_FOUND H0080002D
KM_ERR_SERIAL_FRAMING H0080002E
KM_ERR_FAILED_CLOSE_DEVICE H0080002F
KM_ERR_FAIL_PRODUCT_DLL H00800030
KM_ERR_SYNTAX_ERROR H00800100
KM_ERR_SSMC_ERROR H00030027
KM_ERR_SERVOSTAR_ERROR H00010027
KM_ERR_SSMC_DRIVER_ERROR H00040027

KMErrorGetMessage

获取与错误代码相关的错误消息的文本。


C/C++ KMErrorCode KMErrorGetMessage (KMErrorCode errCode, LPSTR buf, short bufLen)
Visual Basic KMErrorGetMessage (ByVal errCode As Long, ByVal buf$, ByVal bufLen As Integer) As Long
C# System.Int32 IKMErrorGetMessage (System.Int32 errCode, char[] buf, System.UInt32 bufLen)



errCode 获取消息的错误代码
buf 用于存储错误消息的字符数组缓冲区
bufLen buf数组长度
返回值 如果命令成功发送，KM_ERR_OK
备注 返回的文本是依赖于设备的，不会以任何方式进行转换。
如果返回多行文本，将用换行符（'\ n'）分隔行。
参见 KMErrorGetDeviceMessage, KMErrorGetOriginalDeviceMessage
例子 参考 Example #3

KMErrorGetDeviceMessage

获取最后设备错误的原始文本和错误编号。

C/C++ KMErrorCode KMErrorGetDeviceMessage (KMErrorCodePtr pErrCode, LPSTR buf, short bufLen)
Visual Basic KMErrorGetDeviceMessage (pErrCode As Long, ByVal buf$, ByVal bufLen As Integer) As Long
C# System.Int32 IKMErrorGetDeviceMessage (System.IntPtr pErrCode, char[] buf, System.UInt32 bufLen)



pErrCode 指向变量存储最后一个错误编号的指针
buf 字符阵列缓冲区用于设备错误消息
bufLen buf数组长度
返回值 如果命令成功发送，KM_ERR_OK
备注 最后的设备错误存储在每个应用程序上下文的基础上。
返回的文本是依赖于设备的，不会以任何方式进行转换。
如果返回多行文本，将用换行符（'\ n'）分隔行。
参见 KMErrorGetMessage, KMErrorGetOriginalDeviceMessage
例子 See Example #3

KMErrorGetOriginalDeviceMessage

从缓冲区检索整个原始错误消息。


C/C++ KMErrorCode KMErrorGetOriginalDeviceMessage (LPSTR buf, short bufLen)
Visual Basic KMErrorGetOriginalDeviceMessage (ByVal buf$, ByVal bufLen As Integer) As Long
C# System.Int32 IKMErrorGetOriginalDeviceMessage (char[] buf, System.UInt32 bufLen)



buf 用于存储错误消息的字符数组缓冲区
bufLen buf数组长度
返回值 如果命令成功发送，KM_ERR_OK
备注 返回的文本是生成并存储在缓冲区中的原始错误消息
参见 KMErrorGetMessage, KMErrorGetDeviceMessage
例子 参考 Example #3

Example #3

此程序显示如何获取与任何错误编号或发生的最后一个错误相关联的文本说明。

C/C++ example 3.1.png
Visual Basic example 3.2.png
Retrieved from "http://softmc.servotronix.com/index.php?title=KMAPI/zh-hans&oldid=129677"