Main Type 2 hexadecimal characters Possible Values: 01 Reference 02 Probe 03 Button box or foot switch 04 Software-defined 05 Microscope tracker 06 Reserved 07 Calibration device 08 Tool Docking Station 09 Isolation box 0A C-arm tracker 0B Catheter 0D to FF Reserved Number of Switches 1 character Number of 1 character Visible LEDs Reserved 2 characters Subtype 2 characters Manufacturer’s ID 12 characters Tool Revision 3 characters Polaris Vega Application Program Interface Guide 97 Command Details Reply Component Description Serial Number 8 hexadecimal characters (32 bits) Bit field: Port Status bits 0 to 9 Sequence number (one-based) bits 10 to 18 Day of year (zero-based, e.g. Jan 1 is day 0 and Dec 31 is day 364) bits 19 to 22 Month (zero-based) bits 23 to 31 Year (year is - 1900, e.g. the year 2009 is 109) 2 hexadecimal characters (8 bits) Bit field: bit 0 Tool-in-port bit 1 Switch 1 closed bit 2 Switch 2 closed bit 3 Switch 3 closed bit 4 Port initialized bit 5 Port enabled bit 6 Reserved bit 7 Tool-in-port from current sensing Reply Option 0002 - Wired Tool Electrical Information Reply Component Description Reply Option 0002 Data 8 hexadecimal characters Wired tool electrical information. The electrical current is tested for two conditions: over and under. An “over” current condition indicates that there is a short circuit in either the cable or the marker. An “under” current condition indicates that there is either a break in the cable or the marker has burnt out. Bit field: bits 0 to 19 Marker failed. Bit 0 = marker A, ..., bit 19 = marker T bits 20 to 29 Reserved bit 30 Under bit 31 Over You can test the electrical current of all the markers on a tool using TCTST (page 133). 98 Polaris Vega Application Program Interface Guide Command Details Reply Option 0004 - Tool Part Number Reply Component Description Reply Option 0004 Data 20 characters The part number of the tool. Reply Option 0008 - Switch and Visible LED Information Reply Component Description Reply Option 0008 Data 2 hexadecimal characters (8 bits) This option reports the information found in the tool description. It is not information sensed by the hardware. Bit field: bit 0 Tool-in-port switch supported bit 1 Switch 1 supported bit 2 Switch 2 supported bit 3 Switch 3 supported bit 4 Tool tracking LED supported bit 5 LED 1 line 1 supported bit 6 LED 2 line 2 supported bit 7 LED 3 line 3 supported Polaris Vega Application Program Interface Guide 99 Command Details G.003.002 Reply Option 0010 - Tool Marker Type and Wavelength Reply Component Description Reply Option 0010 Data 2 hexadecimal characters (8 bits) Bits 0 to 2 give information on the marker wavelength: 000 9x0 nm (See “Compatibility Notes” on page 101.) X 001 880 nm X 010 930 nm X 100 870 nm X 111 850 nm Bits 3 to 7 give information on the marker type: 00000 Reserved 00001 NDI active X 00010 NDI ceramic X 00011 Unknown active X 00100 Unknown passive X 00101 Passive sphere X 00110 Passive disc X 00111 NDI Radix X 01000 to 11111 Reserved Reply Option 0020 - Physical Port Location = Reply Component Description Hardware Device 8 characters For passive or active wireless tools this is the Position Sensor serial number. For Polaris Vega active tools, this is STB-0. System Type 1 character Possible values: Reserved 100 Polaris Vega Application Program Interface Guide Command Details Reply Component Description 1 character Tool Type Possible values: 0 Wired 1 Wireless 2 ASCII characters Port Number Possible values: 01 to 03 Used for Polaris Vega wired tools 00 Used for Polaris Vega wireless tools 2 characters Reserved Usage Notes 1. The physical location of a port handle is the only information available unless PHINF has been preceded by PINIT (page 107) or PENA (page 91). 2. Port handles for tools that have been disconnected will be reported as UNOCCUPIED and no additional information will be returned. 3. Reply option 0001: For wired tools, bits 1, 2, and 3 in the port status report status. 4. Reply option 0008: For wired tools, bits 1, 2, and 3 report status, and bits 5, 6, and 7 report LED status. Compatibility Notes 1. Reply option 0010: A value of 010 for marker wavelength can be returned only for tools characterized using NDI 6D Architect version 2.02 or later. Tools characterized with earlier versions of NDI 6D Architect will have a value of 000 for a marker wavelength of 930 nm. 2. Reply option 0040: This option is not supported by the hybrid Polaris Vega System. Example Command: PHINF 040001 Reply: 's e l oo p Ty T 08000000NDI r re u t ac f nu D Ma I l oo er on i is v Re T al S i er b um N s tu a St rt C Po CR 00132C3D301110893 Polaris Vega Application Program Interface Guide 101 Command Details PHRQ Assigns a port handle to a tool. Operating Mode Setup Prerequisite Command INIT (page 83) Syntax PHRQ Parameter Description Hardware Device 8 characters The hardware device must match the one returned by PHINF (page 96) reply option 0020, or use wild card characters (*). For active tools connected to the system, specifying all wildcards will default to hardware device STB-0 (the tool ports on the System Control Unit). System Type 1 character Valid Values: Use a wild card character (*). Tool Type 1 character This must be specified for wireless tools. Valid Values: Port Number 0 or * Wired 1 Wireless (passive or active wireless) 2 characters The physical port number where a wired tool is plugged in. This must be specified for wired tools. Valid Values: 102 01 to 03 Used for hybrid Polaris Vega wired tools 00 or ** Used for wireless tools Polaris Vega Application Program Interface Guide Command Details Parameter Description Dummy Tool 2 characters If specified, will auto-generate a non-trackable dummy tool. Useful for 3D straymarker tracking. In the case of Tool Type = Wired, either 01 or 02 adds an active wired dummy tool. Otherwise, In case of Tool Type = Wireless: Valid Values: ** Do not load a dummy tool. Requires tool definition to be loaded with subsequent PVWR (page 116) commands. 01 adds passive dummy tool 02 adds active wireless dummy tool Replies Upon Success: On Error: ERROR See page 157 for error code definitions. Usage Notes 1. Use PHRQ to assign a port handle to a wireless tool or to a wired tool that has neither a tool-inport diode or a marker in position A of the tool wiring matrix. If a wired tool has a tool-in-port diode or a marker in position A of the tool wiring matrix, use PHSR (page 104) to detect the tool and assign it a port handle. 2. Wireless tools: You must specify the tool type. All other parameters may be left as wild card characters (*). 3. Wired tools: You must specify the port number. All other parameters may be left as wild card characters (*). 4. After using PHRQ, you must use PVWR (page 116) to assign a tool definition file to the tool. If you do not assign a tool definition file to the tool, the port handle will be reported as unoccupied when it is initialized with PINIT (page 107) or PENA (page 91). Example Command: PHRQ *********1**** Reply: 04D715 This requests a port handle for a wireless tool. Polaris Vega Application Program Interface Guide 103 Command Details PHSR Returns the number of assigned port handles and the port status for each one. Assigns a port handle to a wired tool. Operating Mode All modes Prerequisite Command INIT (page 83) Syntax PHSR Parameter Description Reply Option Specifies which information will be returned. If no reply option is specified, the system returns information for reply option 00. The reply options cannot be OR’d. Valid Values: 00 Reports all allocated port handles (default) 01 Reports port handles that need to be freed 02 Reports port handles that are occupied, but not initialized or enabled 03 Reports port handles that are occupied and initialized, but not enabled 04 Reports enabled port handles Replies Upon Success: <1st Port Handle><1st Port Handle Status> <2nd Port Handle><2nd Port Handle Status> ... On Error: ERROR See page 157 for error code definitions 104 Polaris Vega Application Program Interface Guide Command Details Reply Component Description Number of Port Handles 2 hexadecimal characters The number of allocated port handles of the type specified in the reply option. If no reply option is specified, the number returned is the total number of allocated port handles. nth Port Handle 2 hexadecimal characters Specifies the port handle whose status follows. nth Port Handle Status 3 hexadecimal characters (12 bits) Bit field: bit 0 Occupied bit 1 Switch 1 closed bit 2 Switch 2 closed bit 3 Switch 3 closed bit 4 Initialized bit 5 Enabled bit 6 Reserved bit 7 Tool detected from current sensing bit 8 to 11 Reserved Usage Notes 1. When you send the PHSR command, the system will detect and assign port handles to any wired tools that do not already have a port handle assigned (i.e. any wired tools that were plugged in after the last PHSR call). It will then return the requested port handle information. 2. The system will detect a wired tool if the tool has a tool-in-port diode, or a marker in position A of the tool wiring matrix. If you are using a wired tool that does not meet this criteria, you will need to request a port handle for the tool using PHRQ. 3. If you unplug a wired tool while the system is in tracking mode, the port handle will be reported as “disabled” in the replies to the BX and TX commands. If you reconnect the tool, it will need a new port handle. 4. If you connect a wired tool to the system while the system is in tracking mode, you will have to take the following steps before the system will report the tool: a) Exit tracking mode (TSTOP). b) Assign, initialize, and enable a port handle for the tool as outlined in Figure 3-1 on page 18. c) Re-enter tracking mode (TSTART). Polaris Vega Application Program Interface Guide 105 Command Details 5. PHSR will report wireless tool ports as unoccupied if you have requested a port handle using PHRQ (page 102) but have not yet associated a tool definition file for the port handle (using PVWR (page 116)). 6. To obtain a port handle for a wireless tool, use PHRQ. 7. PHSR will only return the number of assigned port handles and their status when executed in tracking or diagnostic mode from a master connection, or when executed in any mode from a monitor connection. Examples Command: PHSR Reply: 001414 In this case, there are no occupied port handles. Command: PHSR Reply: 0101031F1AF In this case, there is one occupied port handle, which is initialized and enabled. 106 Polaris Vega Application Program Interface Guide Command Details PINIT Initializes a port handle. Deprecated Operating Mode Setup Prerequisite Command PVWR (page 116) or PHSR (page 104) Syntax PINIT Parameter Description Port Handle 2 hexadecimal characters Replies Upon Success: OKAY or WARNING (Indicates that a non-fatal tool error has been encountered, e.g. a burnt out marker.) or WARNING05 is returned when the system selects a default marker wavelength to track a tool (if the tool’s tool definition file did not specify a marker wavelength). On Error: ERROR See page 157 for error code definitions. Usage Notes 1. PENA now initializes tools that have not been initialized with PINIT. Therefore, it is no longer necessary to use PINIT. 2. If the tool description is drawn from a tool definition file that has been loaded using PVWR (page 116), initialization involves unpacking and verifying the tool definition file. This process is almost instantaneous. 3. If the tool description is drawn from an SROM device, initialization involves reading, unpacking, and verifying the tool definition file contents, and testing electrical current through all the markers to detect burnt out markers. This process takes approximately two seconds if successful, or several seconds longer if a problem is encountered and retries are attempted by the system. Polaris Vega Application Program Interface Guide 107 Command Details 4. The port handle will still initialize when the system returns WARNING. or WARNING05. 5. The SCU will load and parse active tool info when a tool is plugged in. PENA will load and parse passive tool info if not done so yet. Example Command: PINIT 01 Reply: OKAYA896 This initializes port handle 01. 108 Polaris Vega Application Program Interface Guide Command Details PPRD Reads data from the SROM device in a wired tool. Operating Mode Setup Prerequisite Command INIT (page 83) Syntax PPRD Parameter Description Port Handle 2 hexadecimal characters SROM Device Address 4 hexadecimal characters Valid Values: 0x0000 to 0x07C0 Replies Upon Success: The SROM device data is 64 bytes (128 hexadecimal characters) of data. On Error: ERROR See page 157 for error code definitions. Usage Notes 1. The SROM device is a 2-KB write-once device that must be read in 64-byte chunks. An SROM device is considered blank if its contents are all 0xFFs. 2. PPRD reads 64 bytes of data from the SROM device starting at a specified SROM device address. Example Command: PPRD 010000 Reply: 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345678 9ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF66A5 Polaris Vega Application Program Interface Guide 109 Command Details PPWR Writes data to the SROM device in a wired tool. Operating Mode Setup Prerequisite Command INIT (page 83) Syntax PPWR Parameter Description Port Handle 2 hexadecimal characters SROM Device Address 4 hexadecimal characters Valid values: 0x0000 to 0x07C0 SROM Device Data 64 bytes (128 hexadecimal characters) of data Replies Command: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes 1. PPWR writes 64 bytes of data to the SROM device starting at a specified SROM device address. 2. The data must be formatted into unsigned ASCII characters. Each byte of binary data can be represented by two hexadecimal characters, which are then sent to the system in ASCII (4 bits per ASCII character). 3. The tool description section of tool SROM device is a 1-Kbyte, write-once area that must be written in 64-byte chunks. If the information being written to the system is less than 64 bytes in size, then the remainder of the chunk must be padded out with ones to maintain the 64-byte size before being written to the system. To write to the second 1-Kbyte section, use the PUWR command. 4. An SROM device is considered blank if its contents are all 0xFFs. 5. The recommended procedure to follow for updating an SROM device is: 110 Polaris Vega Application Program Interface Guide Command Details a) Read the contents of the SROM device using PPRD (page 109). b) Modify the data. c) Write the modified data back to the SROM device using PPWR (page 110). Example Command: PPWR 0100C000000000000000000000000000000000000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000009731 Reply: OKAYA896 Polaris Vega Application Program Interface Guide 111 Command Details PURD Reads data from the user section of the SROM device in a wired tool. Operating Mode All modes Prerequisite Command INIT (page 83) Syntax PURD Parameter Description Port Handle 2 hexadecimal characters User SROM Device Address 4 hexadecimal characters Valid values: 0x0000 to 0x03C0 Replies Upon Success: The SROM device data is 64 bytes (128 hexadecimal characters) of data. On Error: ERROR See page 157 for error code definitions. Usage Notes 1. The SROM device is automatically selected as the reading target when this command is issued, so you do not need to find and specify the SROM device ID. The SROM device address has an implied offset in the command which places the user information at the correct SROM device address. 2. The PURD command returns 64 bytes of data at a time. Example Command: PURD:010000 112 Polaris Vega Application Program Interface Guide Command Details Reply: 0022446688AACCEE0022446688AACCEE0022446688AACCEE0022446688AACCEE002244668 8AACCEE0022446688AACCEE0022446688AACCEE0022446688AACCEE3CC0 Polaris Vega Application Program Interface Guide 113 Command Details PUWR Writes data to the user section of the SROM device in a wired tool. Operating Mode Setup Prerequisite Command INIT (page 83) Syntax PUWR Parameter Description Port Handle 2 hexadecimal characters User SROM device address 4 hexadecimal characters Valid values: 0x0000 to 0x03C0 User SROM device data 64 bytes of data to write (128 hexadecimal characters) Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes 1. The SROM device is automatically selected as the reading target when this command is issued, so you do not need to find and specify the SROM device ID. The SROM device address has an implied offset in the command which places the user information at the correct SROM device address. 2. The data must be formatted into unsigned ASCII characters. Each byte of binary data can be represented by two hexadecimal characters, which are then sent to the system in ASCII (4 bits per ASCII character). 3. The user section of SROM devices is a 1-Kbyte, write-once area that must be written in 64-byte chunks. If the information being written to the system is less than 64 bytes in size, then the remainder of the chunk must be padded out with ones to maintain the 64-byte size before being written to the system. 114 Polaris Vega Application Program Interface Guide Command Details 4. The recommended procedure to follow for updating an SROM device is outlined below: a) Read the contents of the SROM device using PURD (page 112). b) Modify the data read. c) Write the modified data back to the SROM device using PUWR. Example Command: PUWR 01008000000000000000000000000000000000000000000000000000000000000000 00000000000000000000000000000000000000000000000000000000000000000A927 Reply: OKAYA896 Polaris Vega Application Program Interface Guide 115 Command Details PVWR Assigns a tool definition file to a wireless tool, or overrides the SROM device in a wired tool. Operating Mode Setup Prerequisite Command PHRQ (page 102) or PHSR (page 104) Syntax PVWR Parameter Description Port Handle 2 hexadecimal characters Start Address 4 hexadecimal characters Increment the start address by 64 bytes with each chunk of data sent for a particular port handle. Valid values: 0x0000 to 0x3FC0 Tool Definition Data 64 bytes (128 hexadecimal characters) of data Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes 1. Use PVWR • To assign a tool definition file to a wireless tool after using PHRQ. • To assign a tool definition file to a wired tool, to override the SROM device in the tool. • To assign a tool definition file to a wired tool, to test the tool definition file before permanently recording the tool definition file onto the SROM device. 2. The data must be formatted into unsigned ASCII characters. Each byte of binary data can be represented by two hexadecimal characters, which are then sent to the system in ASCII (4 bits per ASCII character. 116 Polaris Vega Application Program Interface Guide Command Details 3. Data is sent to the system in 64-byte chunks (128 hexadecimal characters). The last chunk must be padded out with zeroes to maintain the 64-byte size before being written to the system. 4. If a wireless tool port is the target of this command, the port becomes occupied when the first 64 bytes of information is written. Any previous initialization for the port is lost. 5. Use PVWR to assign a tool definition file to a wireless tool after using PHRQ (page 102). 6. After using PVWR, enable (PENA) the port handle in order to track the tool. 7. To permanently write a tool definition file to an SROM device, use PPWR (page 110). Example Command: PVWR 0200004E444900551C000001000000000000010100000001A419335A000000030000 000300000000000040000000000000000000000000000000000000000000000000 Reply: OKAYA896 Polaris Vega Application Program Interface Guide 117 Command Details RESET Resets the system. Operating Mode All modes Syntax RESET Parameter Description Reset Option Optional. Specifies the type of reset. If no reset option is specified, the system performs a RESET 0. The reset options cannot be OR’d. Valid Values: 0 Generates a soft reset. Does not power cycle the Position Sensor. 1 Performs a board-level reset of all hardware devices. Replies Upon Success: RESET On Error: ERROR See page 157 for error code definitions. Example Command: RESET 0 Reply: RESETBE6F 118 Polaris Vega Application Program Interface Guide Command Details SAVE Saves all non-volatile user parameters that have been changed. Operating Mode All modes Syntax SAVE Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes 1. To restore the user parameters to factory default values, use the DFLT (page 73) command. To save the user parameters at their factory default values, use the SAVE command after using the DFLT command. 2. On systems that have the Password Protect keyed feature enabled, user parameters can only be saved after the correct password is entered. To enter the password, use SET Config.Password= , where is the correct password. For more information on the Password Protect keyed feature, see the user guide that accompanied the system. 3. To set user parameter values, use the SET (page 120) command. 4. For more information on user parameters, see “User Parameters” on page 20. Example Command: SAVE Reply: OKAYA896 Polaris Vega Application Program Interface Guide 119 Command Details SET Sets user parameter values. Operating Mode All modes Syntax SET= Parameter Description User Parameter Name A case-sensitive string, identifying the name of the user parameter. Value The value to set. Numerical values are decimal unless preceded by 0x. For boolean values, 1 is true and 0 is false. Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes 1. To view a list of user parameters and their current values, use GET *. For a description of the user parameters, use GETINFO *. 2. The user parameter values set using the SET command persist until the system is reset or initialized. To save the user parameter values, use SAVE (page 119). To reset user parameters to their default values, use DFLT (page 73). 3. User parameter names are case-sensitive. 4. For more information on user parameters, see “User Parameters” on page 20 Example Command: SET Param.Tracking.Sensitivity=1 Reply: OKAYA896 This sets the infrared light sensitivity level to level 1 on the first Position Sensor in the configuration. 120 Polaris Vega Application Program Interface Guide Command Details SFLIST Returns information about the supported features of the system. Deprecated Operating Mode Setup, diagnostics or tracking Syntax Parameter Description Reply Option Specifies which information will be returned. G.003.002 SFLIST X The reply options cannot be OR'd. Valid values: 00 Summary of supported features X 01 Number of active tool ports X 02 Number of wireless tool ports X 03 Number of measurement volumes and wavelengths; volume shapes and supported wavelengths X 04 The number of wired tool ports available which support tool-in-port detection from current sensing X 05 Number of active wireless tools X The reply options cannot be OR’d. Replies Upon Success: On Error: ERROR See page 157 for error code definitions. Polaris Vega Application Program Interface Guide 121 Command Details Reply Component Description Reply Option n Data The data specific to the requested reply option. See the reply option information below for details: Reply option 00 (Summary of supported features) Reply option 01 (Number of active tool ports) Reply option 02 (Number of wireless tool ports) Reply option 03 (Number of characterized measurement volumes and wavelengths; volume shapes and supported wavelength) Reply option 04 (The number of wired tool ports available which support tool-in-port detection from current sensing) Reply option 05 (Number of active wireless tools) Reply Option 00 - Supported Features Summary Reply Component Description Reply Option 00 Data 8 hexadecimal characters (32 bits) Bit field: bit 0 Active tool ports available bit 1 Passive tool ports available bit 2 Multiple volume characterization parameters supported bit 3 Tool-in-port from current sensing available bit 4 Active wireless tool ports available bit 5 Reserved bits 7 to 31 Reserved Reply Option 01 - Number of Active Tool Ports Reply Component Description Reply Option 01 Data 1 hexadecimal character The number of wired tool ports. 122 Polaris Vega Application Program Interface Guide Command Details Reply Option 02 - Number of Wireless Tool Ports Reply Component Description Reply Option 02 Data 1 hexadecimal character The number of wireless tool ports, up to a maximum of 15 (the highest number that can be represented in one hexadecimal digit). To find out the actual number of wireless tool ports, read the parameters Features.Tools.Passive Ports (for passive wireless) and Features.Tools.Wireless Ports (for active wireless). Polaris Vega Application Program Interface Guide 123 Command Details Reply Option 03 - Volumes Note Because SFLIST is deprecated, the Volume User Parameters on page 37 should be used instead. = <1st Shape Type><1st Shape Parameter><1st Number of Wavelengths Supported><1st Supported Wavelengths> ... Reply Component Description Number of Volumes 1 hexadecimal character nth Shape Type 1 hexadecimal character Possible values: 5 Extended Pyramid Shape The volumes are named “Pyramid”, “Extended Pyramid” 7 Arc Shape The volume name is “Vicra” nth Shape Parameter 10 parameters, 7 characters each (a sign, and six digits with an implied decimal in the position XXXX . XX) nth Number of Wavelengths Supported 1 hexadecimal character nth Supported Wavelengths 1 character per wavelength supported Possible values: 0 930 nm (see “Usage Notes” on page 127) 1 880 nm 4 870 nm 7 850 nm Reply Option 04 - Number of Active Tool Ports Supporting Tool-in-Port Detection From Current Sensing Reply Component Description Reply Option 04 Data 1 hexadecimal character Reply Option 05 - Number of Active Wireless Ports Reply Component Description Reply Option 05 Data 1 hexadecimal character 124 Polaris Vega Application Program Interface Guide Command Details Polaris Vega System - Shape Parameters Note Because SFLIST is deprecated, the Volume User Parameters on page 37 should be used instead. For the pyramid measurement volume, in reply option 03 returns the following values (illustrated in Figure 5-2): Shape Parameter Value Description D1 -2400 mm z-coordinate of back of volume D2 -1532 mm z-coordinate where sides of volume change slope D3 -950 mm z-coordinate of front of volume D4 572 mm Half width of volume at z = D2 D5 398 mm Half height of volume z = D2 D6 0569.46 Slope of front part of volume sides in the yz-plane (scaled by 1000) D7 0243.03 Slope of back part of volume sides in the yz-plane (scaled by 1000) D8 0297.73 Slope of volume top and bottom in the xz-plane (scaled by 1000) D9 9999.99 mm Maximum half width of volume (unrestricted) D10 9999.99 mm Maximum half height of volume (unrestricted) Polaris Vega Application Program Interface Guide 125 Command Details Figure 5-2 Pyramid Volume Parameters (Polaris Vega) For the extended pyramid measurement volume, in reply option 03 returns the following values (illustrated in Figure 5-2 and Figure 5-3): 126 Shape Parameter Value Description D1 -3000 mm z-coordinate of back of volume D2 -1532 mm z-coordinate where sides of volume change slope D3 -950 mm z-coordinate of front of volume D4 572 mm Half width of volume at z = D2 D5 398 mm Half height of volume z = D2 D6 0569.46 Slope of front part of volume sides in the yz-plane (scaled by 1000) D7 0243.03 Slope of back part of volume sides in the yz-plane (scaled by 1000) D8 0297.73 Slope of volume top and bottom in the xz-plane (scaled by 1000) D9 9999.99 mm Maximum half width of volume (unrestricted) D10 735 mm Maximum half height of volume Polaris Vega Application Program Interface Guide Command Details Figure 5-3 Extended Pyramid Volume Parameters (Polaris Vega) Usage Notes 1. Use both the shape type and the shape parameters to represent the characterized measurement volume graphically. There may be multiple volumes with the same shape type. All volumes of the same shape type use the shape parameters the same way. 2. Reply option 03: A characterized measurement volume that supports wavelength value 0 (930 nm) supports the wavelength values of 000 (9x0 nm) and 010 (930 nm) returned with PHINF (page 96). Examples Command: SFLIST Reply: 0000003FEEEC Command: SFLIST 03 Polaris Vega Application Program Interface Guide 127 Command Details Reply: es um l Voe ofTyp er e mbhap 1 u N S D D2 D3 D4 D5 D6 D7 D8 0 D1 D9 17+010000+058200+109900+019400+000000+000000+000000-083000+050600-055700241D837 s h th gt C nglen CR e el ve av Wa W # 128 of Polaris Vega Application Program Interface Guide Command Details STREAM Initiates a streaming response to a command Operating Mode All modes Syntax STREAM Parameter Description [--id=] --id= is an optional id string that will be returned in the stream response header. If it contains spaces it must be quoted. If it is omitted the command string will be used as the id. ids must be unique to the given connection. [--interval=] --interval= is an integer frame count interval that will be used to limit the response rate. [--diff=true] --diff=true when present indicates that only the differences between the current response and the last streamed response will be sent. At present this option is valid for ascii responses to commands such as GET and GETINFO. [--cmd=] is the command string exactly as it would be if issued separately. For consistency and flexibility it is also possible to specify the command using option --cmd= Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Note The response is binary and is similar to the BX binary response with a different header signature. In order to maintain compatibility with the serial protocol, all binary replies are in little endian format rather than network byte order. The header signature is a 2 byte little endian code. The first byte is 0xD4 the second byte is 0xB5. B5D4

is the unmodified reply for the command that is being streamed exactly as it would appear if the command were given separately without streaming. Usage Notes For details on data streaming format see “Data Streaming” on page 8. Polaris Vega Application Program Interface Guide 129 Command Details Example Command: STREAM BX 0803 Reply: OKAYA896 The following would continue with updated data replies until USTREAM is issued B5D40700BX 08031234A5C4.... B5D40700BX 08031234A5C4.... B5D40700BX 08031234A5C4.... B5D40700BX 08031234A5C4.... B5D40700BX 08031234A5C4.... B5D40700BX 08031234A5C4.... B5D40700BX 08031234A5C4.... B5D40700BX 08031234A5C4.... B5D40700BX 08031234A5C4.... ... 130 Polaris Vega Application Program Interface Guide Command Details SYSLOG Writes data to the Position Sensor or System Control Unit log file. Operating Mode All modes Syntax SYSLOG\\= or SYSLOG= Parameter Description Device Name Selects a hardware device to write to. See “Device Names” on page 21 for information on device names. The device name is ignored if it is specified. Category A string, up to 12 characters Specifies the log entry category or source. If you enter more than 12 characters, the system will truncate the category to 12 characters. Message A string, up to 256 characters. Contains the log message. If you enter more than 256 characters, the system will truncate the message to 256 characters. Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes 1. The system log in each hardware device is intended to record events central to the life of the device. The system automatically records events such as updates, bump sensor events, and hardware faults in the log. 2. To read the log, use GETLOG (page 81). Compatibility Notes For passive systems, only the Position Sensor log file is available. Polaris Vega Application Program Interface Guide 131 Command Details Example Command: SYSLOG Test=This is a SYSLOG test! Reply: OKAYA896 132 Polaris Vega Application Program Interface Guide Command Details TCTST Returns diagnostics on the active markers of a wired tool. Operating Mode Setup Prerequisite Command PINIT (page 107) Syntax TCTST Parameter Description Port Handle 2 hexadecimal characters Replies Upon success: ... On Error: ERROR See page 157 for error code definitions. Reply Component Description Marker n Current 2 hexadecimal characters The electrical current of the markers. Usage Notes 1. If the result is less than 0x0A either there is no marker, or there is a problem with the diode that has caused an open circuit. 2. If the result is greater than 0x0A the marker is either okay or it has short-circuited. The exact value cannot be predicted as it depends upon the System Control Unit and the tool design (cable length, number of markers, and marker configuration). This value should be determined on a historical basis for each particular tool design. 3. You cannot test a visible LED, since the System Control Unit cannot reliably test the low current of an LED because the LED current result may be corrupted from electrical noise. Polaris Vega Application Program Interface Guide 133 Command Details Example Command: TCTST 01 Reply: 9400000000940100000092000000009400000000DF24 134 Polaris Vega Application Program Interface Guide Command Details TSTART Starts Tracking mode. Operating Mode Setup Prerequisite Command INIT (page 83) Syntax TSTART Parameter Description Reply Option 80 (Optional) Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes The frame number is reported in reply option 0001 of the TX (page 138) and BX (page 49) commands. In the Polaris Vega System, the frame number is derived from the PTP time, and reply option 80 is ignored. In order to facilitate the retrieval of tracking data in a monitor connection, TSTART will return OKAY when in tracking mode. Example Command: TSTART Reply: OKAYA896 Polaris Vega Application Program Interface Guide 135 Command Details TSTOP Stops tracking mode. Operating Mode Tracking Prerequisite Command TSTART (page 135) Syntax TSTOP Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes If executed from the Setup mode, it will return OKAY. Example Command: TSTOP Reply: OKAYA896 136 Polaris Vega Application Program Interface Guide Command Details TTCFG Sets up a configuration for a wired tool, so that you can test the tool without using a tool definition file. Operating Mode Setup Prerequisite Command INIT (page 83) Syntax TTCFG Parameter Description Port Handle 2 hexadecimal characters Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes 1. TTCFG internally sets up a test configuration for a wired tool, so that it can be tested without having a tool definition file. This is useful for testing the wiring in the tool before characterizing the tool. For example, after sending TTCFG, you can: • use TCTST to test the current • in diagnostic mode, use IRED to individually activate the markers. 2. After sending the TTCFG command, you will need to enable (PENA) the port handle before using any other commands that list these as prerequisites. 3. With the test configuration, the tool cannot be tracked. Example Command: TTCFG 0A Reply: OKAYA896 Polaris Vega Application Program Interface Guide 137 Command Details TX Returns the latest tool transformations, individual marker positions, and system status in text format. Operating Mode Tracking Syntax G.003.002 TX Parameter Description Reply Option Optional. Specifies which information will be returned. If no reply option is specified, the system returns information for reply option 0001. The reply options are hexadecimal numbers that can be OR’d. If multiple reply options are used, the replies are returned for each port handle in order of increasing option value, with the following exceptions: Reply option 0800 is not reported separately from the other options; it simply enables the system to return certain information in the other options. Reply option 1000 is reported after all handle-specific options but before the and . Valid Values: 0001 Transformation data (default) X 0002 Tool and marker information X 0004 3D position of a single stray active marker X 0008 3D positions of markers on tools X 0800 Transformations not normally reported X 1000 3D positions of stray passive markers X Replies Upon Success: <# of Handles>... ... ... Note If the port handle is disabled, the system returns the string DISABLED instead of .... On Error: ERROR 138 Polaris Vega Application Program Interface Guide Command Details Reply Component Number of Handles Description G.003.002 See page 157 for error code definitions. 2 hexadecimal characters X The number of port handles for which information is returned. Handle n 2 hexadecimal characters X The port handle whose information follows. Reply Option m Data System Status The data specific to the requested reply option. See the reply option information below for details: Reply option 0001 (transformation data) (default) X Reply option 0002 (tool and marker information) X Reply option 0004 (latest 3D position of single, stray, active marker) X Reply option 0008 (3D position of markers on tools) X Reply option 0800 (reporting all transformations) X Reply option 1000 (3D position of stray passive markers) X 4 hexadecimal characters (16 bits) The status of the system. Bit field: bit 0 System communication synchronization error X bits 1 and 2 Reserved bit 3 Recoverable system processing exception. bit 4-5 Reserved bit 6 Some port handle has become occupied X bit 7 Some port handle has become unoccupied X bit 8 Diagnostic pending X bit 9 Temperature (system is not within operating tem- X perature range) bit 10 Hardware configuration changed (e.g. VCU or SCU has connected or disconnected) bits 11 to 15 Reserved X X Note The “diagnostic pending” bit is set whenever an alert is detected or cleared. To view the alerts status and clear the diagnostic pending bit, use GET (page 77) to check the Info.Status.New Alerts user parameter for every Polaris Vega Application Program Interface Guide 139 Command Details hardware device in the system. See “Usage Notes” on page 58 for more details. (Note: For API revision G.001.003 and earlier, the diagnostic pending bit did not indicate when an alert was cleared.) Reply Option 0001 - Transformation Data Reply Component Q0, Qx, Qy, Qz G.003.002 = or = MISSING Description 6 characters each (a sign, and 5 decimal digits with an implied decimal in the position X . XXXX) X Rotational component of the transformation, quaternion, unitless. The value for Q0 is always non-negative. Tx, Ty, Tz 7 characters each (a sign, and 6 decimal digits with an implied decimal in the position XXXX . XX) X Translational components of the transformation, in mm. Error 6 characters (a sign, and 5 decimal digits with an implied decimal in the position X . XXXX) X The error is an RMS value, given in mm. It is the result of the least squares minimization between the marker geometry in the tool definition file and the data from the tool’s markers measured by the system. 140 Polaris Vega Application Program Interface Guide G.003.002 Command Details Reply Component Description Port Status 8 hexadecimal characters (32 bits) Bit field: bit 0 Occupied X bit 1 Switch 1 closed X bit 2 Switch 2 closed X bit 3 Switch 3 closed X bit 4 Initialized X bit 5 Enabled X bit 6 Out of volume X bit 7 Partially out of volume X bit 8 Algorithm limitation (processing requires more buffer than is available) X bit 9 IR interference (a large bright IR object) X bits 10 and 11 Reserved bit 12 Processing exception (same as tool information bit 7 in reply option 0002) bit 13 Reserved bit 14 Fell behind while processing (same as tool information bit 3 in reply option 0002) X bit 15 Data buffer limitation (too much data; for example, too many markers) X X bits 16 to 31 Reserved Frame Number 8 hexadecimal characters X The frame number is an internal counter related to data acquisition, which is derived from the PTP time. The frame number corresponds to the frame in which the raw data, used to calculate the accompanying transformation, was collected. Note The system returns the string MISSING, followed by the port status and frame number, in the following situation: - Tools are reported as missing if a transformation cannot be determined. Polaris Vega Application Program Interface Guide 141 Command Details Reply Option 0002 - Tool and Marker Information Reply Component Tool Information G.003.002 = Description 2 hexadecimal characters (8 bits) Bit field: Marker Information bit 0 Bad transformation fit X bit 1 Not enough acceptable markers for transformation X bit 2 IR interference—environmental IR is interfering with the system (combination of port status bits 9 and 15 in reply option 0001) X bit 3 Fell behind while processing (same as port status bit 14 in reply option 0001) X bits 4 to 6 Tool face used X bit 7 Processing exception (same as port status bit 12 in reply option 0001) X 20 hexadecimal characters (1 per marker) See below for an example. Possible Values: 0 Not used because it was missing X 1 Not used because it exceeded the maximum marker angle X 2 Not used because it exceeded the maximum 3D error for the tool X 3 Used to calculate the transformation X 4 Used to calculate the transformation, but it is out of volume X 5 Not used because it was outside the characterized measurement volume and was not needed to calculate a transformation. X Example - Marker Information: A tool with markers located at T, R, C, and A, where all four markers were used to determine the calculation, would have the reply 30300000000000000303, as illustrated: Marker Letter Reply Char (Hex) 142 T S R Q ... D C B A 3 0 3 0 ... 0 3 0 3 Polaris Vega Application Program Interface Guide Command Details Reply Option 0004 - 3D Position of Single Stray Active Marker Reply Component Description Status G.003.002 = or = 2 hexadecimal characters (8 bits) The status of the stray active marker. A stray marker on an active tool is not fixed with respect to the other markers that make up the tool. Bit field: Tx, Ty, Tz bit 0 Valid stray active marker X bit 1 Marker is missing X bit 2 Reserved bit 3 Marker is out of volume bits 4 to 7 Reserved 7 characters each (a sign, and 6 decimal digits with an implied decimal in the position XXXX . XX) X X Position of the marker, reported in the coordinate system of the Position Sensor. The marker position is reported only if the marker status is “valid,” or if the status is “out of volume” and reply option 0800 is used. Note If no stray active marker is defined (for example, for wireless port handles or wired tools with no stray marker defined in the tool definition file), the status is 00, and no position information is returned. If the marker is missing, or if the marker is out of volume and reply option 0800 is not used, the system returns only the status. Polaris Vega Application Program Interface Guide 143 Command Details Reply Option 0008 - 3D Position of Markers on Tools Reply Component Description G.003.002 = Number of Markers 2 hexadecimal characters X Number of markers used in tool transformations. Out of Volume 1 hexadecimal character per 4 markers (1 bit per marker) X The bit is set when the marker is outside the characterized measurement volume (see example below). Reply size = (number of markers)/4, rounded up to the nearest integer. Txn, Tyn, and Tzn 7 characters each (a sign, and 6 decimal digits with an implied decimal in the position XXXX . XX) X Position of the nth marker, reported in the coordinate system of the Position Sensor. The system will report the positions of markers used in tool transformations, as well as markers that exceeded the maximum marker angle or maximum 3D error specified in the tool definition file. See “Usage Notes” on page 147 for more information. Reply size: If reply option 0800 is not used, reply size = (21 characters) x (number of markers inside the characterized measurement volume). If reply option 0800 is used, reply size = (21 characters) x (total number of markers). Example - Out of Volume: The information is returned in the format illustrated in the following example: one bit per marker, in little endian format. In this example there are nine markers, all of which are out of volume: Marker Number Bit Field Reply 144 9 8 7 6 5 4 3 2 1 0 0 0 1 1 1 1 1 1 1 1 1 1 F F Polaris Vega Application Program Interface Guide Command Details Reply Option 0800 - Reporting All Transformations This option enables the reporting of transformations or translations in situations where translations or transformations are calculated, but by default are not reported by the system. Such situations include: • The tool or marker is outside of the characterized measurement volume. • The bump sensor has been tripped. • The system is outside of the optimal operating temperature range. • Other system conditions are not ideal; see “Alerts User Parameters” on page 22 for a full list of these conditions. This reply option must be OR’d with reply option 0001 to obtain transformations for tools in the situations listed above. It must be OR’d with reply options 0004, 0008, or 1000 to obtain position information for markers in the situations listed above. When using reply option 0800 with the TX command, you must take appropriate action to detect the events listed above, and determine whether they are detrimental to your application. If one or more of the events listed above Warning! occurs, reply option 0800 enables the system to return data that may lead to inaccurate conclusions and may cause personal injury. Appropriate action to detect the events listed above includes: • reading the out-of-volume flag in reply options 0001 and 0002 when tracking tools • reading the out-of-volume information in reply options 0004, 0008, and 1000 when tracking stray markers • reading the temperature flag in the system status • reading the diagnostic pending bit in the system status • reading the Info.Status.New Alerts user parameter for every hardware device in the system when the diagnostic pending bit is set. See “Usage Notes” on page 147 for details. Polaris Vega Application Program Interface Guide 145 Command Details Reply Option 1000 - 3D Position of up to 50 Stray Passive Markers Reply Component Description G.003.002 = Number of Markers 2 hexadecimal characters X Number of stray markers. Out of Volume 1 hexadecimal character per 4 markers (1 bit per marker) X The bit is set when the marker is outside the characterized measurement volume (see example below). Reply size = (number of markers)/4, rounded up to the nearest integer. Txn, Tyn, Tzn 7 characters each (a sign, and 6 decimal digits with an implied decimal in the position XXXX . XX) X Position of the nth marker, reported in the coordinate system of the Position Sensor. Reply size: If reply option 0800 is not used, reply size = (21 characters) x (number of markers inside the characterized measurement volume). If reply option 0800 is used, reply size = (21 characters) x (total number of markers). Note At least one passive port handle must be enabled, to activate the illuminators on the Position Sensor. If no passive port handles are enabled, will return 00 and no other data will be returned. Stray passive markers are defined as markers which are not used to calculate any of the transformations for any enabled, passive tools. Stray active wireless tool markers are not reported. Example - Out of Volume The information is returned in the format illustrated in the following example: one bit per marker, in little endian format. In this example there are nine markers, all of which are out of volume: Marker Number Bit Field Reply 146 9 8 7 6 5 4 3 2 1 0 0 0 1 1 1 1 1 1 1 1 1 1 F F Polaris Vega Application Program Interface Guide Command Details Usage Notes 1. The TX format is easier to parse than the binary format; it is useful when troubleshooting, or observing data as it is collected. For replies in binary format, use BX2 (page 60). 2. By default, transformations will not be reported if the tool is either partially or wholly out of the characterized measurement volume, if the bump sensor has been tripped, or if the system is outside of the optimal operating temperature range. To report these transformations, you must use reply option 0800 OR’d with the desired reply option(s). The accuracy of these transformations is unknown. 3. Reply Option 0001: • When the “diagnostic pending” bit is set in the system status, use GET (page 77) to read the Info.Status.New Alerts user parameter for every hardware device in the system. The act of reading these parameters clears the parameters and the “diagnostic pending” bit. For more information on alerts and their associated user parameters, see “Alerts User Parameters” on page 22. • For wired tools, bits 1, 2, and 3 in the port status report switch status. 4. Reply Option 0008: Markers are returned in alphabetical order according to how they are labelled in the tool definition file. For example, for a tool with markers labelled A, G, M and S, the system will return the marker positions in the order A G M S. Reply option 0008 only returns data for markers that the system detects. To identify which marker is which, compare the reply option 0008 data to the data returned with reply option 0002. The marker order is the same for both replies; each marker that does not have a status of 0 (“missing”) in reply option 0002 corresponds to a marker in reply option 0008 5. Reply Option 1000: At least one passive tool definition file must be initialized and enabled in order for the system to return stray passive marker data. If no passive tool definition files are enabled, this reply option will return 00. Compatibility Notes 1. System Status: • In API revision G.001.004 and later, the diagnostic pending bit (bit 8) is set whenever an alert is detected or cleared. In API revision G.001.003 and earlier, the diagnostic pending bit is set only when an alert is detected. 2. Reply Option 0002: • Marker information value 2 means that the marker was not used because it exceeded the maximum 3D error for the tool. Examples Example 1 Command: TX 0001 Polaris Vega Application Program Interface Guide 147 Command Details Reply: r r esmbe l us be u d t m n N a Nu Hale St e d f t m o n r a # Ha Po Fr 0102MISSING0000007100002211 0000D2A5 CR Sy st em C St at us The system reports that there is one tool, which is missing. Notice the port status, which indicates that the tool is occupied, initialized, enabled, and out of volume. Example 2 Command: TX 0801 Reply: s er leumb d n N Hale of nd qx # Ha q0 r us qy qz tx ty tz or r Er be t ta t r Po S e m Nu am Fr 0102+08126+02988-02040+04568-031514+043184-117696+02981000000710000227A 00003F84 Sy CR st em C St at us With the 0800 reply option applied, the system reports the missing tool. Notice the port status, which indicates that the tool is occupied, initialized, enabled, and out of volume. 148 Polaris Vega Application Program Interface Guide Command Details Example 3 Command: TX 0001 Reply: r esmbe l nd Nu Hale of nd # Ha 0101DISABLED 000001C5 Sy CR st em C St at us The system reports that there is one tool, whose port handle is disabled. It also reports the system status. Example 4 Command: TX 1001 Reply: s er leumb d n N Hale of nd qx # Ha q0 r us qy tx qz ty or t r Er tz be t ta S e m Nu am r Po Fr 0101+08565-01538-04254+02481-006263+027579-099121+020540000003100000368 030-005386+033057-098807-003108+036484-095986-000609+040221-0928270000D105 # Ou tx ty of t 1 1 maof rk Vo er lu s me tz 1 tx 2 ty 2 tz 2 tx 3 ty 3 tz 3 Sy CR st em C St at us The system reports the transformation for one tool (first line of the reply), and the positions of three stray passive markers (second line of the reply). Polaris Vega Application Program Interface Guide 149 Command Details USTREAM Terminates a streaming response to a command. Operating Mode All modes Syntax USTREAM --id= --id= is optional Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Example Command: USTREAM BX 0803 Reply: OKAYA896 The stream of "B5D40700BX 08031234A5C4...." messages stops. 150 Polaris Vega Application Program Interface Guide Command Details VCAP Captures and returns IR image data from the sensors. Operating Mode Tracking Syntax VCAP Parameter Description --frame=passive|active| Specifies what type of frame to return. When VCAP is sent with no activewireless| parameters, the next available frame type is returned. The Param.Trackbackground|illuminated ing.Illuminated (Background) Frame parameters must be set to 1 before frames will be returned. --frameindex= Specifies which frame in the frame sequence to return. This is useful when the system is configured with more than one frame of a particular type (e.g. two active frames) and only one of them needs to be returned. When VCAP is sent with no frame index, the next available frame type is returned. --sensor= Specifies which sensor to capture an image from. By default both sensors are used. The left sensor (sensor 0 ) is returned first, followed by the right sensor (sensor 1). --format=RAW|TIFF|PGM Specifies the image format. By default, RAW is used. --depth= Specifies the number of bits to use per pixel. Valid values are 1, 2, 4, 8 and 16. The default is 16. --stride= Specifies the pixel-read step size. For example, a stride of 4 means that every fourth pixel is returned. The default is 1 (i.e. return every pixel). --sample=pixel| average|peak If stride is greater than 1, this specifies how to sample the intermediate pixels. The default is pixel (i.e. intermediate pixels are ignored). --area= Specifies the area of the image to be returned. The maximum size of the image is 1920 x 1200. The default is to return the whole image. If the stride parameter is defined, the area returned will be a subset of the area that is defined. Replies Upon Success: A5C8<4 byte Reply Length> or A5C4<2 byte Reply Length><2 byte Header CRC><2 byte Data CRC> Polaris Vega Application Program Interface Guide 151 Command Details Note The payload is in the General Binary Format, which is documented in the section General Binary Format on page 5. On Error: ERROR See page 157 for error code definitions. Image Data Component: 0x000A Image Component Header Item Type Sensor Frame Type Frame Index Frame Number Trigger Threshold Background Threshold Exposure Stride Image Depth Image Area Meta data length (M) Meta data Image Item 1 byte 1 byte 1 byte 1 byte 4 bytes 4 bytes 4 bytes 2 bytes 1 byte 1 byte 8 bytes 4 bytes M bytes 0=RAW, 1=PGM, 2=TIFF Sensor number Frame type (see BX2) Frame sequence index Frame number Trigger threshold, percentage of full scale (float) Background threshold, percentage of full scale (float) Exposure in microseconds Pixel stride count Bits per pixel X, Y, Width, Height (2 bytes each) Length of optional meta data. Must be multiple of 4 Optional meta data The image data PGM format images have the following meta data embedded as comments: # frame_type = # frame_number = # sensor = # exposure = # trigger_threshold = <% of full scale> # background_threshold = <% of full scale> # stride = # depth = # area = Examples Command: VCAP 152 Polaris Vega Application Program Interface Guide Command Details Reply: 9.2 MB of data in GBF format, consisting of two image components (one for each sensor), each showing the entire image (1920 x 1200 pixels x 16 bits of gray scale) in RAW format. Command: vcap --sensor=0 --stride=2 --format=tiff --depth=8 Reply: 576,326 bytes of data in GBF format, consisting of one image component (for the left sensor), showing 960 x 600 pixels (sampling every second pixel in every second row of the entire image), in 8-bit gray scale, in TIFF format. Polaris Vega Application Program Interface Guide 153 Command Details VER Returns the firmware revision number of critical processors installed in the system. Operating Mode Setup Syntax G.003.002 VER Parameter Description Reply Option Specifies which information will be returned. The reply options cannot be OR'd. Valid Values: 0 System Control Processor (Position Sensor) X 1 Reserved 2 Reserved 3 System Control Unit Processor X 4 System Control Processor (Position Sensor), with enhanced revision numbering. The revision numbering is XXX.YYY, where XXX = major revision and YYY = minor revision. The major revision number is always the same as the revision number for parameter value 0. X 5 Combined firmware revision number. The revision numbering format is XXX. Only the number is reported; there is no information about the type of system. * 6 Reserved Replies Upon Success: Reply Options 0 to 4 and 6: (included only for Reply Option 0 and 4) Reply Option 5: 154 Polaris Vega Application Program Interface Guide Command Details On Error: ERROR See page 157 for error code definitions. Usage Notes 1. If you send the command VER 5 after the INIT command has replied with ERROR2E, the reply will be ???, because component versions are incompatible. Compatibility Notes 1. You can also obtain the combined firmware revision of the system by using the command GET (page 77) to read the value of the user parameter Config.Combined Firmware Revision. See “User Parameters” on page 20 for more information on user parameters. 2. Reply Option 3: Is not supported by passive systems. Examples Command: VER 4 Reply: Polaris Vega Control Firmware NDI S/N: P9-B0058 Characterization Date: 06/09/16 Freeze Tag: Polaris Vega Beta 008.002 Freeze Date: June 20 2016 (c) Northern Digital Inc. AEBC Command: VER 5 Reply: 001BDB5 Polaris Vega Application Program Interface Guide 155 Command Details VSEL Selects a characterised measurement volume. Deprecated Operating Mode Setup Prerequisite Command INIT (page 83) Syntax VSEL Parameter Description Volume Number 1 hexadecimal character Possible Values: 1 to the maximum returned by SFLIST (page 121) Replies Upon Success: OKAY On Error: ERROR See page 157 for error code definitions. Usage Notes Use SFLIST (page 121) to determine which measurement volumes are available. Compatibility Notes The VSEL command has been deprecated for the Polaris Vega System. To select a measurement volume for the Polaris Vega System, use the command SET (page 120) to set the user parameter Param.Tracking.Selected Volume. Example Command: VSEL 1 Reply: OKAYA896 156 Polaris Vega Application Program Interface Guide Error and Warning Code Definitions 6 Error and Warning Code Definitions 6.1 Error Code Definitions If the system receives an invalid command, it responds to the host with the message ERROR. Table 6-1 identifies the error codes and their definitions. Table 6-1 Error Code Definitions Error Code Definition 01 Invalid command. 02 Command too long. 03 Command too short. 04 Invalid CRC calculated for command; calculated CRC does not match the one sent. 05 Time-out on command execution. 06 Unable to set up new communication parameters. This occurs if one of the communication parameters is out of range. 07 Incorrect number of parameters. 08 Invalid port handle selected. 09 Invalid mode selected. Either the tracking priority is out of range, or an incorrect priority was selected (e.g. the tool has markers defined and “button box” was selected). 0A Invalid LED selected. The LED selected is out of range. 0B Invalid LED state selected. The LED state selected is out of range. 0C Command is invalid while in the current mode. 0D No tool is assigned to the selected port handle. 0E Selected port handle not initialized. The port handle needs to be initialized before the command is sent. 0F Selected port handle not enabled. The port handle needs to be enabled before the command is sent. 10 System not initialized. The system must be initialized before the command is sent. 11 Unable to stop tracking. This occurs if there are hardware problems. Please contact NDI. 12 Unable to start tracking. This occurs if there are hardware problems. Please contact NDI. 13 Hardware error: unable to read the SROM device. 14 Invalid Position Sensor characterization parameters. 15 Unable to initialize the system. This occurs if: • the system could not return to Setup mode • there are internal hardware problems. Please contact NDI. • there are internal parameter errors. Use GET to read the Info.Status.Alerts parameter for more details. Polaris Vega Application Program Interface Guide 157 Error and Warning Code Definitions Table 6-1 Error Code Definitions (Continued) Error Code 158 Definition 16 Unable to start Diagnostic mode. This occurs if there are hardware problems. Please contact NDI. 17 Unable to stop Diagnostic mode. This occurs if there are hardware problems. Please contact NDI. 18 Reserved 19 Unable to read device's version information. This occurs if: • the processor selected is out of range • the system is unable to inquire firmware version information from a processor 1A Internal system error. This occurs when the system is unable to recover after: • too much IR • a system processing exception 1B Reserved 1C Unable to set marker activation signature. 1D Reserved 1E Unable to read SROM device data. This occurs if the system is: • unable to auto-select the first SROM device on the given port handle as a target to read from • unable to read a page of SROM device data successfully 1F Unable to write SROM device data. This can occur if: • the system is unable to auto-select the first SROM device on the given port handle as a target for writing to the SROM device • the system is unable to write a page of SROM device data successfully 20 Reserved 21 Unable to test electrical current on tool. 22 Enabled tools are not supported by selected volume parameters. For example, a Position Sensor cannot track a tool if the volume parameter set does not include the marker wavelength of an enabled tool. 23 Command parameter is out of range. 24 Unable to select measurement volume. This occurs if: • the selected volume is not available • there are internal hardware errors. Please contact NDI. 25 Unable to determine the system’s supported features list. This occurs if the system is unable to read all the hardware information. 26-27 Reserved 28 Too many tools are enabled, or the configuration of tools loaded requires too many frames. 29 Reserved 2A No memory is available for dynamic allocation (heap is full). Polaris Vega Application Program Interface Guide Error and Warning Code Definitions Table 6-1 Error Code Definitions (Continued) Error Code Definition 2B The requested port handle has not been allocated. 2C The requested port handle has become unoccupied. 2D All handles have been allocated. 2E Incompatible firmware versions. This can occur if: • a firmware update failed • components with incompatible firmware are connected To correct the problem, update the firmware. If the Multi Firmware feature is installed, select a valid combined firmware revision. 2F Invalid port description. 30 Requested port is already assigned a port handle. 31 Reserved 32 Invalid operation for the device associated with the specified port handle. 33 Feature not available. 34 User parameter does not exist. 35 Invalid value type (e.g. string instead of integer). 36 User parameter value set is out of valid range. 37 User parameter array index is out of valid range. 38 User parameter size is incorrect. 39 Permission denied; file or user parameter is read-only, or a command which requires master mode is attempted from a monitor mode connection. 3A Reserved 3B File not found. 3C Error writing to file. 3D Error reading from file. 3E-3F Reserved 40 Tool Definition File Error. This occurs if: • the CRC failed • the file format is invalid 41 Tool characteristics not supported. This occurs when one of the following fields in the tool definition file is outside of the range supported by the system: • number of markers • number of faces • number of groups • number of markers per face (unique geometry tools only) 42 Device not present. This occurs when the command is specific to a device that is not connected to the system. 43 Reserved Polaris Vega Application Program Interface Guide 159 Error and Warning Code Definitions Table 6-1 Error Code Definitions (Continued) 6.2 Error Code Definition F0 Reserved F1-FF Reserved Warning Code Definitions Table 6-2 Warning Code Definitions Warning Definition WARNING01 A non-fatal tool error has been encountered, e.g. a burnt out marker. WARNING02 The tool you are trying to enable is a unique geometry tool that doesn’t meet the unique geometry requirements. WARNING03 The tool you are trying to enable is a unique geometry tool that conflicts with another unique geometry tool already loaded and enabled. WARNING04 The tool you are trying to enable is a unique geometry tool that doesn’t meet the unique geometry requirements, and conflicts with another unique geometry tool already loaded and enabled. WARNING05 The system has selected a default marker wavelength to track a tool (if the tool’s tool definition file did not specify a marker wavelength). WARNING01 and WARNING05 are returned with the PINIT or the PENA command. WARNING02, WARNING03 and WARNING04 are returned with the PENA command. 160 Polaris Vega Application Program Interface Guide Appendix A Keyed Features This section describes how to use the API commands and user parameters with the keyed features. For more information on keyed features, see the user guide that accompanied your system. For more information on user parameters, see “User Parameters” on page 20. A.1 Disabling and Enabling Keyed Features Disabling a keyed feature makes that feature unavailable. Enabling a keyed feature makes the feature available. A keyed feature is enabled upon installation. To disable or enable a keyed feature: 1. Use the API command SET to set the value of the user parameter Features.Keys.Disabled Keys. The value of this parameter is a comma-separated list. To disable a keyed feature, add its name to the comma-separated list. To re-enable a keyed feature, remove its name from the commaseparated list. For example: “SET Features.Keys.Disabled Keys=Multi Firmware” will disable the Multi Firmware feature. “SET Features.Keys.Disabled Keys=” will re-enable all the installed features keys. 2. Use the API command SAVE to save the settings. 3. Reset the system (use the API command RESET). The changed settings take effect upon system reset. Polaris Vega Application Program Interface Guide 161 A.2 Multi Firmware Feature The multi firmware feature allows the system to contain more than one combined firmware revision. When the multi firmware feature is enabled, you can specify which combined firmware revision the system will use on its next reset or power up. Changing the Combined Firmware Revision Currently in Use Procedure 1. (Optional) Determine which combined firmware revision is currently in use: use the API command GET to read the user parameter Config.Combined Firmware Revision. Example Command: GET Config.Combined Firmware Revision Reply: Config.Combined Firmware Revision=002 2. Determine which combined firmware revisions are available: API revision G.001.004 and later: use the Command: GET Config.Multi Firmware. API command GET (page 77) to read the user Available Combined Firmware Revisions parameter Config.Multi Firmware.Available Reply: 002,003 Combined Firmware Revisions. The list of possible firmware revisions is given in the enumerated list. In this example, the firmware revisions are 002 and 003. API revision G.001.003 or earlier: use GETINFO (page 79) to read the user parameter Config.Multi Firmware.Load Combined Firmware Revision.) Command: GETINFO Config.Multi Firmware.Load Combined Firmware Revision Reply: Config.Multi Firmware.Load Combined Firmware Revision=0;1;3;0;255;002,003; Combined firmware revision to load on next reset (selection automatically saves when set) The list of possible firmware revisions is given in the enumerated list returned by GETINFO. In this example, the firmware revisions are 002 and 003. Select the desired combined firmware Command: SET Config.Multi Firmware.Load revision: use the API command SET to set the Combined Firmware Revision=1 Reply: OKAY value of the user parameter Config.Multi Firmware.Load Combined Firmware Revision.The enumeration is zerobased. For example, to select the second item in the list (revision 003), set the value of the user parameter to 1.This parameter value is automatically saved when set. The selected combined firmware revision is loaded on the next reset. 162 Polaris Vega Application Program Interface Guide A.3 Positioning Laser The positioning laser is located in the Polaris Vega System Position Sensor and indicates the centre of the characterized measurement volume. This feature allows you to properly position the Position Sensor, or position objects in the measurement volume. Unlike the other keyed features, the positioning laser feature cannot be purchased after you obtain the system; the laser hardware must be installed when the system is manufactured. For full details on the positioning laser, see the user guide that accompanied your system. It is possible to activate (turn on) the laser by using an external laser switch connected to a laser switch port. The optional laser switch is not supplied by NDI. Polaris Vega Application Program Interface Guide 163 Appendix B Sample C Routines The following sample C routines are included for reference. For more information and sample code, refer to the Combined API Sample (CAPI). Table 6-3 Sample C Routines Routine Description CalcCRC16 Calculates a running CRC16 using the polynomial X^16 + X^15 + X^2 + 1. EulerAngleTrig Determines the sine and cosine of the Euler angles. DetermineR Calculates the 3x3 rotation matrix which corresponds to the given Euler angles. CvtQuatToRotationMatrix Determines the rotation matrix that corresponds to the given quaternion values. DetermineEuler Calculates the Euler angles given the 3x3 rotation matrix. CvtQuatToEulerRotation Determines the rotation in Euler angles (degrees) that corresponds to the given quaternion rotation. The following defines are used by the sample C routines: /* * Conversion factors. */ #define RAD_TO_DEGREES (180 / 3.1415926) /* * Defined data types. */ typedef float RotationMatrix[3][3]; typedef struct Rotation { float fRoll, /* rotation about the object's z-axis (Euler angle) */ fPitch, /* rotation about the object's y-axis (Euler angle) */ fYaw; /* rotation about the object's x-axis (Euler angle) */ } Rotation; typedef struct QuatRotation { float fQ0, fQX, fQY, fQZ; } QuatRotation; 164 Polaris Vega Application Program Interface Guide B.1 CalcCRC16 The following is a sample C routine, for calculating a running 16 bit CRC, as used in communications between the host computer and the Polaris System. /***************************************************************** Name: CalcCRC16 Input Values: int data unsigned int *puCRC16 :Data value to add to running CRC16. :Ptr. to running CRC16. Output Values: None. Returned Value: None. Description: This routine calculates a running CRC16 using the polynomial X^16 + X^15 + X^2 + 1. *****************************************************************/ void CalcCRC16( int data, unsigned int *puCRC16 ) { static int oddparity[16] = { 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0 }; data = (data ^ (*puCRC16 & 0xff)) & 0xff; *puCRC16 >>= 8; if ( oddparity[data & 0x0f] ^ oddparity[data >> 4] ) { *puCRC16 ^=0xc001 } /* if */ data <<= 6; *puCRC16 ^= data; data <<= 1; *puCRC16 ^= data; } /* CalcCRC16 */ Polaris Vega Application Program Interface Guide 165 B.2 EulerAngleTrig /******************************************************************** Name: EulerAngleTrig Input Values: Rotation *pdtRotationAngle :Ptr to struct containing the roll, pitch, yaw Euler angles which define the required rotation. Output Values: Rotation *pdtSinAngle :Ptr yaw *pdtCosAngle :Ptr yaw to struct containing the sine of the roll, pitch, Euler angles. to struct containing the cosine of the roll, pitch, Euler angles. Returned Value: None. Description: This routine determines the sine and cosine of the Euler angles. *********************************************************************/ static void EulerAngleTrig( Rotation *pdtRotationAngle, Rotation *pdtSinAngle, Rotation *pdtCosAngle ) { pdtSinAngle->fRoll= sin( pdtRotationAngle->fRoll ); pdtSinAngle->fPitch= sin( pdtRotationAngle->fPitch ); pdtSinAngle->fYaw = sin( pdtRotationAngle->fYaw ); pdtCosAngle->fRoll= cos( pdtRotationAngle->fRoll ); pdtCosAngle->fPitch= cos( pdtRotationAngle->fPitch ); pdtCosAngle->fYaw= cos( pdtRotationAngle->fYaw ); } /* EulerAngleTrig */ 166 Polaris Vega Application Program Interface Guide B.3 DetermineR /******************************************************************** Name: DetermineR Input Values: Rotation *pdtRotationAngle :Ptr to struct containing the roll, pitch, yaw Euler angles which define the required rotation. Output Values: RotationMatrix dtRotationMatrix :The 3x3 rotation matrix to be determined. Returned Value: None. Description: This routine calculates the 3x3 rotation matrix which corresponds to the given Euler angles. ********************************************************************/ void DetermineR( Rotation *pdtRotationAngle, RotationMatrix dtRotationMatrix ) { Rotation dtSinAngle, /* the sine of the roll, pitch, and yaw angles */ dtCosAngle; /* the cosine of the roll, pitch, and yaw angles */ /* * Might as well determine the sine and cosine of the given Euler *angles right from the start */ EulerAngleTrig( pdtRotationAngle, &dtSinAngle, &dtCosAngle ); /* * Fill in the rotation matrix. */ dtRotationMatrix[0][0] = dtCosAngle.fRoll * dtCosAngle.fPitch; dtRotationMatrix[0][1] = dtCosAngle.fRoll * dtSinAngle.fPitch * dtSinAngle.fYaw - dtSinAngle.fRoll * dtCosAngle.fYaw; dtRotationMatrix[0][2] = dtCosAngle.fRoll * dtSinAngle.fPitch * dtCosAngle.fYaw + dtSinAngle.fRoll * dtSinAngle.fYaw; dtRotationMatrix[1][0] = dtSinAngle.fRoll * dtCosAngle.fPitch; dtRotationMatrix[1][1] = dtSinAngle.fRoll * dtSinAngle.fPitch * dtSinAngle.fYaw + dtCosAngle.fRoll * dtCosAngle.fYaw; dtRotationMatrix[1][2] = dtSinAngle.fRoll * dtSinAngle.fPitch * dtCosAngle.fYaw - dtCosAngle.fRoll * dtSinAngle.fYaw; dtRotationMatrix[2][0] = - dtSinAngle.fPitch; dtRotationMatrix[2][1] = dtCosAngle.fPitch * dtSinAngle.fYaw; dtRotationMatrix[2][2] = dtCosAngle.fPitch * dtCosAngle.fYaw; } /* DetermineR */ Polaris Vega Application Program Interface Guide 167 B.4 CvtQuatToRotationMatrix /******************************************************************** Name: CvtQuatToRotationMatrix Input Values: QuatRotation *pdtQuatRot :Ptr to the quaternion rotation. Output Values: RotationMatrix dtRotationMatrix :The 3x3 determined rotation matrix. Returned Value: None. Description: This routine determines the rotation matrix that corresponds to the given quaternion. Let the quaternion be represented by: | Q = | | | Q0 Qx Qy Qz | | | | and the rotation matrix by: | M00 M01 M02 | M = | M10 M11 M12 | | M20 M21 M22 | then assuming the quaternion, Q, has been normalized to convert Q to M we use the following equations: M00 M01 M02 M10 M11 M12 M20 M21 M22 = = = = = = = = = (Q0 2 * 2 * 2 * (Q0 2 * 2 * 2 * (Q0 * Q0) + (Qx * Qx) - (Qy * Qy) - (Qz * Qz) ((Qx * Qy) - (Q0 * Qz)) ((Qx * Qz) + (Q0 * Qy)) ((Qx * Qy) + (Q0 * Qz)) * Q0) - (Qx * Qx) + (Qy * Qy) - (Qz * Qz) ((Qy * Qz) - (Q0 * Qx)) ((Qx * Qz) - (Q0 * Qy)) ((Qy * Qz) + (Q0 * Qx)) * Q0) - (Qx * Qx) - (Qy * Qy) + (Qz * Qz) *********************************************************************/ void CvtQuatToRotationMatrix( QuatRotation *pdtQuatRot, RotationMatrix dtRotMatrix ) { float fQ0Q0, fQxQx, fQyQy, fQzQz, fQ0Qx, 168 Polaris Vega Application Program Interface Guide fQ0Qy, fQ0Qz, fQxQy, fQxQz, fQyQz; /* * Determine some calculations done more than once. */ fQ0Q0 = pdtQuatRot->fQ0 * pdtQuatRot->fQ0; fQxQx = pdtQuatRot->fQX * pdtQuatRot->fQX; fQyQy = pdtQuatRot->fQY * pdtQuatRot->fQY; fQzQz = pdtQuatRot->fQZ * pdtQuatRot->fQZ; fQ0Qx = pdtQuatRot->fQ0 * pdtQuatRot->fQX; fQ0Qy = pdtQuatRot->fQ0 * pdtQuatRot->fQY; fQ0Qz = pdtQuatRot->fQ0 * pdtQuatRot->fQZ; fQxQy = pdtQuatRot->fQX * pdtQuatRot->fQY; fQxQz = pdtQuatRot->fQX * pdtQuatRot->fQZ; fQyQz = pdtQuatRot->fQY * pdtQuatRot->fQZ; /* * Determine the rotation matrix elements. */ dtRotMatrix[0][0] = fQ0Q0 + fQxQx - fQyQy - fQzQz; dtRotMatrix[0][1] = 2.0 * (-fQ0Qz + fQxQy); dtRotMatrix[0][2] = 2.0 * (fQ0Qy + fQxQz); dtRotMatrix[1][0] = 2.0 * (fQ0Qz + fQxQy); dtRotMatrix[1][1] = fQ0Q0 - fQxQx + fQyQy - fQzQz; dtRotMatrix[1][2] = 2.0 * (-fQ0Qx + fQyQz); dtRotMatrix[2][0] = 2.0 * (-fQ0Qy + fQxQz); dtRotMatrix[2][1] = 2.0 * (fQ0Qx + fQyQz); dtRotMatrix[2][2] = fQ0Q0 - fQxQx - fQyQy + fQzQz; } /* CvtQuatToRotationMatrix */ Polaris Vega Application Program Interface Guide 169 B.5 DetermineEuler /******************************************************************* Name: DetermineEuler Input Values: RotationMatrix dtRotationMatrix :The 3x3 rotation matrix to convert. Output Values: Rotation *pdtEulerRot :Rotation is Euler angle format. Roll, pitch, yaw Euler angles which define the required rotation. Returned Value: None. Description: This routine calculates the Euler angles given the 3x3 rotation matrix. *******************************************************************/ void DetermineEuler( RotationMatrix dtRotMatrix, Rotation *pdtEulerRot ) { float fRoll, fCosRoll, fSinRoll; fRoll = atan2( dtRotMatrix[1][0], dtRotMatrix[0][0] ); fCosRoll = cos( fRoll ); fSinRoll = sin( fRoll ); pdtEulerRot->fRoll = fRoll; pdtEulerRot->fPitch = atan2( -dtRotMatrix[2][0], (fCosRoll * dtRotMatrix[0][0]) + (fSinRoll * dtRotMatrix[1][0]) ); pdtEulerRot->fYaw = atan2( (fSinRoll * dtRotMatrix[0][2]) (fCosRoll * dtRotMatrix[1][2]), (-fSinRoll * dtRotMatrix[0][1]) + (fCosRoll * dtRotMatrix[1][1]) ); } 170 /* DetermineEuler */ Polaris Vega Application Program Interface Guide B.6 CvtQuatToEulerRotation /************************************************************** Name: CvtQuatToEulerRotation Input Values: QuatRotation *pdtQuatRot :Ptr to the quaternion rotation. Output Values: Rotation *pdtEulerRot :Ptr to the determined rotation Euler angles. Returned Value: None. Description: This routine determines the rotation in Euler angles (degrees)that corresponds to the given quaternion rotation. ******************************************************************/ void CvtQuatToEulerRotation( QuatRotation *pdtQuatRot, Rotation *pdtEulerRot ) { RotationMatrix dtRotMatrix; CvtQuatToRotationMatrix( pdtQuatRot, dtRotMatrix ); DetermineEuler( dtRotMatrix, pdtEulerRot ); pdtEulerRot->fYaw *= RAD_TO_DEGREES; pdtEulerRot->fPitch *= RAD_TO_DEGREES; pdtEulerRot->fRoll *= RAD_TO_DEGREES; } /* CvtQuatToEulerRotation */ Polaris Vega Application Program Interface Guide 171 Abbreviations and Acronyms 172 Abbreviation or Acronym Definition API Application Program Interface CRC Cyclic Redundancy Check IEEE Institute of Electrical and Electronic Engineers IRED Infrared light Emitting Diode LED Light Emitting Diode LOS Line of Sight OOV Out of Volume PSE‘ Power Sourcing Equipment Rev xx Combined firmware revision. For example, rev 24 refers to combined firmware revision 024. RMS Root Mean Square SCU System Control Unit SROM Serial Read Only Memory TIP Tool-In-Port UV Refers to the rows and columns on the Position Sensor. U is the column number and V is the row number VCU Video Camera Unit Polaris Vega Application Program Interface Guide Glossary characterized measurement volume The characterized measurement volume is the volume within the field of view where accuracy is within specified limits. NDI cannot guarantee measurement accuracy performed outside this region. faces Tool faces are separate rigid bodies that make up a tool. Up to eight faces can be defined for one tool. firmware Firmware is a computer program stored in Polaris hardware and controls the Polaris System. maximum 3D error Maximum 3D error applies to individual markers. It is a parameter in the tool definition file, that specifies the maximum allowable difference between the actual and expected location of a marker on a tool. maximum marker angle Maximum marker angle is a parameter in the tool definition file, used to determine if the Position Sensor can view a specific marker and whether it should be included in the transformation calculated for the tool. missing If the system cannot detect a marker, that marker is considered missing. If the system cannot detect enough markers on a tool to determine a transformation, that tool is considered missing. SCU The System Control Unit (SCU) is a component of the hybrid Polaris Vega System. stray marker A stray marker is a marker that is not part of a tool. SROM device A tool definition file can be programmed into the SROM device so that the tool can carry its own information for automatic retrieval by an NDI measurement system. switch A switch, when activated, initiates certain actions in the associated software application. A tool may have switches incorporated into its design. Polaris Vega Application Program Interface Guide 173 tool definition file A tool definition file stores information about a tool. This includes information such as the placement of the tool's markers, the location of its origin, and its manufacturing data. A tool definition file is formatted as.rom. 174 Polaris Vega Application Program Interface Guide Index Index Numerics 3D command, 41 3D marker positions, 41 3D position markers on tools, 56, 144 single stray active marker, 54, 143 stray passive markers, 57, 146 A activation signature, 86 active tools activation signature, 86 electrical information, 98 number of ports available, 33, 122 active wireless tools number of ports available, 33, 122 alerts, 22, 32 simulated, 31 algorithm limitation, 53, 141 API revision, 46 APIREV command, 46 assigning a port handle, 102, 104 a tool definition file, 116 B bad transformation fit, 54, 142 battery, 145 baud rate, 70 BEEP command, 47 beeper, 31 buffer limitation, 53, 141 bump sensor reporting data when triggered, 56, 145 user parameters, 28, 31, 32 button box, 91, 97 BX command, 49 BX2 command, 60 C C routine defines, 164 calibration device, 97 Polaris Vega Application Program Interface Guide C-arm tracker, 97 catheter, 97 changes in implementation, 3 characterized measurement volume Polaris Vega, 125 selecting, 156 shape types and parameters, 124 user parameters, 30 combined firmware revision, 35, 154 COMM command, 70 commands complete list, 1 deprecated, 1 reply format, 13 syntax, 12 timeouts, 32 used with user parameters, 21 communication parameters, 70 with an NDI system, 11 configuration of a tool, 137 contact information, iv CRC calculating using a C routine, 165 reply format, 13 current sensing, 98 current test, 133 customer number, 34 D data bits, 70 data buffer limitation, 53, 141 default user parameter values, 73 defines, 164 deprecated commands list, 1 device address, 35 information, 35 instance, 35 names, 21 port, 35 type, 35 DFTL command, 73 Diagnostic mode, 12 start, 74 stop, 75 diagnostic pending, 51, 139 disabled port handle, 16, 50, 138 175 Index disabling keyed features, 161 port handles, 90 DSTART command, 74 DSTOP command, 75 dynamic tool, 91 E ECHO command, 76 electrical current test, 133 electrical information, 98 email NDI, iv enabled tools, 33 enabling keyed features, 161 port handles, 91 enumeration list, 80 error algorithm limitation, 53, 141 bad transformation fit, 54, 142 codes, 157 data buffer limitation, 53, 141 fell behind while processing, 53, 54, 141, 142 IR interference, 53, 54, 141, 142 not enough markers, 54, 142 processing exception, 51, 53, 54, 139, 141, 142 RMS error, 52, 140 synchronization, 51, 139 temperature out of range, 51, 139 Euler angles converting from quaternion, 171 converting to rotation matrix, 167 determining from rotation matrix, 170 determining sine and cosine, 166 F feature keys, 33 enabling and disabling, 161 multi firmware, 162 password protect, 119, 163 positioning laser, 163 features of the system, 121 fell behind while processing, 53, 54, 141, 142 firmware multiple versions, 162 versions, 154 foot switch, 97 frame number, 53, 141 176 freeing port handles, 95 G GET command, 77 GETINFO command, 79 GETIO command, 81 GETLOG command, 81 H handles see port handles hard reset, 118 hardware device see device hardware handshaking, 71 hardware model, 34 I illuminator rate, 31 image capture user parameters, 30 information user parameters, 32 INIT command, 83 initializing port handles, 107 the system, 83 input/output line setting, 121 status, 81 IR interference, 53, 54, 141, 142 IRATE command, 84 IRED command, 86 IRED marker activation, 86 isolation box, 97 K keyed features, 33 enabling and disabling, 161 multi firmware, 35, 162 password protect, 163 positioning laser, 163 Polaris Vega Application Program Interface Guide Index L laser keyed feature, 163 status, 30 LED see also visible LEDs LED command, 88 line separation, 43, 44 list of commands, 1 log file, 33 retrieving, 81 writing to, 131 M manufacturer’s ID, 97 markers 3D positions, 41 activating, 86 information, 54, 142 missing, 54, 142 wavelength, 100 maximum marker angle, 54, 142 microscope, 97 missing marker, 54, 142 transformation, 53, 141 mode, 32 Diagnostic, 12 Setup, 12 Tracking, 12 model, 34 modes of operation, 12 multi firmware feature, 35, 162 N NDI, iv not enough markers, 54, 142 O operating modes, 12 Polaris Vega Application Program Interface Guide out of volume markers on tools, 56, 142, 144 reporting OOV data, 56, 145 stray active marker, 55, 143 stray passive markers, 57, 146 tools, 53, 141 output line setting, 121 status, 81 P parameters see user parameters parity, 71 part number of tool, 99 partially out of volume, 53, 141 passive tools number of ports available, 33, 122 password protect feature, 119, 163 PDIS command, 90 PENA command, 91 PFSEL command, 93 phantom markers, 45 PHF command, 95 PHINF command, 96 PHRQ command, 102 PHSR command, 104 physical port location, 100 PINIT command, 107 port handles, 104 about, 16 disabled, 138 disabling, 90 enabling, 91 freeing, 95 information, 104 initializing, 107 physical location, 96 physical port location, 100 requesting, 102 status, 96, 104 tool information, 96 unoccupied, 17 port status, 53, 98, 141 positioning laser feature, 163 PPRD command, 109 PPWR command, 110 probe, 97 processing exception, 51, 53, 54, 139, 141, 142 PURD command, 112 PUWR command, 114 PVWR command, 116 177 Index Q quaternion converting to Euler angles, 171 converting to rotation matrix, 168 R reading the SROM device, 109, 112 receiving replies, 13 reference tool, 97 releasing port handles, 95 reply format, 13 requesting a port handle, 102 RESET command, 118 resetting the system, 118 revision of API, 46 RMS error, 52, 140 rotation matrix converting from Euler, 167 converting from quaternion, 168 converting to Euler angles, 170 S SAVE command, 119 sending commands, 12 sensitivity level, 31 serial communication parameters, 70 serial number Position Sensor, 34 tool, 98 SET command, 120 SETIO command, 121 settings user parameters, 30 Setup mode, 12 SFLIST command, 121 simulated alerts, 31 soft reset, 118 software-defined tool, 97 SROM device reading, 109, 112 writing to, 110, 114 SROM Image file see tool definition file start Diagnostic mode, 74 Tracking mode, 135 178 static tool, 91 status port handles, 53, 96, 141 switches, 98, 141 system, 51 stop Diagnostic mode, 75 Tracking mode, 136 stop bits, 71 stray markers 3D position, 146 active, 54 passive, 57 STREAM command, 129 strober, 97 switches number of, 97 status, 98, 141 supported, 99 sync port setting the value, 121 status, 81 synchronization error, 51, 139 syntax, 12 SYSLOG command, 131 system alerts, 22, 32 system battery, 145 system beeper, 31, 47 system configuration user parameters, 35 system control processor, 154 system features, 121 system log, 33, 131 system mode, 32 system status, 51, 139 T TCTST command, 133 temperature out of range error, 51, 139 reporting data, 145 test configuration, 137 testing electrical current, 133 timeout commands, 32 tool definition file, 116 Tool Docking Station, 97 tool-in-port, 98, 103, 105, 122 Polaris Vega Application Program Interface Guide Index tools active wireless, 33 enabled, 33 information, 54, 142 part number, 99 passive, 33 physical location, 100 revision, 97 serial number, 98 test configuration, 137 tracking LED, 99 tracking priority, 91 type, 97 tracking LED, 99 Tracking mode, 12 start, 135 stop, 136 tracking priority, 91 transformations bad fit, 54, 142 binary, 49 disabled, 16 missing, 53, 141 text, 138 TSTART command, 135 TSTOP command, 136 TTCFG command, 137 TX command, 138 type of tool, 97 U unique geometry requirements, 91, 160 unoccupied port handle, 17 user parameters about, 20 alerts parameters, 22 bump sensor parameters, 28 commands, 21 device names, 21 enumeration list, 80 hardware device information, 35 image capture parameters, 30 information parameters, 32 restoring default values, 73 retrieving descriptive information, 79 retrieving values, 77 saving values, 119 setting values, 120 settings parameters, 30 system configuration, 35 video camera parameters, 28 video camera user parameters, 37 volume user parameters, 37 USTREAM command, 150 V VCAP command, 151 VER command, 154 version of API, 46 versions of firmware, 154 video camera user parameters, 28 visible LEDs controlling, 88 number of, 97 supported, 99 tool tracking LED, 99 VSEL command, 156 W warning codes, 91, 160 warning message, 108 warnings, iii wavelength of markers, 100 writing to the SROM device, 110, 114 Polaris Vega Application Program Interface Guide 179