KMotion Quick Reference 

KMotionDLL

Send Commands

WriteLine

WriteLineReadLine
ReadLineTimeOut

 

Board Locks

WaitToken

KMotionLock

ReleaseToken

Failed

 

 

Console

ServiceConsole

SetConsoleCallback

 

Coff Loader

LoadCoff

 

Compiler

CompileAndLoadCoff

 

USB

ListLocations

 

CKMotionDLL(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 TimeOutms);

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

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(board);

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.ReleaseToken();
}

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();
 
 
 
int 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();