KMAPI

Overview

The KMAPI software package allows you to communicate with softMC from popular programming languages, such as Visual Basic over TCP/IP and UDP. The KMAPI provides complete access to the command line interface of your system across a TCP/IP connection. Fast access to frequently changing data, such as axis set-points and feedback, is provided via a UDP connection, also called UDP fast data.

Introduction

The KMAPI addresses several concerns when interfacing your program with Kollmorgen drives and controllers, including:

• sending commands (and receiving responses)
• reading and setting amplifier or controller variables
• sending and retrieving files
• error handling

The KMAPI addresses these concerns by providing a library of functions which allow the user to describe their system in terms of devices (amplifiers, controllers, axes, groups) and then communicate with these devices individually.
Central to the KMAPI is the concept of a device table. The device table is a data store (database) which is managed by the KMAPI for the user.
The device table is populated with devices by the programmer, allowing the programmer to execute commands on any device in the device table. Most details of the communication techniques used are hidden allowing the programmer to focus on high level programming instead of communication protocols.

General Information

The KMAPI is available for Windows NT and is compatible with a wide variety of 32-bit programming tools including Microsoft Visual Basic and Microsoft Visual C++.
The KMAPI is provided as a Windows DLL which makes it accessible from most Windows programming languages.
Most KMAPI functions return an error code which indicates the success of the action requested by the programmer. Full text descriptions of the error are often associated with the error and can be accessed via KMAPI calls.

Initialization

The first step in using the KMAPI is to call the initialization function KMInitialize.
This ensures that the information which the KMAPI maintains internally about your application is correct.
No other KMAPI calls should be made before the KMAPI is initialized.

Error Messages

Most of the KMAPI functions return an error code. Successful KMAPI functions return KM_ERR_OK. Errors originate in the device itself or the KMAPI.
When the message originates within the KMAPI, an error number is returned which can be compared against the list of errors in the KMAPI header files (C/C++), or the global files (Visual Basic).
In addition the KMAPI also assigns a text message to the error which can be retrieved by calling KMErrorGetMessage. When the error originates in the device (drive or controller) the KMAPI “parses” the message and stores the relevant information including the error message and the error number as given by the device.
This information can be retrieved for the last error via KMErrorGetDeviceMessage similar to the Win32 KMAPI GetLastError function.
Finally, the text of the error message, as the device originally sent, can be retrieved via KMErrorGetOriginalDeviceMessage.

Sending/Retrieving Files

For the sending and retrieval of files the KMAPI provides users with two functions, KMPutFile and KMGetFile, respectively.
In addition to the device handle parameter, the path of the file and the actual command must be sent when calling either of these functions.

Advanced asynchronous message handling

Some controllers and drives generate messages not related to a specific command called asynchronous messages.
Some examples of asynchronous messages are overspeed warnings, limit switch closures and runtime error messages from softMC tasks.
When these messages are received the KMAPI converts them into Windows messages (events) which the programmer can request to have delivered to their application.

By default the KMAPI displays each asynchronous message in a modal dialog box (via the Win32 MessageBox function).
If the programmer wants to handle these messages differently the KMAsyncSetHandler KMAPI function allows a window to be registered as the destination for these messages.
KMAsyncGetHandler can be used to save the previous error handler to that the programmer can restore it on demand.

Like all Windows messages, WM_KM_ASYNC has two parameters, wParam and lParam.
lParam contains a handle to the buffer which contains the asynchronous message as received by the KMAPI.
The programmer can use KMAsyncGetMessage to get the asynchronous message from the KMAPI.

Asynchronous messages and Microsoft Visual Basic

Visual Basic does not provide an easy mechanism for directly handling Windows messages.
In order to overcome this limitation a custom control called KMAPI has been provided which has an event representing the receipt of an asynchronous message.
Placing this control on your form automatically initializes the KMAPI (KMInitialize) and registers the form for asynchronous messages.

Library Reference

KMAPI Initialization

KMInitialize

Prepares the KMAPI for use:

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

Return Value	KM_ERR_OK if KMAPI is successfully initialized. KM_ERR_WINDOWS_API if the asynchronous message window can’t be created. KM_ERR_MEM_LOCK if the application context was not successfully created.
Remarks	The KMInitialize function must be called before any other KMAPI functions are called.
See Also	KMTerminate
Example	See Example #1

KMTerminate

Performs KMAPI cleanup required for proper application termination.

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

Return Value	KM_ERR_OK if KMAPI is successfully terminated. KM_ERR_MEM_LOCK if the application context cannot be locked or removed. KM_ERR_NO_CONTEXT if the application context cannot be found in the application context registry.
Remarks	The KMTerminate function must be called before the application using the KMAPI terminates.
See Also	KMInitialize
Example	See Example #1

Device Management

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	Type of controller to create
controllerName	String name for the controller
controllerCommType	How the API should communicate with the controller (see communication type description)
controllerID	What the controller’s address is
commOptions	COM port used by the controller
Return Value	A handle referring to the controller.
Remarks	See product type description for controllerProduct. controllerName is provided for user convenience and is not used internally by the KMAPI. See communication type description for controllerCommType. commOptions is a general parameter that is intended for many uses. Presently, only connections of type COMM_TCPIP use this parameter. If COMM_TCPIP is selected then the commOptions parameter allows the user to specify what controller to connect to by IP address, controller name, serial number or DIP switch setting. The format for commOptions is as follows: “IP: xx.xx.xx.xx” where xx.xx.xx.xx is an IP address (e.g. “192.10.34.6”). “NM: yyyyy” where yyyyy is a name assigned by the user to the Sys.Name property of the controller. “SN: XXXXX-XXX” where XXXXX-XXX is the serial number assigned to the controller at the factory and printed on the model number label. “DP: XXXXXX” where XXXXXX is the value (in decimal) of the DIP switch setting on controllers that support. This is useful for user configuration of addresses. When connecting via serial the IP address should is always be specified as 91.0.0.2. If commOptions is not used, the parameter should be an empty string (“”). KMCreateController allocates memory on behalf of the user. This memory must be freed before program termination via KMDestroyDevice. The range for controllerDevice is 1 - 9.
See Also	____
Example	See Example #1

Device Access

KMExecuteCmd

Sends a command to a device.

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	Handle for the device the command is being sent to.
cndStr	The command to send.
Return Value	KM_ERR_OK if command is successfully transmitted
Remarks	Sends the command cmdStr unmodified to the device specified by device. Should be used with commands that do not have responses.
See Also	KMExecuteCmdResponse
Example	See Example #1

KMExecuteCmdResponse

Sends a command to a device and waits for a response.

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	Handle for the device the command is being sent to.
cndStr	The command to send.
outStr	A buffer for the response.
outSize	Size of the outStr buffer.
Return Value	KM_ERR_OK if command is successfully transmitted
Remarks	Sends the command cmdStr unmodified to the device specified by device. Should be used with commands that have responses.
See Also	KMExecuteCmd
Example	See Example #1