KMotionDLL
CKKMotionDLL(int board);
Creates a CKMotionDLL object to be used to communicate to a specific board.
board
specifies which board in the system the object is associated with
int WriteLine(const char *s);
Writes a null terminated string of characters to a specified KMotion Board. There is no wait for any response.
Return Value
0 if successful, non-zero if unsuccessful (invalid board specified)
Parameters
s
Null terminated string to send
Example
#include "KMotionDll.h"
CKMotionDLL KM(0);
if (KM.WriteLine("Move0=1000") MyError();
int WriteLineReadLine(const char *s, char *response);
Writes a null terminated string of characters to a specified KMotion Board. Waits for a response string. This command is thread safe. It waits for the token for the specified board, sends the command, waits for the response, then releases the board.
Return Value
0 if successful, non-zero if unsuccessful (invalid board specified, timeout on the response)
Parameters
s
Null terminated string to send
response
Buffer to receive the null terminated string received as response
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
char resp[256];
while (1)
{
if (KM.WriteLineReadLine(0, "CheckDone0",resp) MyError();
if (strcmp(resp,"1")==0) break;
}
int ReadLineTimeOut(char *buf, int TimeOuts);
Waits for a response string from a previously issued command. Note in a multi-process or multi thread environment the KMotion board should be locked prior to issuing a command that has a response(s), Otherwise there is a possibility that another process or thread may receive the expected response.
Return Value
0 if successful, non-zero if unsuccessful (invalid board specified, timeout on the response)
Parameters
buf
Buffer to receive the Null terminated string received as response
TimeOutms
Amount of time to receive a response
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
char resp1[256];
char resp2[256];
char resp3[256];
// first get the token for the board to allow uninterrupted access
if (KM.WaitToken()!=KMOTION_LOCKED) MyError();
// tell the board to send 24 (32 bit) words at offset 0
if (KM.WriteLine("GetGatherHex 0 24")) MyError();
// receive the data (8 hex words per line)
if (KM.ReadLineTimeout(resp1)) MyError();
if (KM.ReadLineTimeout(resp2)) MyError();
if (KM.ReadLineTimeout(resp3)) MyError();
// release our access to the board
KM.ReleaseToken();
int WaitToken();
Waits until the token for the specified KMotion board can be obtained. Call this function whenever uninterrupted access to a KMotion board is required. For example before a command where several lines of response will be returned. Release the token as quickly as possible by calling the ReleaseToken function as all other access to the locked board will be blocked until released.
Return Value
0 if successful, non-zero if unsuccessful (invalid board specified)
Parameters
none
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
char resp1[256];
char resp2[256];
char resp3[256];
// first get the token for the board to allow uninterrupted access
if (KM.WaitToken()!=KMOTION_LOCKED) MyError();
// tell the board to send 24 (32 bit) words at offset 0
if (KM.WriteLine("GetGatherHex 0 24")) MyError();
// receive the data (8 hex words per line)
if (KM.ReadLineTimeout(resp1)) MyError();
if (KM.ReadLineTimeout(resp2)) MyError();
if (KM.ReadLineTimeout(resp3)) MyError();
// release our access to the board
KM.ReleaseToken();
int KMotionLock();
Attempts to obtain the token of the specified KMotion board.. Call this function whenever uninterrupted access to a KMotion board is required. For example before a command where several lines of response will be returned. Release the token as quickly as possible by calling the ReleaseToken function as all other access to the locked board will be blocked until released. This function is similar to the WaitToken function, except that it returns immediately (instead of waiting) if the board is already locked.
Return Value
KMOTION_LOCKED=0, // (and token is locked) if KMotion is available for use
KMOTION_IN_USE=1, // if already in use
KMOTION_NOT_CONNECTED=2 // if error or not able to connect
Parameters
none
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
char resp1[256];
char resp2[256];
char resp3[256];
int result;
// first get the token for the board to allow uninterrupted access
do
{
result = KM.KMotionLock();
if (result == KMOTION NOT CONNECTED) MyError();
if (result == KMOTION IN USE) DoOtherProcessing();
} while
(result != KMOTION_LOCKED)
// receive the data (8 hex words per line)
if (KM.ReadLineTimeout(resp1)) MyError();
if (KM.ReadLineTimeout(resp2)) MyError();
if (KM.ReadLineTimeout(resp3)) MyError();
// release our access to the board
KM.ReleaseToken();
void ReleaseToken();
Releases the previously obtained token of the specified KMotion board. See WaitToken and LockKMotion functions. The token should always be released as quickly as possible as all other access to the locked board will be blocked until released.
Return Value
none - the function can not fail
Parameters
none
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
char resp1[256];
char resp2[256];
char resp3[256];
int result;
// first get the token for the board to allow uninterrupted access
do
{
result = KM.KMotionLock();
if (result == KMOTION NOT CONNECTED) MyError();
if (result == KMOTION IN USE) DoOtherProcessing();
} while
(result != KMOTION_LOCKED)
// tell the board to send 24 (32 bit) words at offset 0
if (KM.WriteLine("GetGatherHex 0 24")) MyError();
// receive the data (8 hex words per line)
if (KM.ReadLineTimeout(resp1)) MyError();
if (KM.ReadLineTimeout(resp2)) MyError();
if (KM.ReadLineTimeout(resp3)) MyError();
// release our access to the board
KM.ReleaseToken();
int Failed();
This function should be called whenever an error is detected with a KMotion board. This function disconnects the driver, flags the board as disconnected, and displays the error message shown below. A user program may typically detect a timeout error or invalid data error if the KMotion board is powered down or unplugged while communication is in progress. Calling this function will force any subsequent attempts to access the board to wait for a board to be connected, re-connect, flush any buffers, etc...
"Read Failed - Auto Disconnect"
Return Value
always 0 - the function can not fail
Parameters
none
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
if (KM.KMotionLock() == KMOTION_LOCKED) // see if we can get access
{
// upload bulk status
if (UploadStatus())
{
// error reading status
KM.Failed();
}
KM.ReleaseRoken();
}
int LoadCoff(int Thread, const char *Name, bool PackToFlash);
This function downloads a compiled C program to the memory of the specified KMotion board.
C Programs that run in the KMotion Board are normally compiled using the included and integrated compiler in the KMotion Application. Using the KMotion Application the user's C Program should be loaded into a selected thread and compiled. This will automatically generate a COFF executable with the same name and in the same directory as the C Source code, but with a .out extension. It is the users responsibility to keep track of which thread the COFF executable was compiled to execute in.
The downloaded code may then be executed by issuing the "Execute" command
Return Value
returns 0 - if successful
Parameters
Thread
KMotion Thread that the program should be loaded into
Name
Filename of coff file to download
PackToFlash
Internal system command always specify as false
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
unsigned int EntryPoint;
if (KM.LoadCoff(1, "C:\\test.out", false)) return 1;
KM.WriteLine("Execute 0");
int ServiceConsole();
Services the KMotion Console data stream. The Console is a place where all unsolicited data, such as errors, or data "Printed" by user programs goes to. In between processing commands, KMotion uploads any unsolicited data it may have up to the host. The KMotionDLL driver buffers this data until some process declares itself as a Console Handler (See SetConsoleCallback) and makes calls to this function ServiceConsole.
This function should be called at regular intervals. If console data is available a call back to the Console Handler will occur with one line of data.
Return Value
returns 0 - if successful
Parameters
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
int ConsoleHandler(const char *buf)
{
MyLogData(buf);
return 0;
}
KM.SetConsoleCallback(ConsoleHandler);
KM.ServiceConsole();
int SetConsoleCallback(CONSOLE_HANDLER *ch);
Sets the user provided console callback function.
Return Value
returns 0 - if successful
Parameters
ch
name of console handler function
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
int ConsoleHandler(const char *buf)
{
MyLogData(buf);
return 0;
}
.
.
.
KM.SetConsoleCallback(ConsoleHandler);
KM.ServiceConsole();
CompileAndLoadCoff(const char *Name, int Thread);
or
int CompileAndLoadCoff(const char *Name, int Thread, char *Err, int MaxErrLen);
Compiles the specified C Program file, downloads the object code to the specified Thread space, and sets the Entry Point, for the specified thread. Two versions of the function are supplied; one returns any error messages, the other does not.
The downloaded code may then be executed by issuing the Execute command.
Return Value
returns 0 - if successful
Parameters
Name
Filename of C Program to compile and download
Thread
Thread number where the program is to be compiled for and downloaded into. Valid range 1...7.
Err
Caller's supplied buffer for any error messages
MaxErrLen
Length of caller's supplied buffer for any error messages
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
if (KM.CompileAndLoadCoff("C:\\MyProgram.c", 1) MyError();
if (KM.WriteLine("Execute1") MyError();
int ListLocations(int *nlocations, int *list);
Returns the number of currently connected KMotion boards and a list of their USB location identifiers
Return Value
returns 0 - if successful
Parameters
nlocations
pointer to integer where the number of locations should be returned
List
pointer to array to be filled in with the list of USB location identifiers
Example
#include "KMotionDLL.h"
CKMotionDLL KM(0);
int n_boards;>
int BoardList[256];
if (KM.ListLocations(&n_boards, BoardList) MyError();