KMotion Quick Reference | KMotionDLL
Send Commands WriteLine WriteLineReadLine ReadLineTimeOut Board Locks WaitToken KMotionLock ReleaseToken Failed Console ServiceConsole SetConsoleCallback Coff Loader LoadCoff C ompiler 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();