Core Interface Methods

Typedefs
typedef void(*	NDIErrorCallback )(int errnum, char *description, void *userdata)

Functions
char *	ndiDeviceName (int i)
int	ndiProbe (const char *device)
ndicapi *	ndiOpen (const char *device)
void	ndiClose (ndicapi *pol)
void	ndiSetThreadMode (ndicapi *pol, int mode)
char *	ndiCommand (ndicapi *pol, const char *format,...)
char *	ndiCommandVA (ndicapi *pol, const char *format, va_list ap)
void	ndiSetErrorCallback (ndicapi *pol, NDIErrorCallback callback, void *userdata)

Detailed Description

These are the primary set of methods for communicating with tracking devices from NDI that follow the NDI Combined Application Programmers' Interface.

Typedef Documentation

typedef void(* NDIErrorCallback)(int errnum, char *description, void *userdata)

Error callback type for use with ndiSetErrorCallback().

Function Documentation

void ndiClose

(

ndicapi *

pol

)

Close communication with the NDI device. You should send a "COMM:00000" command before you close communication so that you can resume communication on a subsequent call to ndiOpen() without having to reset the NDI device.

Returns

a handle for an NDI device, or zero if device could not be opened

char* ndiCommand	(	ndicapi *	pol,
		const char *	format,
			...
	)

Send a command to the device using a printf-style format string.

Parameters

pol	valid NDI device handle
format	a printf-style format string
...	format arguments as per the format string

Returns

the text reply from the device with the CRC chopped off

The standard format of an NDI API command is, for example, "INIT:" or "PENA:AD". A CRC value and a carriage return will be appended to the command before it is sent to the device.

This function will automatically recogize certain commands and behave accordingly:

• NULL - A serial break will be sent to the device.
• "COMM:" - After the COMM is sent, the host computer serial port is adjusted to match the device.
• "INIT:" - After the INIT is sent, communication will be paused for 100ms.
• "PHSR:" - The information returned by the PHSR command is stored and can be retrieved though the ndiGetPHSR() functions.
• "PHINF:" - The information returned by the PHINF command is stored and can be retrieved though the ndiGetPHINF() functions.
• "TX:" - The information returned by the GX command is stored and can be retrieved though the ndiGetTX() functions.
• "GX:" - The information returned by the GX command is stored and can be retrieved though the ndiGetGX() functions.
• "PSTAT:" - The information returned by the PSTAT command is stored and can be retrieved through one of the ndiGetPSTAT() functions.
• "SSTAT:" - The information returned by the SSTAT command is stored and can be retrieved through one of the ndiGetSSTAT() functions.
• "IRCHK:" - The information returned by the IRCHK command is stored and can be retrieved through the ndiGetIRCHK() functions.

The ndiGetError() function can be used to check whether an error occured or, alternatively, ndiSetErrorCallback() can be used to set a function that will be called whenever an error occurs.

For convenience, there is a set of macros for sending commands to the devices. These are listed in Command Macros.

char* ndiCommandVA	(	ndicapi *	pol,
		const char *	format,
		va_list	ap
	)

This function is identical in behaviour to ndiCommand(), except that it accepts a va_list instead of an argument list. The use of va_list is described in the standard C header file "stdarg.h".

char* ndiDeviceName

(

int

i

)

This function will return the name of the i th serial port device, i.e. i = 0 gives "COM1:" on Windows and "/dev/ttyS0" on linux.

Parameters

i	integer between 0 and 3

Returns

the name of a serial port device or 0

If i is too large, the return value is zero.

ndicapi* ndiOpen

(

const char *

device

)

Open communication with the NDI device on the specified serial port device. This also sets the serial port parameters to (9600 baud, 8N1, no handshaking).

Parameters

device

name of a valid serial port device

Returns

1 if an NDI device was found on the specified port, 0 otherwise

int ndiProbe

(

const char *

device

)

Probe for an NDI device on the specified serial port device. This will perform the following steps:

1. save the status of the device (baud rate etc)
2. open the device at 9600 baud, 8 data bits, no parity, 1 stop bit
3. send an "INIT:" command and check for the expected reply
4. if the "INIT:" failed, send a serial break and re-try the "INIT:"
5. if the "INIT:" succeeds, send "VER:0" and check for response.
6. restore the device to its previous state and close the device.

Parameters

device

name of a valid serial port device

Returns

one of:

• NDI_OKAY - probe was successful
• NDI_OPEN_ERROR - couldn't open the device
• NDI_BAD_COMM - device file is probably not a serial port
• NDI_WRITE_ERROR - I/O error while writing to the device
• NDI_READ_ERROR - I/O error while reading from device
• NDI_TIMEOUT - timeout while waiting for data
• NDI_PROBE_FAIL - the device found was not an NDI device

void ndiSetErrorCallback	(	ndicapi *	pol,
		NDIErrorCallback	callback,
		void *	userdata
	)

Set a function that will be called each time an error occurs.

Parameters

pol	valid NDI device handle
callback	a callback with the following signature: void callback(int errnum, char *error_description, void *userdata)
userdata	data to send to the callback each time it is called

The callback can be set to NULL to erase a previous callback.

void ndiSetThreadMode	(	ndicapi *	pol,
		int	mode
	)

Set up multithreading to increase efficiency.

Parameters

pol	valid NDI device handle
mode	1 to turn on threading, 0 to turn off threading

It can take milliseconds or even tens of milliseconds for the tracking system to return the transform data after a TX or GX command. During this time, the application normally sits idle.

One way to avoid this idle time is to spawn a separate thread to send the GX/TX/BX commands to the device and wait for the replies. This allows the main application thread to continue to execute while the other thread is waiting for a reply from the device.

When the thread mode is set, every time the application sends a GX, TX or BX command to the device during tracking mode the spawned thread will automatically begin resending the GX/TX/BX command as fast as possible. Then when the application sends the next GX/TX/BX command, the thread will simply send the application the most recent reply instead of forcing the application to wait through a full command/reply cycle.

If the application changes the reply mode for the GX, TX or BX command, then the thread will begin sending commands with the new reply format.