1. No category

NDI Combined API Sample
User Guide
Revision 4
April 2008
IMPORTANT
Please read this entire
document before using the
NDI Combined API Sample
Revision Status
Revision Number
Date
Description
1
September 2005
First release, for version 2.01 of
NDI Combined API Sample
2
September 2005
Updated for version 3.01 of NDI
Combined API Sample
3
June 2006
Updated for version 3.02 of NDI
Combined API Sample
4
April 2008
Removed reference to wireless
communications (Bluetooth).
Part number: IL-1070108
Copyright 2005-2008 Northern Digital Inc. All Rights Reserved.
p Printed in Canada.
Disclaimer of Warranties and Limitation of Liability
Published by:
Northern Digital Inc.
103 Randall Dr.
Waterloo, Ontario, Canada N2V 1C5
Telephone:
Toll Free:
Global:
Facsimile:
Website:
+1 (519) 884-5142
+1 (877) 634 634 0
++ (800) 634 634 00
+1 (519) 884-5184
www.ndigital.com
Copyright 2005-2008, Northern Digital Inc.
All rights reserved. No part of this document may be reproduced, transcribed, transmitted, distributed, modified, merged, translated into any language or used in any
form by any means - graphic, electronic, or mechanical, including but not limited to
photocopying, recording, taping or information storage and retrieval systems - without
the prior written consent of Northern Digital Inc. Certain copying of the software
included herein is unlawful. Refer to your software license agreement for information
respecting permitted copying.
Disclaimer of Warranties and Limitation of Liabilities
Northern Digital Inc. has taken due care in preparing this document and the programs
and data on the electronic media accompanying this document including research,
development, and testing.
This document describes the state of Northern Digital Inc.’s knowledge respecting the
subject matter herein at the time of its publication, and may not reflect its state of
knowledge at all times in the future. Northern Digital Inc. has carefully reviewed this
document for technical accuracy. If errors are suspected, the user should consult with
Northern Digital Inc. prior to proceeding. Northern Digital Inc. makes no expressed or
implied warranty of any kind with regard to this document or the programs and data
on the electronic media accompanying this document.
Northern Digital Inc. makes no representation, condition or warranty to the user or
any other party with respect to the adequacy of this document for any particular purpose or with respect to its adequacy to produce a particular result. The user’s right to
recover damages caused by fault or negligence on the part of Northern Digital Inc.
shall be limited to the amount paid by the user to Northern Digital Inc. for the provision of this document. In no event shall Northern Digital Inc. be liable for special, col-
NDI Combined API Sample User Guide - Revision 4
lateral, incidental, direct, indirect or consequential damages, losses, costs, charges,
claims, demands, or claim for lost profits, data, fees or expenses of any nature or
kind.
Product names listed are trademarks of their respective manufacturers. Company
names listed are trademarks or trade names of their respective companies.
NDI Combined API Sample User Guide - Revision 4
Table of Contents
Table of Contents
Read Me First . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii
Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii
Updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii
1
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 What is the NDI Combined API Sample? . . . . . . . . . . . . . . . . . . . 1
1.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2
Using NDI Combined API Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1 Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 System Communication Commands . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 Extras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3
Source Code Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
NDI Combined API Sample User Guide - Revision 4
i
Read Me First
Read Me First
This guide supports the NDI Combined API Sample, version 3.02.
For more information on the API, see:
•
For Aurora: the “NDI Polaris and Aurora Combined
Application Programmer’s Interface Guide.”
•
For Polaris, Polaris Vicra, and Polaris Spectra: the “Polaris
Application Program Interface Guide.”
Contact Information
If you have any questions regarding the content of this guide or the
operation of this product, please contact us:
Updates
NDI is committed to continuous improvements in the quality and
versatility of its software and hardware. To obtain the best results with
your NDI system, check the NDI Support Site regularly for update
information:
http://support.ndigital.com
ii
NDI Combined API Sample User Guide - Revision 4
Overview
1 Overview
1.1 What is the NDI Combined API Sample?
NDI Combined API Sample is intended to be used as a sample
executable, with the entire source code for the program provided for
reference. The source code uses RS-232 communications to illustrate
sending commands to and parsing responses from a Polaris System, a
Polaris Vicra System, a Polaris Spectra System, or an Aurora System.
The source code directory contains all of the files required to build an
executable. It includes both source code files and project files.
1.2 Requirements
System Requirements
NDI Combined API Sample is intended to run on Windows NT 4.0, 2000
and XP operating systems.
Hardware Requirements
Product
Firmware Revision
Polaris
Combined firmware revision 024 or later
Polaris Vicra
Combined firmware revision 001 or later
Polaris Spectra
Combined firmware revision 002 or later
Aurora
Combined firmware revision 001 or later
Compiler Requirements
NDI Combined API Sample was created and compiled using Microsoft's
Visual C++ 6.0. It has not been tested with other compilers, and thus is
not guaranteed to work with other compilers.
NDI Combined API Sample User Guide - Revision 4
1
Overview
1.3 Installation
To install the NDI combined API sample, copy the contents of the
“NDICombinedAPISample” folder from the CD onto the host computer.
2
NDI Combined API Sample User Guide - Revision 4
Using NDI Combined API Sample
2 Using NDI Combined API Sample
This sample code uses the NDI Combined API. Some options are systemspecific and therefore might not be available for the system you are using.
2.1 Settings
The settings are stored in the CombinedAPISample.ini file.
Communication Settings
Communication settings allow you to specify the COM port parameters:
port number, data bits, baud rate, stop bits, parity, hardware handshaking,
and timeout value. The timeout value is the amount of time the program
polls the COM port for a reply before assuming communication has been
lost.
When you start the NDI Combined API Sample application, make sure
that the “Reset hardware upon initialization” option in the COM port
settings is selected. To select this option, select Settings > COM Port
Settings. Ensure that the “Reset hardware upon initialization” check box
contains a check mark.
Note If this option is not selected, the hardware will not be set to the correct
baud rate when the system is initialized, which can result in a
communications timeout.
ROM File Settings
ROM file settings allow you to specify the tool definition files (.rom) to
be loaded to the system.
Illuminator Activation Rate (Polaris and Polaris Spectra only)
The illuminator activation rate for the Polaris System and the Polaris
Spectra System can be set to 20 Hz, 30 Hz, or 60 Hz while the system is
in any mode except tracking.
NDI Combined API Sample User Guide - Revision 4
3
Using NDI Combined API Sample
2.2 System Communication Commands
Reset System
This command sends a serial break to the COM port to reset the system,
and resets the main dialog.
Initialize System
This command initializes the system, polls the system for VER and
SFLIST information (viewable in System Properties), places the dialog
in initialized mode, and determines which type of system is connected.
Activate Handles
This command retrieves or requests port handles, initializes and enables
the port handles, loads tool definition files to port handles that have tool
definition files specified, and gathers all the information to display under
Tool Properties.
Start Tracking
This command places the system in tracking mode, and displays the
transformations in the main dialog. You can switch between BX (binary
transformations) and TX (text transformations), and specify whether to
use the 0x0800 option.
Stop Tracking
This command stops tracking and returns the program to setup mode.
2.3 Extras
System Properties
This dialog displays system properties that are read upon initialization.
4
NDI Combined API Sample User Guide - Revision 4
Using NDI Combined API Sample
COM Port Timeouts
The program will timeout if its connection to the system is lost, or if the
amount of time required to receive a response from the system exceeds
the specified timeout value. In this case, you will be presented with three
options:
•
Retry: attempts to resend the command, and polls for the
response for the specified amount of time (timeout value).
•
Restart: restarts the application and cancels the current COM
port communication.
•
Close Application: closes the application and cancels the
current COM port communication.
Note For the Polaris and Aurora Systems, the timeout values are specified in
the INI file. For the Polaris Vicra and Polaris Spectra Systems, the timeout
values are specified in the Info.Timeout.* parameters. Use the GET
command to view the values of these parameters.
Tool Properties
Once port handles have been initialized, you can view the handle
properties by selecting the port handle from the combo box located on the
main dialog. If the system is not in tracking mode, you have the option of
disabling the tool by toggling the Handle Enabled check box.
Tracking Modes
The program can report transformations in TX (text transformation) and
BX (binary transformation) formats. To change between formats, toggle
the radio buttons located on the main dialog. You can also specify the use
of the 0x0800 tracking flag, and whether to report transformations as
Euler angles instead of quaternion units.
Reference Handle
If you select a reference handle, the program will report the
transformations of other tools with respect to the position and orientation
NDI Combined API Sample User Guide - Revision 4
5
Using NDI Combined API Sample
of the reference tool. The current reference tool is indicated by the letter
R in front of its port handle.
System Information
The system information area displays information while tracking. It will
display the following:
•
the frame number
•
“temperature out of range” and “diagnostic pending” messages
(Polaris Vicra and Polaris Spectra only)
Click the button to see the diagnostic alert flags (described in
more detail in the “Polaris Application Program Interface
Guide”).
Legend
While tracking the tool, the Status column in the tracking table will show
one of the following:
6
•
POOV - the tool is partially out of volume, but can still be
tracked by the system. If Report out of volume
transformations is checked, the system will report
transformations; otherwise, the system will report that the tool is
missing.
•
OOV - the tool is out of volume, but can still be reported by the
system. If ‘Report out of volume transformations’ is checked,
the system will report transformations; otherwise, the system
will report that the tool is missing.
•
OK - the tool is within the characterized measurement volume
and is being tracked.
•
--- - the system cannot track the tool.
NDI Combined API Sample User Guide - Revision 4
Source Code Explanation
3 Source Code Explanation
CombinedAPISample.cpp This is the source file created by Visual C++
when the project is created. It controls the main dialog.
CombinedAPISampleDlg.cpp This is the code for the main dialog. It
controls all of the calls made by and to the main dialog. This file controls
the creation of the supporting dialogs and the CommandHandling class. It
controls the entire user interaction section of the program.
Comm32.cpp This is the code for communicating with the
communications port. It includes code for sending messages to and
getting responses from the system attached to the port. It also has code for
opening, initializing and closing the port.
CommandConstruction.cpp This is the code to construct a command. It
takes a command string, and if specified replaces the space with a ‘:’ and
calculates and attaches a CRC for the command. The code also attaches a
carriage return to the command.
CommandHandling.cpp This is the main class that controls creating
commands, sending them to the systems, receiving the response, and
parsing the response. This routine parses the responses into variables and
structures that can be called by the parent class for displaying purposes.
ComPortSettings.cpp This is the code that controls the COM Port
Settings dialog. It controls all input from the user regarding the COM
port and interacts directly with the INI file to both recall and store the
information for future reference.
ComPortTimeout.cpp This is the code that controls the COM Port
Timeout dialog. This dialog is displayed when there has been a timeout
while communicating with the system. The dialog gives the user three
options: restart the program, retry the command, or close the program.
Conversions.cpp This file is responsible for all the math conversions
used to change binary and hexadecimal values to the ASCII, integer or
float value. These conversions are mainly used while tracking in binary
mode.
IlluminatorFiringRate.cpp This file controls the Illuminator Activation
Rate dialog box. It accepts input from the user for the illuminator
activation rate (Polaris only). It interacts directly with the INI file to both
save and recall the appropriate value.
NDI Combined API Sample User Guide - Revision 4
7
Source Code Explanation
INIFileRW.cpp This file contains all of the routines required for
communication with the INI file. It has both read and write routines, in
order to receive information from and write information to the INI file. It
has routines for all variable types that may be read from the INI file.
NewAlertFlagsDlg.cpp This file controls the display of Polaris Vicra and
Polaris Spectra alerts returned with the alerts parameters.
ProgramOptions.cpp This file controls the Program Options dialog box.
It accepts input from the user for program files, switches, and flags. It
interacts directly with the INI file to both save and recall the appropriate
values.
ROMFileDlg.cpp This file controls the SROM Image File dialog box. It
accepts input from the user for the tool definition files to be virtually
loaded to the system. It displays only the ports that are available. It
initializes the system if the system hasn’t already been initialized. It
interacts directly with the INI file to both save and recall the appropriate
values.
SystemCRC.cpp This file contains all of the routines required to calculate
CRCs and to verify that the CRCs coming back are valid. These routines
are defined in the CommandHandling header file.
SystemFeaturesDlg.cpp This file controls the System Features dialog.
This dialog displays the features of the currently attached system. It
receives input from the main dialog and displays information obtained
using VER and SFLIST calls.
APIStructures.h This header file contains all of the structures and
variables required while parsing information received from the system.
Note All .cpp files have corresponding headers (.h extension).
8
NDI Combined API Sample User Guide - Revision 4
Index
Index
A
initialize system 4
installing 2
activate ports 4
APIStructures.h 8
N
C
COM port 3
CombinedAPISample.cpp 7
CombinedAPISample.ini 3
CombinedAPISampleDlg.cpp 7
Comm32.cpp 7
CommandConstruction.cpp 7
CommandHandling.cpp 7
communication settings 3
compiler requirements 1
ComPortSettings.cpp 7
ComPortTimeout.cpp 7
contacting NDI ii
Conversions.cpp 7
NDI Combined API Sample
defined 1
installing 2
overview 1
requirements 1
settings 3
NewAlertFlags.Dlg.cpp 8
O
OOV 6
P
H
hardware requirements 1
POOV 6
ports 4
ProgramOptions.cpp 8
I
R
illuminator activation rate 3
IlluminatorFiringRate.cpp 7
information about the system 6
INIFileRW.cpp 8
reference handle 5
reset system 4
ROM file settings 3
ROMFileDlg.cpp 8
NDI Combined API Sample User Guide - Revision 4
9
Index
S
settings 3
system communication 4
system information 6
system properties 4
system requirements 1
SystemCRC.cpp 8
SystemFeaturesDlg.cpp 8
tool port properties 5
tool status 6
tracking
reference handle 5
setting modes 5
start tracking 4
stop tracking 4
system information 6
tool status 6
T
U
timeouts 5
tool definition files (.ROM) 3
updates, obtaining ii
10
NDI Combined API Sample User Guide - Revision 4