Macros
#define	plRESET(p) plCommand((p),NULL)

#define	plINIT(p) plCommand((p),"INIT:")

#define	plCOMM(p, baud, dps, h) plCommand((p),"COMM:%d%03d%d",(baud),(dps),(h))

#define	plPVWR(p, port, a, x) plCommand((p),"PVWR:%c%04X%.128s",(port),(a),(x))

#define	plPVCLR(p, port) plCommand((p),"PVCLR:%c",(port))

#define	plPINIT(p, port) plCommand((p),"PINIT:%c",(port))

#define	plPENA(p, port, mode) plCommand((p),"PENA:%c%c",(port),(mode))

#define	plPDIS(p, port) plCommand((p),"PDIS:%c",(port))

#define	plTSTART(p) plCommand((p),"TSTART:")

#define	plTSTOP(p) plCommand((p),"TSTOP:")

#define	plGX(p, mode) plCommand((p),"GX:%04X",(mode))

#define	plLED(p, port, led, s) plCommand((p),"LED:%c%d%c",(port),(led),(s))

#define	plBEEP(p, n) plCommand((p),"BEEP:%i",(n))

#define	plVER(p, n) plCommand((p),"VER:%d",(n))

#define	plSFLIST(p, mode) plCommand((p),"SFLIST:%02X",(mode))

#define	plVSEL(p, n) plCommand((p),"VSEL:%d",(n))

#define	plPSTAT(p, format) plCommand((p),"PSTAT:%04X",(format))

#define	plSSTAT(p, format) plCommand((p),"SSTAT:%04X",(format))

#define	plPPRD(p, port, addr) plCommand((p),"PPRD:%c%04X",(port),(addr))

#define	plPPWR(p, port, a, x) plCommand((p),"PPWR:%c%04X%.128s",(port),(a),(x))

#define	plPURD(p, port, addr) plCommand((p),"PURD:%c%04X",(port),(addr))

#define	plPUWR(p, port, a, x) plCommand((p),"PPWR:%c%04X%.128s",(port),(a),(x))

#define	plPSEL(p, port, id) plCommand((p),"PSEL:%c%s",(port),(id))

#define	plPSRCH(p, port) plCommand((p),"PSRCH:%c",(port))

#define	plPVTIP(p, port, tip, np) plCommand((p),"PVTIP:%c%d%d",(port),(tip),(np))

#define	plTTCFG(p, port) plCommand((p),"TTCFG:%c",(port))

#define	plTCTST(p, port) plCommand((p),"TCTST:%c",(port))

#define	plDSTART(p) plCommand((p),"DSTART:")

#define	plDSTOP(p) plCommand((p),"DSTOP:")

#define	plIRINIT(p) plCommand((p),"IRINIT:")

#define	plIRCHK(p, mode) plCommand((p),"IRCHK:%04X",(mode))

#define	plIRED(p, port, sig) plCommand((p),"IRED:%c%08X",(port),(sig))

#define	pl3D(p, port, mode) plCommand((p),"3D:%c%d",(port),(mode))

Functions
static int	plPVWRFromFile (polaris pol, int port, char filename)

Detailed Description

These are a set of macros that send commands to the POLARIS via plCommand().

The plGetError() function can be used to determine whether an error occurred.

The return value is a terminated string containing the reply from the POLARIS with the CRC and final carriage return chopped off.

Macro Definition Documentation

#define pl3D	(	p,
		port,
		mode
	)	plCommand((p),"3D:%c%d",(port),(mode))

Get the 3D position and an error value for a single marker on a tool. The mode should be set to 1 or 3. This command is only available in diagnostic mode.

Parameters

port	the port number: '1', '2' or '3'
mode	see NDI POLARIS documentation

The IRED command should be used to set up a marker firing signature before this command is called.

#define plBEEP	(	p,
		n
	)	plCommand((p),"BEEP:%i",(n))

Cause the POLARIS to beep.

Parameters

n	the number of times to beep, an integer between 1 and 9

A reply of "0" means that the POLARIS is already beeping and cannot service this beep request.

This command can be used in tracking mode.

#define plCOMM	(	p,
		baud,
		dps,
		h
	)	plCommand((p),"COMM:%d%03d%d",(baud),(dps),(h))

Change the POLARIS communication parameters. The host parameters will automatically be adjusted to match. If the specified baud rate is not supported by the serial port, then the error code will be set to PL_BAD_COMM and the POLARIS will have to be reset before communication can continue. Most modern UNIX systems accept all baud rates except 14400, and Windows systems support all baud rates.

Parameters

baud	one of PL_9600, PL_14400, PL_19200, PL_38400, PL_57600, PL_115200
dps	should usually be PL_8N1, the most common mode
h	one of PL_HANDSHAKE or PL_NOHANDSHAKE

#define plDSTART ( p ) plCommand((p),"DSTART:")

Put the POLARIS into diagnostic mode.

#define plDSTOP ( p ) plCommand((p),"DSTOP:")

Take the POLARIS out of diagnostic mode.

#define plGX	(	p,
		mode
	)	plCommand((p),"GX:%04X",(mode))

Request tracking information from the POLARIS. This command is only available in tracking mode.

Parameters

mode

a reply mode containing the following bits:

PL_XFORMS_AND_STATUS 0x0001 - transforms and status
PL_ADDITIONAL_INFO 0x0002 - additional tool transform info
PL_SINGLE_STRAY 0x0004 - stray active marker reporting
PL_FRAME_NUMBER 0x0008 - frame number for each tool
PL_PASSIVE 0x8000 - include information for ports 'A', 'B', 'C'
PL_PASSIVE_EXTRA 0x2000 - with PL_PASSIVE, ports 'A' to 'I'
PL_PASSIVE_STRAY 0x1000 - stray passive marker reporting

The GX command with the appropriate reply mode is used to update the data that is returned by the following functions:

#define plINIT ( p ) plCommand((p),"INIT:")

Initialize the POLARIS. The POLARIS must be initialized before any other commands are sent.

#define plIRCHK	(	p,
		mode
	)	plCommand((p),"IRCHK:%04X",(mode))

Check for sources of environmental infrared. This command is only valid in diagnostic mode after an IRINIT command.

Parameters

mode	reply mode bits: PL_DETECTED 0x0001 - return '1' if IR detected, else '0' PL_SOURCES 0x0002 - locations of up to 20 sources per camera

The IRCHK command is used to update the information returned by the plGetIRCHKDetected() and plGetIRCHKSourceXY() functions.

#define plIRED	(	p,
		port,
		sig
	)	plCommand((p),"IRED:%c%08X",(port),(sig))

Set the infrared firing signature for the specified port. This command is only available in diagnostic mode.

Parameters

port	the active tool port '1', '2' or '3'
sig	a 32-bit integer whose bits specify what IREDS to fire

#define plIRINIT ( p ) plCommand((p),"IRINIT:")

Initialize the diagnostic environmental infrared checking system. This command must be called prior to using the IRCHK command.

#define plLED	(	p,
		port,
		led,
		s
	)	plCommand((p),"LED:%c%d%c",(port),(led),(s))

Set a tool LED to a particular state.

Parameters

port	one of '1', '2' or '3' (active ports only)
led	an integer between 1 and 3
state	desired state: PL_BLANK ('B'), PL_FLASH 'F' or PL_SOLID 'S'

This command can be used in tracking mode.

#define plPDIS	(	p,
		port
	)	plCommand((p),"PDIS:%c",(port))

Disable transform reporting on the specified port.

Parameters

port	one of '1', '2', '3' or 'A' to 'I'

#define plPENA	(	p,
		port,
		mode
	)	plCommand((p),"PENA:%c%c",(port),(mode))

Enable transform reporting on the specified port.

Parameters

port	one of '1', '2', '3' or 'A' to 'I'
mode	one of PL_STATIC 'S', PL_DYNAMIC 'D' or PL_BUTTON_BOX 'B'

#define plPINIT	(	p,
		port
	)	plCommand((p),"PINIT:%c",(port))

Initialize the specified port.

Parameters

port	one of '1', '2', '3' or 'A' to 'I'

#define plPPRD	(	p,
		port,
		addr
	)	plCommand((p),"PPRD:%c%04X",(port),(addr))

Read the tool SROM. Use plHexDecode() to convert reply to binary.

#define plPPWR	(	p,
		port,
		a,
		x
	)	plCommand((p),"PPWR:%c%04X%.128s",(port),(a),(x))

Write the tool SROM. Use plHexEncode() to convert data to a hex string.

#define plPSEL	(	p,
		port,
		id
	)	plCommand((p),"PSEL:%c%s",(port),(id))

Select an SROM target by ID.

#define plPSRCH	(	p,
		port
	)	plCommand((p),"PSRCH:%c",(port))

Search for available SROM targets.

#define plPSTAT	(	p,
		format
	)	plCommand((p),"PSTAT:%04X",(format))

Ask the POLARIS for information about the tool ports.

Parameters

format

a reply format mode composed of the following bits:

PL_BASIC 0x0001 - get port status and basic tool information
PL_TESTING 0x0002 - get current test for active tools
PL_PART_NUMBER 0x0004 - get a 20 character part number
PL_ACCESSORIES 0x0008 - get a summary of the tool accessories
PL_MARKER_TYPE 0x0010 - get the tool marker type
PL_PASSIVE 0x8000 - include information for ports 'A', 'B', 'C'
PL_PASSIVE_EXTRA 0x2000 - with PL_PASSIVE, ports 'A' to 'I'

The use of the PSTAT command with the appropriate reply format updates the information returned by the following commands:

int plGetPSTATPortStatus(polaris *pol, int port)
int plGetPSTATToolInfo(polaris *pol, int port, char information[30])
unsigned long plGetPSTATCurrentTest(polaris *pol, int port)
int plGetPSTATAccessories(polaris *pol, int port)
int plGetPSTATMarkerType(polaris *pol, int port)

This command is not available during tracking mode.

#define plPURD	(	p,
		port,
		addr
	)	plCommand((p),"PURD:%c%04X",(port),(addr))

Read the user part of the tool SROM. Use plHexDecode() convert reply.

#define plPUWR	(	p,
		port,
		a,
		x
	)	plCommand((p),"PPWR:%c%04X%.128s",(port),(a),(x))

Write the user part of the tool SROM. Use plHexEncode() to convert data.

#define plPVCLR	(	p,
		port
	)	plCommand((p),"PVCLR:%c",(port))

Clear the virtual SROM for the specified port. For a passive tool, this is equivalent to unplugging the tool.

Parameters

port	one of '1', '2', '3' or 'A' to 'I'

#define plPVTIP	(	p,
		port,
		tip,
		np
	)	plCommand((p),"PVTIP:%c%d%d",(port),(tip),(np))

Set the virtual TOOL IN PORT and non-POLARIS tool signals for this port

#define plPVWR	(	p,
		port,
		a,
		x
	)	plCommand((p),"PVWR:%c%04X%.128s",(port),(a),(x))

Write to a virtual SROM address on the specified port. The plPVWRFromFile() function provides a more convenient means of uploading tool descriptions.

Parameters

port	one of '1', '2', '3' or 'A' to 'I'
a	an address between 0 and 960
x	64-byte data array encoded as a 128-character hexidecimal string

The plHexEncode() function can be used to encode the data into hexidecimal.

#define plRESET ( p ) plCommand((p),NULL)

Send a serial break to reset the POLARIS. If the reset was not successful, the error code will be set to PL_RESET_FAIL.

#define plSFLIST	(	p,
		mode
	)	plCommand((p),"SFLIST:%02X",(mode))

Get a feature list for this POLARIS.

Parameters

mode

the desired reply mode

0x00 - 32-bit feature summary encoded as 8 hexidecimal digits
0x01 - the number of active tool ports as a single digit
0x02 - the number of passive tool ports as a single digit
0x03 - list of volumes available (see NDI documentation)
0x04 - the number of ports that support tool-in-port current sensing

The feature summary bits are defined as follow:

0x00000001 - active tool ports are available
0x00000002 - passive tool ports are available
0x00000004 - multiple volumes are available
0x00000008 - tool-in-port current sensing is available

#define plSSTAT	(	p,
		format
	)	plCommand((p),"SSTAT:%04X",(format))

Request status information from the POLARIS.

Parameters

format

a reply format mode composed of the following bits:

PL_CONTROL 0x0001 - control processor information
PL_SENSORS 0x0002 - sensor processors
PL_TIU 0x0004 - TIU processor

The use of the SSTAT command with the appropriate reply format updates the information returned by the following commands:

This command is not available during tracking mode.

#define plTCTST	(	p,
		port
	)	plCommand((p),"TCTST:%c",(port))

Perform a current test on this port.

#define plTSTART ( p ) plCommand((p),"TSTART:")

Put the POLARIS into tracking mode.

#define plTSTOP ( p ) plCommand((p),"TSTOP:")

Take the POLARIS out of tracking mode.

#define plTTCFG	(	p,
		port
	)	plCommand((p),"TTCFG:%c",(port))

Set default tool configuration prior to testing.

#define plVER	(	p,
		n
	)	plCommand((p),"VER:%d",(n))

Get a string that describes the POLARIS firmware version.

Parameters

n	the processor to get the firmware revision of: 0 - control firmware 1 - left sensor firmware 2 - right sensor firmware 3 - TIU firmware 4 - control firmware with enhanced versioning

#define plVSEL	(	p,
		n
	)	plCommand((p),"VSEL:%d",(n))

Select from the different calibrated operating volumes available to the POLARIS.

Parameters

n	the volume to select, see plSFLIST()

Function Documentation

static int plPVWRFromFile	(	polaris *	pol,
		int	port,
		char *	filename
	)

static

Write data from a ROM file into the virtual SROM for the specified port.

Parameters

pol	pointer to a valid polaris object
port	one of '1', '2', '3' or 'A' to 'I'
filename	file to read the SROM data from

Returns: PL_OKAY if the write was successful

If the return value is not PL_OKAY but plGetError() returns PL_OKAY, then the ROM file could not be read and no information was written to the POLARIS.

This function uses the PVWR command to write the SROM. The total size of the virtual SROM is 1024 bytes. If the file is shorter than this, then zeros will be written to the remaining space in the SROM.

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation