Table of contents |

## KMotion Quick Reference

### Send Commands

WriteLine

WriteLineReadLine

ReadLineTimeOut

### Board Locks

WaitToken

KMotionLock

ReleaseToken

Failed

### Console

ServiceConsole

SetConsoleCallback

### Coff Loader

LoadCoff

### Compiler

CompileAndLoadCoff

### USB

ListLocations

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