Polaris Basic Methods

Typedefs
typedef NDIErrorCallback	PLErrorCallback

Functions
static char *	plDeviceName (int i)
static int	plProbe (const char *device)
static polaris *	plOpen (const char *device)
static void	plClose (polaris *pol)
static void	plSetThreadMode (polaris *pol, int mode)
static char *	plCommand (polaris *pol, const char *format,...)
static char *	plCommandVA (polaris *pol, const char *format, va_list ap)
static void	plSetErrorCallback (polaris *pol, PLErrorCallback callback, void *userdata)

Detailed Description

These are the primary set of methods for communicating with the POLARIS.

Typedef Documentation

typedef NDIErrorCallback PLErrorCallback

Error callback type for use with plSetErrorCallback().

Function Documentation

static void plClose ( polaris *  pol )

static

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

static char* plCommand ( polaris *  pol, const char *  format,   ...  )

static

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

Parameters

pol	pointer to a valid POLARIS object
format	a printf-style format string
...	format arguments as per the format string

Returns

the text reply from POLARIS with CRC chopped off

The standard format of a POLARIS 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 POLARIS.

This function will automatically recogize certain commands and behave accordingly:

• NULL - A serial break will be sent to the POLARIS.
• "COMM:" - After the COMM is sent, the host computer serial port is adjusted to match the POLARIS.
• "INIT:" - After the INIT is sent, communication will be paused for 100ms.
• "GX:" - The information returned by the GX command is stored and can be retrieved though the plGetGX() functions.
• "PSTAT:" - The information returned by the PSTAT command is stored and can be retrieved through one of the plGetPSTAT() functions.
• "SSTAT:" - The information returned by the SSTAT command is stored and can be retrieved through one of the plGetSSTAT() functions.
• "IRCHK:" - The information returned by the IRCHK command is stored and can be retrieved through the plGetIRCHK() functions.

The plGetError() function can be used to check whether an error occured or, alternatively, plSetErrorCallback() 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 POLARIS. These are listed in Polaris Command Macros.

static char* plCommandVA ( polaris *  pol, const char *  format, va_list  ap  )

static

This function is identical in behaviour to plCommand(), 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".

static char* plDeviceName ( int  i )

static

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.

static polaris* plOpen ( const char *  device )

static

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

Parameters

device

name of a valid serial port device

Returns

pointer to a polaris object, or zero if device couldn't be opened

static int plProbe ( const char *  device )

static

Probe for the polaris on the specified device. This will take 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 "Polaris"
6. restore the device to its previous state and close the device.

Parameters

device

name of a valid serial port device

Returns

one of:

• PL_OKAY - probe was successful
• PL_OPEN_ERROR - couldn't open the device
• PL_BAD_COMM - device file is probably not a serial port
• PL_WRITE_ERROR - I/O error while writing to the device
• PL_READ_ERROR - I/O error while reading from device
• PL_TIMEOUT - timeout while waiting for data
• PL_PROBE_FAIL - POLARIS not found on this serial port

static void plSetErrorCallback ( polaris *  pol, PLErrorCallback  callback, void *  userdata  )

static

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

Parameters

pol	pointer to a valid POLARIS object
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

static void plSetThreadMode ( polaris *  pol, int  mode  )

static

Set up multithreading to increase efficiency.

Parameters

pol	pointer to a valid POLARIS object
mode	1 to turn on threading, 0 to turn off threading

It can take milliseconds or even tens of milliseconds for the POLARIS to return the transform data after a 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 commands to the POLARIS and wait for the reply. Then the application can continue to execute and simply pick up the GX reply when the POLARIS has finished sending it.

When the thread mode is set, every time the application sends a GX command to the POLARIS during tracking mode the spawned thread will automatically begin resending the GX command as fast as possible. Then when the application sends the next GX 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 command, then the thread will begin sending GX commands with the new reply format.