Welcome

Polhemus Tracker SDK v2.1.3

Polhemus Tracker SDK v2.1.3

Welcome to the Polhemus Tracker Software Development Kit.

The core of this kit is the Polhemus Developer Interface (PDI) library. The PDI is the application developer's window to configuring, managing, and capturing data from the Polhemus Liberty and Patriot trackers, the state-of-the-art in electromagnetic motion tracking.

With the PDI, Polhemus has created a new standard in ease-of-use from the software developer's perspective: arguably the frontline of tracker use.

The PDI contains C++ header files, library files, code samples, and HTML online help: everything you need to get up and running your tracker in your own applications in a very short time.

Online Help Overview

The chapters of the Polhemus Tracker SDK online help are outlined below. Jump to the chapter that interests you most, or start at the beginning and browse the whole book. For a quick start in using the PDI, try building and running one of the sample programs.

Audience

The Polhemus Tracker SDK online help assumes a working knowledge of C++ and basic Windows application programming.

Getting Started

This section will guide you through installation of the tracker host software (including the PDI itself), and setting up your MS Visual Studio environment to use the PDI.

Sample Applications

The sample programs demonstrate features of the PDI and their use. Each sample project is a fully buildable and pre-configured MS Visual Studio project, ready to build and run.

PDI Reference

Once you are started, the PDI reference section will be the most-used part of this document. For getting started, it contains a step-by-step guide to using the PDI library. After that, there are detailed topics describing each class in the PDI, and all of their members, as well as PDI types and message IDs.


Legal Information

Copyrights

Information in this document is subject to change without notice. Complying with all applicable copyright laws is the responsibility of the user.

Alken Incorporated may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Alken, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Copyright © 2004 by Alken Inc. dba Polhemus.

Colchester, Vermont U.S.A.

All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording or otherwise, without the prior written permission of Alken Incorporated. No patent liability is assumed with respect to the use of the information contained herein. While every precaution has been taken in the preparation of this book, Alken Incorporated assumes no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from use of the information contained herein.

3SPACE® is a registered trademark of Polhemus; Liberty™ and Patriot™ are trademarks of Polhemus.

Microsoft, MS, Windows, Windows NT, Windows 2000, Windows XP, MS-DOS, MSDN, Developer Studio, the Visual Studio logo, Visual C++, MFC, Win32, Win32s, and Win64 are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

Licensing

The Licensed Materials are protected by copyright laws, international copyright treaties, and trade secret laws, as well as other intellectual property laws and treaties. The Licensed Material are licensed, not sold to you. Alken Inc. dba Polhemus retains title and ownership of the Polhemus Tracker SDK Materials, including all intellectual property rights in the Polhemus Tracker SDK Materials and all copies thereof.

The Licensed Materials contain copyrighted material, trade secrets and other proprietary information. In order to protect the Licensed Materials, and except as specifically permitted by statute by a provision that cannot be waived by contract, you may not unlock, decompile, reverse engineer, disassemble or otherwise translate any binary or object code versions of the software programs included in the Licensed Material to human-perceivable form. You also agree that you will use your best efforts to prevent your employees and contractors from unlocking, decompiling, reverse engineering, disassembling, modifying or translating the Licensed Materials. Alken Inc. dba Polhemus reserves all rights not specifically granted under this agreement.

The licensed materials are provided "As Is." Alken Inc. dba Polhemus makes no warranties or representations, either express, or implied or statutory, including any implied warranties of merchantability, fitness for a particular purpose, lack of viruses, accuracy or completeness of responses, results, and lack of negligence. Alken Inc. dba Polhemus disclaims any warranty of title, quiet enjoyment, quiet possession, and non-infringement of any third party intellectual property rights with regard to the Licensed Materials or your use of those Materials.

In no event shall Alken Inc. dba Polhemus be liable under any circumstances for special incidental or consequential damages including, but not limited to loss of profits or revenue. Without limiting the foregoing Alken Inc. dba Polhemus maximum liability for damages for any cause whatsoever, exclusive of claims for patent infringement and regardless of the form of the action (including but not limited to contract negligence or strict liability) shall be limited to buyer's actual direct damages, not to exceed the price of the goods upon which such liability is based.


Getting Started

  1. Set up the tracker. Refer to Tracker Manual.

  2. Install the SDK.

  3. Set up your Microsoft Visual Studio 6 environment.

  4. Review the Sample Applications.

  5. Write your own.


Installing

Polhemus Tracker SDK v2.1.3

Installing the Polhemus Tracker SDK

To install the Polhemus SDK and its components:

1. Insert the disk that came with your tracker into the CD-ROM drive of your host computer.

2. Run the "Install Host SW" self-installing executable located in the root directory of the CD-ROM.

3. Select any of the configurations available, and make sure that the "SDK" option is selected.


Working with Visual Studio 6

To use the PDI in your Visual Studio project, perform the steps outlined below.

Set up the Include path

In your VS project, navigate to Project Settings→C/C++ Tab→Category Preprocessor.

To the Additional include directories field, add:

C:\Program Files\Polhemus\PDI\Inc

This is the default installed path of the PDI. If you installed the PDI to another location, input that path instead.

Set up the Link path

In your VS project, navigate to Project Settings→Link Tab→Category Input.

To the Object/Library modules field, add:

PDID.lib (For Debug build)

or

PDI.lib (For Release build)

Note: If you use the debug version of the PDI, you will see occasional TRACE statements from the PDI in your Visual Studio output window. You may find these useful, or annoying.

To the Additional Libraries field, add:

C:\Program Files\Polhemus\PDI\Lib

This is the default installed path of the PDI. If you installed the PDI to another location, input that path instead.

At Run Time

To run, your application will need to be able to locate the PDI DLL file that it is using. This can be accomplished in a couple of ways.

  1. Copy the appropriate DLL to the directory that your program will run from. By default installation, the DLLs are located at:

    C:\Program Files\Polhemus\PDI\Lib\

    If you installed the PDI to another location, look in the Lib directory in that location. The DLL files are called PDID.dll (Debug build) and PDI.dll (Release build).

  2. For debugging within the Visual Studio environment, you can also add the above path to Options→Directories→Library Files.


Sample Applications

All sample applications are located in the PDI\Samples folder of your default Polhemus installation.

  1. PDImfc - A Visual C++/MFC project. Uses windows messages to capture P&O.

  2. PDIconsole - A Visual C++ Windows console application project.

  3. PDImulti - A Visual C++/MFC MDI application project demonstrating how to manage multiple trackers. Queries current P&O from the windows message loop.


PDImfc

Polhemus Tracker SDK v2.1.3

PDImfc Sample Project

The PDImfc project is a simple MFC dialog-based project that demonstrates the following uses of the PDI:

  • CPDIdev object instantiation.

  • Tracker connection management via CPDIdev::DiscoverCnx(),
 CnxReady(),
 SetSerialIF(), &
 Disconnect().

  • Sensor activation via CPDIdev::EnableSensor().

  • P&O output data configuration via CPDImdat, CPDIdev::SetSDataList().

  • P&O buffer management via CPDIdev::SetPnoBuffer() & LastPnoPtr().

  • Single P&O frame collection via CPDIdev::ReadSinglePno().

  • Continuous P&O frame collection via CPDIdev::StartContPno(), StopContPno() and message handling.

  • PDI error parsing with CPDIdev::GetLastResultStr() & ResultStr().


PDIconsole

Polhemus Tracker SDK v2.1.3

PDIconsole Sample Project

The PDIconsole project is a simple console-based Windows application project that demonstrates tracker data capture without the overhead of Windows messages. It demonstrates the following uses of the PDI:

  • CPDIdev object instantiation.

  • Tracker connection management via CPDIdev::DiscoverCnx(),
 CnxReady(),
 SetSerialIF(), &
 Disconnect().

  • P&O output data configuration via CPDImdat, CPDIdev::SetSDataList().

  • P&O buffer management via CPDIdev::SetPnoBuffer() & LastPnoPtr().

  • Single P&O frame collection via CPDIdev::ReadSinglePnoBuf().

  • Continuous P&O frame collection via CPDIdev::StartContPno(), StopContPno(), without the use of message handling. P&O data is collected synchronously by calling LastPnoPtr().

  • PDI error parsing with CPDIdev::GetLastResultStr() & ResultStr().


PDImulti

Polhemus Tracker SDK v2.1.3

PDImulti Sample Project

The PDImulti project is an MFC Multi-Document-Interface (MDI) project that demonstrates how to connect to and manage multiple trackers from one host application. Each "new document" in the MDI searches for a new tracker on the host system, and if found, connects to that tracker.

  • CPDIdev object instantiation.

  • Tracker connection management via CPDIdev::DiscoverCnx(),
 CnxReady(), &
 Disconnect().

  • Tracker management via CPDIdev::SetEcho(),
 GetBITErrs(),
 ClearBITErrs(), &
 WhoAmI().

  • P&O output data configuration via CPDImdat, CPDIdev::SetSDataList().

  • Single P&O frame collection via CPDIdev::ReadSinglePnoBuf().

  • Continuous P&O frame collection via CPDIdev::StartContPno(), StopContPno(), and LastPnoPtr(). In this sample project, P&O frames are sampled in the application's message loop idle time. Windows messages are not used. This enables the application to "keep up" with a high volume of tracker data without degrading Windows performance. In this sample, the P&O buffer is not employed; therefore every frame captured from the tracker is not preserved by the application. However, addition of the P&O buffer is a simple exercise. See the PDImfc project for an example.

  • PDI error parsing with CPDIdev::GetLastResultStr().


Programming

Polhemus Tracker SDK v2.1.3

PDI Reference: Programming with the PDI

How the PDI Works

The PDI resides in a Dynamic Linked Library (DLL) that your application links to at runtime. The primary interface to the tracker you are managing is through instantiation of an object of type CPDIdev. Through CPDIdev, you will set and read tracker device configuration parameters and collect real-time motion data.

Step-By-Step

  1. Create a tracker object.

  2. Establish a connection.

  3. Configure the tracker.

  4. Collect Motion Data.

  5. Terminate the connection.

Additional Information

Using the Tracker Data store, Using a Stylus


Create a Tracker Object

The first step to managing a Polhemus tracker programmatically is to create an instance of the CPDIdev class. CPDIdev is your interface to the Polhemus device. You need to create one instance of CPDIdev for each tracker that you intend to manage with your application.

CPDIdev m_pdiDev;

The device object that you create should be maintained for the duration of the session with the tracker. That is, you do not want to create an object that is either local or temporary in scope unless you want your program's contact with the tracker to also be temporary. In most cases, you will create the object either as a member of another class whose lifetime equals the lifetime of the application (see the PDImfc sample program) or as a global object.


Connecting to the Tracker

Polhemus Tracker SDK v2.1.3

Connect to the Tracker

The easiest way to do this is to make a call to CPDIdev::DiscoverCnx(). DiscoverCnx() searches for a tracker connection first via USB, then on serial ports COM1 thru COM4. The type of connection (USB or Serial, or none) is returned.

ePiCommType eType = m_pdiDev.DiscoverCnx();

Note that DiscoverCnx() queries the four COM ports, but it does not attempt all combinations of serial port configurations. The default serial port configuration is 115,000 bps and NO parity. If you require different serial port settings, a call to CPDIdev::SetSerialIF() is required before calling DiscoverCnx().

If your tracker is plugged into a serial port other than COM1 thru COM4, DiscoverCnx() will not locate it. You must call CPDIdev::ConnectSer() to establish the connection explicitly.

CPDIdev::ConnectUSB() may be called to find a USB tracker connection.

A single CPDIdev object may control one and only one tracker connection. If there is more than one tracker connected to your host computer, DiscoverCnx will find the next available tracker connection that is not already in use by another instantiation of CPDIdev. See CPDIdev::DiscoverCnx() for more details about connecting to multiple trackers.

If a connection is already established when any connection method (DiscoverCnx(), ConnectSer(), or ConnectUSB()) is called, that connection will be destroyed before attempting a new connection.

Verifying the Connection

Successful establishment and verification of a tracker connection means that the tracker has been contacted and has responded to a short series of automatic initialization commands without error. The initialization commands are equivalent to the following:

  • CPDIdev::SetBinary The PDI requires data transfer with the tracker to be in binary mode.

  • CPDIdev::WhoAmI

  • CPDIdev::GetSavedLabels

Terminating the Connection

Call CPDIdev::Disconnect() to end the session.

m_pdiDev.Disconnect();


Configure the Tracker

The CPDIdev class has many methods for querying and setting tracker configuration parameters:

Device-Level Settings:

  • Active Station Map:

CPDIdev::GetStationMap() and SetStationMap().

  • Attitude Filter:

CPDIdev::GetAttFilter() and SetAttFilter().

  • Position Filter:

CPDIdev::GetPosFilter() and SetPosFilter().

  • Source Frame Rotation:

CPDIdev::GetSourceFrame() and SetSourceFrame().

  • External Sync:

CPDIdev::GetSyncEnabled() and SetSyncEnabled().

  • Units of Measure:

CPDIdev::GetMetric() and SetMetric().

  • Data Format:

CPDIdev::GetBinary() and SetBinary().1

  • Compensation:

CPDIdev::GetCompState(),
     SetCompState(), and
     GetSavedMaps().

  • Echo Mode :

CPDIdev::GetEcho() and SetEcho().2

Notes:
  1. In most circumstances, it is not necessary to set the data format. When using the PDI, all tracker I/O is in BINARY format. The PDI sets the data format to BINARY whenever a tracker connection is made. The only time that it might be necessary to set the tracker to ASCII mode is if you are exiting your application and you want to leave the tracker in a state where (manual) output is human-readable.

If you set the tracker to ASCII mode during a tracker session, the PDI will no longer recognize responses from the tracker, and most function calls will fail. The only functions that would succeed in this state would be the CPDIdev::TxtCmd(), which is designed to pass caller-defined text strings to the tracker and return the tracker response with no error checking, CPDIdev::SetBinary(), and CPDIdev::GetBinary().

  2. It is also usually unnecessary to configure the tracker's echo mode. When using the PDI, no benefit is gained by having each command echoed back to the host. Echo mode is primarily intended for the manual ASCII user.

Per-Sensor Settings:

  • Sensor Activation:

CPDIdev::EnableSensor().

  • Output Motion Data List:

CPDIdev::GetSDataList() and SetSDataList().

  • Alignment:

CPDIdev::GetSAlignment(),
     SetSAlignment(), and
     ResetSAlignment().

  • Boresight:

CPDIdev::GetSBoresight(), SetSBoresight(), and ClearSBoresight().

  • Hemisphere:

CPDIdev::GetSHemisphere(), SetSHemisphere().

  • Hemisphere Tracking:

 CPDIdev::GetSHemiTrack() and SetSHemiTrack().

  • Stylus Mode:

CPDIdev::GetSStylusMode() and SetSStylusMode().

Notes:

  1. All per-sensor configuration settings can be applied to all sensors on the tracker by specifying PDI_ALL_SENSORS (-1) as the sensor number argument.
  2. The Output Motion Data List is set using class CPDImdat.

A bitmap that represents enabled stations in a tracker. Least significant bit (LSB) represents station one. A bit value of 1 indicates that station is enabled; 0 indicates disabled.

Sensitivity, Boundary, and Transition control parameters for the adaptive filter that operates on the attitude (az, el, roll) outputs of the tracker.

Active signal on the tracker's external event input. Tracker may be configured to place an external sync marker in P&O output when signal detected, or to ignore external sync signals.

Orientation angles (Az, El, Roll) to which the tracker references all of a sensors orientation output. All orientation outputs are relative to a sensor's boresight angles. The default boresight reference angles are (0, 0, 0).

The pushing of the stylus switch has no change on tracker output other than setting an event marker in the output record when the button is pressed. This marker is only output when specified in the output motion data list.

In echo mode, the tracker responds to configuration-modifying commands by "echoing" back the command that was received. This allows feedback to the ASCII user when modifying configuration settings. This may be most useful to a user that is operating the tracker directly through the RS-232 interface, and less useful when using the PDI.

In echo mode, the tracker responds to configuration-modifying commands by "echoing" back the command that was received. This allows feedback to the ASCII user when modifying configuration settings. This may be most useful to a user that is operating the tracker directly through the RS-232 interface, and less useful when using the PDI.


Collect Motion Data

Configure Data List

Configure the output data list(s). The default output data set for each sensor is Position, Euler Orientation, and <CR><LF>. Alternatively, or in addition, each sensor data list can be individually configured to deliver Quarternion, Direction Cosine, Frame Count, Timestamp , and Stylus or external sync flags. Use CPDIdev::SetSDataList() and CPDIdev::GetSDataList() to set and read the output data list configuration for each sensor.

Continuous Frame Collection

Once the output data list is set, continuous motion frame collection is accomplished through a series of steps.

  1. Supply an output buffer.

    The PDI places motion data collected from the tracker into a client-supplied buffer. When the end of the buffer is reached, the data wraps to the beginning of the buffer. The client is responsible for the memory-management of the buffer; that is, it is responsible for the size, and for allocating and destroying the buffer.

    The first step for the client is to allocate the buffer, and tell the PDI about it.

    #define MY_MOTION_BUF_SIZE 0x0800

    BYTE pMotionBuf[ MY_MOTION_BUF_SIZE ];

    m_pdiDev.SetPnoBuffer( pMotionBuf, MY_MOTION_BUF_SIZE );

  2. Start continuous collection.

    m_pdiDev.StartContPno( m_hWnd );

    If a valid window HANDLE is supplied with this call, then the PDI will notify the client program about received motion frames through the Windows message system. Therefore, the client must supply a window HANDLE to collect continuous motion data asynchronously via the messages described in step 3.

    If a window handle of zero is supplied to StartContPno(), continuous collection is started, but no Windows messages will be generated. Continuous motion data must then be collected synchronously, using methods described in step 4.

    When called, StartContPno() resets an internal Host Frame Count to zero. The Host Frame Count is incremented each time a P&O frame is received from the tracker. This counter may be queried or reset at any time by calling LastHostFrameCount() or ResetHostFrameCount(), respectively. This internal counter provides a host-based means of counting frames received from the tracker. Realtime tracker-originated frame count is available as part of the tracker's output data set using SetSDataList().

  3. Handle motion frame messages.

    During normal continuous output mode operation, the following windows messages will be sent from the PDI to the client, provided that a valid window handle was provided to StartContPno():

    • WM_PI_DATA_STARTED

      Posted immediately after a successful call to StartContPno(). No parameters are sent.

    • WM_PI_RAWDATA_READY

      As complete motion frames are received from the tracker, the PDI will place them in the client-supplied buffer and post this message. The parameters sent are the position and size of the new frame in the buffer.

      Note: When the PDI reaches the end of the client-supplied buffer such that the entire next frame will not fit into the remainder of the buffer, it will "wrap" and place the next frame at the beginning of the buffer. The PDI will not wrap in the middle of the frame.

    • WM_PI_RAWDATA_ERROR

      Posted when a runtime error has occurred with the received motion data. Continuous data will continue even after an error has occurred. It is the responsibility of the client to stop continuous collection if needed. An error code parameter is sent with this message.

    • WM_PI_RAWDATA_ WARNING

      Posted when an non-fatal runtime error has occurred with the received motion data. Continuous data will continue even after an error has occurred. It is the responsibility of the client to stop continuous collection if needed. An error code parameter is sent with this message. Non-fatal runtime errors are informational conditions rather than actual tracker or host system error conditions.

    • WM_PI_DATA_STOPPED

      Posted when continuous motion capture has ended. No WM_PI_RAWDATA_READY (or error) messages will be posted after this message.

  4. Manage the motion buffer, if necessary.

    During normal operation, the position in the client-supplied buffer may be managed and/or queried through the following methods.

    • CPDIdev::LastPnoPtr()

      Returns the position and size of the latest motion frame received.

      Note: If a zero window handle was supplied to the StartContPno call, this method is the only way that continuous motion data can be collected by the calling application.

    • CPDIdev::ResetPnoPtr()

      Resets the PDI's frame pointer so that the next frame received will be placed a the beginning of the buffer.

  5. Stop continuous collection.

    m_pdiDev.StopContPno();

Single Frame Collection

To get a single position & orientation "snapshot" from the tracker is to call CPDIdev::ReadSinglePno(). This will produce a single WM_PI_RAWDATA_READY message to the client containing a new motion data frame from the tracker.

Alternatively, a single frame may be collected synchronously by calling CPDIdev::ReadSinglePnoBuf(). This method returns directly with a pointer to a new motion frame from the tracker.

For both ReadSinglePno() and ReadSinglePnoBuf(), if an output buffer has been configured using SetPnoBuffer(), the new frame will be placed in the next buffer location.

Active signal on the tracker's external event input. Tracker may be configured to place an external sync marker in P&O output when signal detected, or to ignore external sync signals.

A positive integer value reported by the tracker indicating the relative frame number since the last frame initialization (zero). Rollover occurs after 2^32 frames. The frame count is initialized automatically on tracker power up or restart. The frame counting feature is always enabled in the tracker; it is only output when specified in the output motion data list.

A 3x3 matrix representing the cosines of the angles between a sensor's x, y, z axes and the X, Y, Z axes of the measurement reference (alignment) frame.

A four-parameter quantity representing a vector and a scalar. The quaternion q = q0 + i q1 + j q2 + k q3 can be used to represent a sensor's orientation without the need for trigonometric functions.

A host-side 32-bit frame counter incremented each time a complete P&O frame is received from the tracker. The Host Frame Count is automatically reset when Continuous Output Mode is started.

A positive integer value reported by the tracker indicating the number of milliseconds since the last timestamp initialization or reset. Rollover occurs after 2^32 milliseconds. Timestamp is initialized automatically on tracker power up or restart. The timestamping feature is always enabled in the tracker; timestamp is only output when specified in the output motion data list.


Using the Tracker Datastore

Polhemus Tracker SDK v2.1.3

Using the Tracker Data Store

The Polhemus Liberty Tracker has the ability to locally store 3 sets of custom configuration settings in addition to the factory default settings. Any stored configuration (including the factory default) can be designated the default configuration, activated when the tracker is powered up (by turning the device on) or restarted (by issuing a restart command).

In the context of the PDI, each location in the tracker data store is known as a data store slot. The data store has four 4 slots. Three (3) of the slots are available to store custom configurations. The remaining slot contains the factory default configuration, and cannot be overwritten. Through the PDI, each slot is referenced by the enumerated data type ePiConfigSlot. The value PICFG_SLOT_DEFAULT represents the slot containing the default configuration, and values PICFG_SLOT_1 through PI_CFG_SLOT_3 represent the programmable slots.

Configurations stored in data store slots are identified not only by the slot number, but by a unique configuration label that is assigned by the user. The configuration label is a null-terminated string with a maximum length of 15 characters, not including the null terminator.

Warning: The uniqueness of configuration labels saved in the data store is not enforced by the tracker or by the PDI.

The function CPDIdev::GetSavedLabels is used to retrieve the labels currently saved in the data store. The data store labels are represented in the PDIlabels data construct, which is an array of 16-character strings. In a system that has no custom configurations saved, the PDIlabels returned from GetSavedLabels will have the following values:

"Default\0"

"***************\0"

"***************\0"

"***************\0"

The first label indicates the default configuration in PICFG_SLOT_DEFAULT. The lower three labels indicate vacant data store slots PICFG_SLOT_1 through PI_CFG_SLOT_3. These strings are defined as PDI_DEFAULT_CONFIG_LABEL, and PDI_VACANT_CONFIG_LABEL, in defined PDIdefs.h.

Summary of Applicable Functions

The CPDIdev functions that deal with the Tracker Data store are the following:

CPDIdev::GetSavedLabels | Retrieves labels identifying custom configurations currently persisted in the tracker data store.
CPDIdev::GetCfgLabel | Retrieves label identifying currently active tracker configuration.
CPDIdev::SetCfgLabel | Sets label identifying currently active tracker configuration
CPDIdev::SaveCfgToSlot | Saves current tracker configuration to a tracker data store slot. To do this, the current configuration must be labeled.
CPDIdev::SetStartupSlot | Selects the data store slot containing the will be the default startup/restart configuration.
CPDIdev::GetStartupSlot | Retrieves the data store slot that is currently designated as the startup/restart configuration.

Step-by-Step

The following steps are necessary to store a configuration in the data store.

  1. Configure the tracker to your specifications. See Configuring the Tracker. The tracker is now configured with your custom configuration set.

  2. Give your custom configuration a label. In other words, label the tracker's current configuration. Use CPDIdev::SetCfgLabel to do this. You may wish to insure that the label you select is not already used in the tracker data store. Call CPDIdev::GetSavedLabels and examine the labels to determine that yours is not in use.

    At this point you may verify that the current configuration has your new label. Do this by calling CPDIdev::GetCfgLabel.

    Warning: If you change anything about the current configuration at this point, your label will be unusable.

    With one exception*, whenever configuration settings are changed in the tracker, the tracker will reset the configuration's label. The reason is this: At startup or restart, the tracker gets its current configuration from the data store slot identified as the startup slot (step X below). If, immediately after startup, you were to query the current configuration label using GetCfgLabel, it would return the label in the data store, e.g. "Default." Now if you change a setting in the configuration, for example the Attitude Filter or the Active Station Map , you are no longer using the Default configuration. Therefore, the tracker resets the configuration's label to "***************" (PDI_VACANT_CONFIG_LABEL) to indicate that the current configuration is unlabeled.

    * The CPDIdev::SetBinary function will not cause the label to be reset.

  3. Save the configuration to a data store slot. Use CPDIdev::SaveCfgToSlot to do this. Note that you cannot save your configuration to slot PICFG_SLOT_DEFAULT. If you call CPDIdev::GetSavedLabels again, you will now see your label in the slot you selected.

    Warning: If you change anything about the current configuration at this point, your changes will not be preserved in the data store slot.

    Any subsequent changes to the current configuration at this point will not be present in the configuration just saved to the data store. As described above, neither will the current configuration's label be preserved. (The label will still appear in the data store labels, just as you saved it.)

  4. Select the configuration as the default. If you want your custom configuration (or any other stored configuration) to be active the next time you restart the tracker, use CPDIdev::SetStartupSlot to select it.

    Note: The tracker will allow you to select a vacant slot as the default startup slot. If this happens: Upon restart, the tracker will revert to the default slot.

  5. Finally, if at any time, you wish to make a stored configuration the currently active configuration, you need to select it as the startup and then restart the tracker. This is done by calling CPDIdev::SetStartupSlot and then CPDIdev::RestartTracker.

A bitmap that represents enabled stations in a tracker. Least significant bit (LSB) represents station one. A bit value of 1 indicates that station is enabled; 0 indicates disabled.

Sensitivity, Boundary, and Transition control parameters for the adaptive filter that operates on the attitude (az, el, roll) outputs of the tracker.


Using a Stylus

The Polhemus tracker can be configured in two ways to work with an attached Polhemus Stylus: Mouse Mode, and Point/Track Mode.

Stylus Mouse Mode

In stylus Mouse mode, each time a stylus button is pressed, a flag is added to the station's current P&O frame indicating the stylus button push event. To capture this stylus event in your program, perform the following steps:

  1. Configure the station stylus mode to PI_STYMODE_MOUSE with a call to CPDIdev::SetSStylusMode().

  2. Make sure that the stylus is active by calling CPDIdev::EnableSensor() or CPDIdev::SetStationMap().

  3. Configure the stylus' CPDImdat output motion data list to include the PDI_MODATA_STYLUS stylus flag item. Do this with a call to CPDIdev::SetSDataList().

  4. Collect motion data from the tracker, in either continuous output or single frame mode. See Collect Motion Data for details.

Stylus Point/Track Mode

In stylus Point/Track mode, the stylus button acts as a switch to collect P&O data. When not in continuous output mode, the stylus button event causes the tracker to generate one frame of P&O data and send it to the host ("Point" mode). When in continous output mode, the tracker uses the stylus button event to start or stop the flow of continuous P&O data to the host ("Track" mode).

In either case, the host system must be ready to receive stylus-generated P&O frames asynchronously; it must engage in asynchronous frame collection.

  1. Configure the station stylus mode to PI_STYMODE_POINT with a call to CPDIdev::SetSStylusMode().

  2. Make sure that the stylus is active by calling CPDIdev::Enable Sensor() or CPDIdev::SetStationMap().

    If either of these steps is skipped, no data will be collected from the tracker, as the trigger event (stylus button push) will never be detected by the tracker.

    Note that in Point/Track mode, P&O data will be generated for every activated station on the tracker. If you are only interested in data from the stylus itself, make sure that the stylus is the only active station.

  3. Activate host asynchronous frame collection in the CPDIdev object by calling CPDIdev::StartStylusPno().

    At this point, P&O frames are generated asynchronously with each push of the stylus button. If non-continuous stylus-driven ("Point" mode) output is your goal, you are finished. If continuous ("Track" mode) data is what you are after, continue to step 4.

  4. Activate continuous output mode in the tracker by calling CPDIdev::StartContPno().

    This puts the tracker in continuous output mode. The host is already in asynchronous frame collection mode as a result of step 3.

    When the tracker is placed in continuous output mode, continuous P&O data will begin to flow to the host, and to your program via the WM_PI_RAWDATA_READY message. The first push of the stylus button will stop the flow of data. See Collect Motion Data for details about continuous data collection.


Class Overview

Polhemus Tracker SDK v2.1.3

PDI Class Overview

Name | Description
CPDIbiterr | A class used for describing Built-In-Test ( BIT ) results.
CPDIdev | The control interface between your program and the tracker.
CPDIfilter | A class used to configure alignment and position filters in the device.
CPDImdat | A class used for describing the programmable output data contained in motion frames received from the tracker.
CPDIser | A class used to configure serial port communication with the device.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.


CPDIbiterr

Polhemus Tracker SDK v2.1.3

Class CPDIbiterr

The CPDIbiterr class is used for describing tracker system BIT errors.

At runtime, the tracker reports the presence of BIT errors in the error field of motion data frames. The full extent of tracker BIT errors is retrieved from the tracker by a call to the CPDIdev::GetBITErrs() method. Use this class to interpret reported BIT errors.

To avoid continued reporting of BIT errors at runtime, the CPDIdev::ClearBITErrs() method may be used.

CPDIbiterr Member Functions

Header

Declared in CPDIbiterr.h; #include PDI.h.

Sample Code

PDImfc

See Also

CPDIdev::ClearBITErrs, CPDIdev::GetBITErrs, Programming with the PDI

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.


CPDIbiterr Functions

Name | Declaration | Description
CPDIbiterr::CPDIbiterr | CPDIbiterr( VOID ); | Constructor
CPDIbiterr::Parse | VOID Parse ( LPSTR szBuf, DWORD dwSize ); | Places text description of BIT error in caller-supplied szBuf string buffer of size dwSize. See Notes below.
CPDImdat::IsClear | BOOL IsClear ( VOID ); | Returns TRUE if no BIT errors exist.

Notes

If no BIT errors are detected, the Parse function will return "No Errors."

If BIT errors have been detected, the Parse function will return the following:

  1. The top-level BIT error bitmap(s). If tracker problems exist, report this value to your customer service representative.

  2. If tracker system hardware component errors exist, the results of failed BIT tests will be reported for each hardware component that reported them.

  3. If sensor BIT errors exist, these will be reported also. If sensor BIT errors are detected, try to eliminate the problem by changing the problem sensor.

If possible, write down reported BIT errors to aid your customer service representative in finding a solution to your problem.

See Also

CPDIbiterr Overview, CPDIdev::GetBITErrs, CPDIdev::ClearBITErrs

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.


CPDIdev

Polhemus Tracker SDK v2.1.3

Class CPDIdev

The CPDIdev class provides the control interface for managing a Polhemus tracker device.

An instantiation of CPDIdev represents a single connection to a single tracker.

CPDIdev Functions by Category

Header

Declared in CPDIdev.h; #include PDI.h.

Sample Code

PDImfc

See Also

Programming with the PDI


Functions By Category

Polhemus Tracker SDK v2.1.3

CPDIdev Functions By Category

Construction

CPDIdev

Constructs a CPDIdev object.

Connection

CnxReady

Returns TRUE if Connection established

CnxType

Returns current connection type.

ConnectSer

Attempts to connect via current serial port parameters

ConnectUSB

Attempts to connect via USB device

Disconnect

Ends current connection

DiscoverCnx

Search for USB, then Serial Connection to device

GetSerialIF

Gets current CPDIser serial port parameters from tracker if connection established. Otherwise gets local port parameters.

SetSerialIF

Sets current CPDIser serial port parameters. Configures device only connection established.

Device-Level Configuration

GetAttFilter / SetAttFilter

Get/Set CPDIfilter attitude filter ( 'Y' Command )

GetBinary / SetBinary

Get/Set binary output ( 'F' Command )

GetCompState / SetCompState

Get/Set map compensation state ( 'D' command )

GetFrameRate / SetFrameRate

Get/Set output data frame rate ( 'R' Command )

GetMetric / SetMetric

Get/Sets metric output ( 'U' Command )

GetPosFilter / SetPosFilter

Get/Set CPDIfilter position filter ( 'X' Command )

GetSourceFrame / SetSourceFrame

Get/Set source frame rotation ( 'G' Command )

GetStationMap / SetStationMap

Get/Set active station map ( '^U' Command )

GetSyncEnabled / SetSyncEnabled

Get/Set external sync enabled ( 'Z' Command )

GetEcho / SetEcho

Get/Set echo mode ( '^E' Command )

Sensor-Level Configuration

ClearSBoresight

Clear sensor boresight ( '^B' Command )

EnableSensor

Enable or disable sensor ( '^U' Command )

GetSDataList / SetSDataList

Get/Set CPDImdat sensor motion data output list ( 'O' Command )

GetSAlignment / SetSAlignment

Get/Set sensor alignment reference frame ( 'A' Command )

GetSBoresight / SetSBoresight

Get/Set sensor boresight ( 'B' Command )

GetSHemisphere / SetSHemisphere

Get/Set sensor hemisphere of operation ( 'H' Command )

GetSHemiTrack / SetSHemiTrack

Get/Set sensor hemisphere tracking enabled ( 'H' Command )

GetSStylusMode / SetSStylusMode

Get/Set sensor stylus mode ( 'L' Command )

ResetSAlignment

Reset sensor alignment ( '^R' Command )

Tracker Configuration Management

GetCfgLabel / SetCfgLabel

Get/Set label to current configuration ( '^X' Command )

GetSavedLabels

Gets currently saved configuration labels ( '^X' Command )

GetStartupSlot / SetStartupSlot

Gets current startup configuration slot number ( '^W' Command )

SaveCfgToSlot

Saves current configuration to slot ( '^K' Command )

Tracker Map Management

GetCompState / SetCompState

Get/Set map compensation state ( 'D' command )

GetSavedMaps

Gets currently saved compensation maps ( '^D' Command )

P & O Collection

ReadSinglePno

Reads single P&O frame. ('P' command): posts data msg to HWND

ResetFrameCount

Reset motion frame count ( 'Q' Command )

ResetTimeStamp

Reset motion frame timestamp ( 'T' Command )

StartContPno

Start continuous P&O collection: posts data msg to HWND

StopContPno

Stop continuous P&O collection

StartStylusPno

Start host P&O collection for Stylus Point Mode operation; posts data msgs to HWND.

StopStylusPno

Stop host P&O collection for Stylus Point Mode operation.

P & O Buffer Management

ClearPnoBuffer

Clears client-supplied P&O output buffer pointer.

LastHostFrameCount

Returns Host Frame Count of last P&O frame collected.

LastPnoPtr

Returns position and size of P&O frame collected

ResetHostFrameCount

Resets Host Frame Count to zero.

ResetPnoPtr

Resets next P&O output pointer to beginning of buffer.

SetPnoBuffer

Sets client-supplied P&O output buffer pointer

Other Runtime Methods

MaxSensors

Retrieves maximum number of sensors supported by the tracker.

RestartTracker

Restarts Tracker, posts restart msg to HWND ( '^Y' Command )

TrackerType

Retrieves type of tracker.

TxtCmd

Sends generic text command to device

WhoAmI

Issues tracker WhoAmI command ('^V' command )

WhoAmISensor

Issues sensor/source WhoAmI command ( '^V' command )

Troubleshooting

GetLastResult

Returns numeric result of last operation

GetLastResultStr

Returns string result of last operation

ResultStr

Returns string definition of ePiErrCode enum result code

Pipe Export

StartPipeExport

Start raw P&O export on named pipe.

CancelPipeExport

Cancel raw P&O export on named pipe.

The tracker may be set for ASCII or Binary output. When in Binary output mode, the tracker will respond to commands in binary, or computer-readable streams of data. The PDI requires binary output to communicate with the tracker, and automatically configures the tracker for binary output each time a connection is established.

Sensitivity, Boundary, and Transition control parameters for the adaptive filter that operates on the attitude (az, el, roll) outputs of the tracker.

A bitmap that represents enabled stations in a tracker. Least significant bit (LSB) represents station one. A bit value of 1 indicates that station is enabled; 0 indicates disabled.

Active signal on the tracker's external event input. Tracker may be configured to place an external sync marker in P&O output when signal detected, or to ignore external sync signals.

Orientation angles (Az, El, Roll) to which the tracker references all of a sensors orientation output. All orientation outputs are relative to a sensor's boresight angles. The default boresight reference angles are (0, 0, 0).

A set of three (X,Y,Z) position values that define 1) a new origin point where the (X,Y,Z) position measurements would equal (0,0,0) if the sensor were placed there, 2) the coordinates of the point defining the positive direction of the X-axis of the reference frame, and 3) the coordinates of the point defining the positive direction of the Y-axis. All P&O output data is referred to a sensor's current Alignment Reference Frame. The default sensor alignment reference frame is also the default Source Reference Frame, [(0,0,0),(200,0,0),(0,200,0)].

Because of the symmetry of the magnetic fields generated by the source, there are two mathematical solutions to each set of sensor data processed. Therefore, only half of the total spatial sphere surrounding the source is practically used at any one time without experiencing an ambiguity (usually sign flips) in the X, Y, Z measurements. This half sphere is referred to as the current hemisphere. The chosen hemisphere is defined by an LOS (line of sight) vector from the source through a point at the zenith of the hemisphere, and is specified by the LOS direction cosines.

Current Tracker configuration settings may be named and saved to the tracker for later retrieval on startup. Configuration labels are names given to configurations that have been saved to the tracker.

A positive integer value reported by the tracker indicating the relative frame number since the last frame initialization (zero). Rollover occurs after 2^32 frames. The frame count is initialized automatically on tracker power up or restart. The frame counting feature is always enabled in the tracker; it is only output when specified in the output motion data list.

A positive integer value reported by the tracker indicating the number of milliseconds since the last timestamp initialization or reset. Rollover occurs after 2^32 milliseconds. Timestamp is initialized automatically on tracker power up or restart. The time stamping feature is always enabled in the tracker; timestamp is only output when specified in the output motion data list.

The pushing of the stylus switch has no change on tracker output other than setting an event marker in the output record when the button is pressed. This marker is only output when specified in the output motion data list.

Rate at which tracker outputs P&O frames.

In echo mode, the tracker responds to configuration-modifying commands by "echoing" back the command that was received. This allows feedback to the ASCII user when modifying configuration settings. This may be most useful to a user that is operating the tracker directly through the RS-232 interface, and less useful when using the PDI.

A host-side 32-bit frame counter incremented each time a complete P&O frame is received from the tracker. The Host Frame Count is automatically reset when Continuous Output Mode is started.


CPDIdev::CancelPipeExport

BOOL CancelPipeExport( VOID );

Description

Cancels raw P&O export on named pipe.

Return Value

TRUE if successful.

Notes

Use CancelPipeExport to end export of real-time raw P&O data to named pipe. CancelPipeExport may be used during continuous P&O data collection.

See Also

CPDIdev::StartPipeExport


CPDIdev::ClearBITErrs

BOOL ClearBITErrs ( VOID );

Description

Clears BIT errors from tracker.

Return Values

TRUE if function succeeded.

Notes

The tracker runs Built-In Tests (BIT) each time it is powered up or restarted. Also, at runtime, certain sensor-related BIT tests are run whenever sensors are plugged in or removed. Thus, BIT errors may be generated at these times. If BIT errors have been detected, they will be reported in the error field of runtime motion frames, or via a call to GetBITErrs.

See Also

CPDIdev Overview, CPDIdev::GetBITErrs, CPDIbiterr Overview


CPDIdev::ClearPnoBuffer

BOOL ClearPnoBuffer ( VOID );

Description

Clear client-supplied motion output buffer pointer.

Return Value

TRUE if successful.

Notes

Use ClearPnoBuffer to set the output P&O buffer pointer to zero. When the output P&O buffer pointer is cleared, raw P&O data will be reported via the WM_PI_RAWDATA_READY message, but will not be deposited in an external client-managed buffer. The data will be available in an internal buffer maintained by CPDIdev, but will be overwritten as new data frames are received.

See Also

CPDIdev Overview, CPDIdev::LastPnoPtr,
 CPDIdev::ResetPnoPtr,
 CPDIdev::SetPnoBuffer,
 Collect Motion Data


CPDIdev::ClearSBoresight

BOOL ClearSBoresight ( INT nSensor );

Description

Clear sensor(s) boresight reference angles. IE, UN-boresight sensor(s).

Parameters

nSensor

[in]

1-based sensor number

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be affected.

ClearSBoresight is equivalent to sending the ASCII '^B' command to the tracker.

See Also

CPDIdev Overview, CPDIdev::GetSBoresight, CPDIdev::SetSBoresight, Configure the Tracker

Orientation angles (Az, El, Roll) to which the tracker references all of a sensors orientation output. All orientation outputs are relative to a sensor's boresight angles. The default boresight reference angles are (0, 0, 0).


CPDIdev::CnxReady

BOOL CnxReady ( VOID ); // Returns TRUE if Connection established

Description

Check for active tracker connection.

Return Value

TRUE if connection exists.

Notes

Use CnxReady to determine if an active connection to the tracker exists.

See Also

CPDIdev Overview, CPDIdev::CnxType,
 CPDIdev::ConnectSer,
 CPDIdev::ConnectUSB,
 CPDIdev::Disconnect,
 CPDIdev::DiscoverCnx,
 Connecting to the Tracker


CPDIdev::CnxType

ePiCommType CnxType ( VOID );

Description

Get type of current tracker connection.

Return Value

ePiCommType enum values:

  • PI_CNX_NONE No connection is established.
  • PI_CNX_UNKNOWN Connection is in an unknown state. This may indicate that the CPDIdev is un-initialized. If this is returned, the best course of action is to get the object to a known state by either disconnecting via a call to Disconnect, or by re-instantiating the CPDIdev object.
  • PI_CNX_USB USB connection is established.
  • PI_CNX_SERIAL Serial connection is established. Parameters of this connection may be retrieved by a call to GetSerialIF.

Notes

Use CnxReady to determine if an active connection to the tracker exists.

See Also

CPDIdev Overview, CPDIdev::CnxReady,
 CPDIdev::ConnectSer,
 CPDIdev::ConnectUSB,
 CPDIdev::Disconnect,
 CPDIdev::DiscoverCnx,
 CPDIdev::GetSerialIF,
 Connecting to the Tracker


CPDIdev::ConnectSer

BOOL ConnectSer ( VOID );

Description

Connect to tracker via serial port.

Return Value

TRUE if serial connection established successfully.

Notes

Use ConnectSer to establish a serial port connection using serial interface parameters set by a previous call to SetSerialIF.

When a successful connection is established, the serial port is opened without error and the tracker responds to a series of commands without error. See Connecting to the Tracker for details.

See Also

CPDIdev Overview, CPDIdev::CnxReady,
 CPDIdev::CnxType,
 CPDIdev::ConnectSer,
 CPDIdev::ConnectUSB,
 CPDIdev::Disconnect,
 CPDIdev::DiscoverCnx,
 CPDIdev::GetSerialIF,
 CPDIdev::SetSerialIF,
 Connecting to the Tracker


CPDIdev::ConnectUSB

BOOL Connect USB ( VOID );

Description

Connect to tracker via USB device.

Return Value

TRUE if USB connection established successfully.

Notes

Use ConnectUSB to establish a USB connection directly.

When a successful connection is established, the USB device is opened without error and the tracker responds to a series of commands without error. See Connecting to the Tracker for details.

See Also

CPDIdev Overview, CPDIdev::CnxReady,
 CPDIdev::CnxType,
 CPDIdev::Disconnect,
 CPDIdev::DiscoverCnx,
 CPDIdev::ConnectSer,
 Connecting to the Tracker


CPDIdev::CPDIdev

CPDIdev( VOID );

Description

Constructs a CPDIdev object.

See Also

CPDIdev Overview, CPDIdev Functions by Category, Create A Tracker Object,


CPDIdev::Disconnect

BOOL Disconnect ( VOID );

Description

End current connection.

Return Value

TRUE if connection ended without error.

Disconnect may fail if CPDIdev is already in the process of disconnecting or connecting, or if CPDIdev is unable to end all running threads. To determine the reason for a failure, call GetLastResult.

Notes

Use Disconnect to end an active connection. If no connection exists, Disconnect will succeed.

See Also

CPDIdev Overview,
 CPDIdev::CnxReady, CPDIdev::CnxType,
 CPDIdev::ConnectSer,
 CPDIdev::ConnectUSB,
 CPDIdev::DiscoverCnx,
 Connecting to the Tracker,


CPDIdev::DiscoverCnx

ePiCommType DiscoverCnx ( VOID );

Description

Search for connection to device.

Return Value

ePiCommType enum values:

  • PI_CNX_NONE No connection is established.
  • PI_CNX_UNKNOWN Connection is in an unknown state.
  • PI_CNX_USB USB connection is established.
  • PI_CNX_SERIAL Serial connection is established. Parameters of this connection may be retrieved by a call to GetSerialIF.

If PI_CNX_NONE or PI_CNX_UNKNOWN is returned, determine the reason for failure by calling GetLastResult.

Notes

DiscoverCnx searches for a single tracker connection first via USB, then on serial ports COM1 thru COM4. Serial connections are attempted on each port using only default CPDIser baud rate and parity values.

If multiple trackers are connected to the host computer, successive calls to DiscoverCnx will find tracker connections in the following order:

  1. All USB connections to Liberty trackers, then

  2. All USB connections to Patriot trackers, and finally
  3. All serial port connections to COM1 thru COM4.

Note that to discover all connected trackers, successive calls to DiscoverCnx must be made on separate instantiations of CPDIdev. If DiscoverCnx is called successively for the same CPDIdev object, any current connection will be destroyed before the next connection is discovered, as a CPDIdev object can only represent one tracker connection at a time. See the PDImulti sample project for a demonstration of managing multiple trackers from a single application.

See Also

CPDIdev Overview, CPDIdev::CnxReady, CPDIdev::CnxType, CPDIdev::ConnectSer, CPDIdev::ConnectUSB, CPDIdev::Disconnect, GetSerialIF, Connecting to the Tracker


CPDIdev::EnableSensor

BOOL EnableSensor ( INT nSensor, BOOL bEnable );

Description

Enable or disable sensor(s) on tracker.

Parameters

nSensor

[in]

1-based sensor number

bEnable

[in]

TRUE if sensor is to be enabled, FALSE if sensor is to be disabled.

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be enabled or disabled.

EnableSensor is equivalent to sending the ASCII '^U' command to the tracker.

See Also

CPDIdev Overview, CPDIdev::GetStationMap, CPDIdev::SetStationMap, Configure the Tracker


CPDIdev::GetAttFilter

BOOL GetAttFilter ( CPDIfilter & cFilter );

Description

Retrieve current attitude filter from tracker.

Parameters

cFilter

[out]

Reference to a CPDIfilter object that will receive the attitude filter setting returned by the tracker.

Return Values

TRUE if function successfully retrieved the Attitude Filter from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetAttFilter is equivalent to sending the ASCII 'Y' command to the tracker.

If function fails, content of cFilter parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetAttFilter, CPDIfilter Overview, Configure the Tracker

Sensitivity, Boundary, and Transition control parameters for the adaptive filter that operates on the attitude (az, el, roll) outputs of the tracker.


CPDIdev::GetBinary

BOOL GetBinary ( BOOL & bBinary );

Description

Retrieve current binary output setting from tracker.

Parameters

bBinary

[out]

Reference to a BOOL that will receive the tracker's current binary output setting

Return Values

TRUE if function successfully retrieved binary output setting from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetBinary is equivalent to sending the ASCII 'F' command to the tracker.

If function fails, content of bBinary parameter is indeterminate.

For successful operation with the PDI, the tracker must use the binary output setting. This setting may be changed by calling SetBinary(FALSE), but all subsequent commands to the tracker EXCEPT SetBinary, GetBinary, and TxtCmd will fail.

See Also

CPDIdev Overview, CPDIdev::SetBinary, Configure the Tracker

The tracker may be set for ASCII or Binary output. When in Binary output mode, the tracker will respond to commands in binary, or computer-readable streams of data. The PDI requires binary output to communicate with the tracker, and automatically configures the tracker for binary output each time a connection is established.


CPDIdev::GetBITErrs

BOOL GetBITErrs ( CPDIbiterr & cBIT );

Description

Retrieves current BIT results from tracker.

Parameters

cBIT

[out]

Reference to CPDIbiterr to be set.

Return Values

TRUE if function succeeded.

Notes

Use GetBITErrors to retrieve current detailed BIT test results from tracker. BIT results are generated each time tracker is powered up or restarted. Certain Sensor-related BIT results are generated whenever sensors are plugged in or removed. If BIT errors exist, runtime motion data frames will contain BIT-related errors. See Runtime Errors. Call ClearBITErrs to clear current results.

See Also

CPDIdev Overview, CPDIdev::ClearBITErrs, CPDIbiterr Overview, ePiDevError

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.


CPDIdev::GetCfgLabel

BOOL GetCfgLabel ( LPCSTR & szLabel );

Description

Retrieve string label of current configuration from tracker.

Parameters

szLabel

[out]

Reference to LPCSTR that will receive a pointer to the label returned by the tracker.

Return Values

TRUE if function successfully retrieved the current configuration label from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetCfgLabel is equivalent to sending the ASCII '^X' command to the tracker.

If function fails, content of szLabel parameter is indeterminate.

See Also

CPDIdev Overview,
 CPDIdev::GetSavedLabels,
 CPDIdev::GetStartupSlot,
 CPDIdev::SaveCfgToSlot,
 CPDIdev::SetCfgLabel,
 CPDIdev::SetStartupSlot,
 Using the Tracker Data store


CPDIdev::GetCompState

BOOL GetCompState( INT & nMap );

Description

Reads current compensation state of tracker.

Parameters

nMap

[out]

1-based map index; if 0, compensation is disabled.

Return Value

TRUE if function successfully retrieved the current compensation state from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetCompState is used to query the state of map compensation in the tracker. It is equivalent to sending the ASCII 'D' command to the tracker.

If compensation is disabled, nMap equals 0.

If compensation is enables, nMap reflects the 1-based index of a map saved in the tracker. Use GetSavedMaps to obtain a count and a list of saved map labels.

See Also

CPDIdev::GetSavedMaps, CPDIdev::SetCompState


CPDIdev::GetEcho

BOOL GetEcho ( BOOL & bEcho );

Description

Retrieve Echo Mode setting from tracker.

Parameters

bEcho

[out]

Reference to BOOL that will receive the tracker's echo mode setting.

TRUE indicates that tracker is currently in echo mode.

FALSE indicates that the tracker is not in echo mode.

Return Values

TRUE if function successfully retrieved the echo mode setting from tracker.

If function failed, call GetLastResult to get more information.

Notes

GetEcho is equivalent to sending the ASCII '^E' command to the tracker.

If function fails, content of bEcho parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetEcho, Configure the Tracker

In echo mode, the tracker responds to configuration-modifying commands by "echoing" back the command that was received. This allows feedback to the ASCII user when modifying configuration settings. This may be most useful to a user that is operating the tracker directly through the RS-232 interface, and less useful when using the PDI.


CPDIdev::GetFrameRate

BOOL GetFrameRate ( ePiFrameRate & eRate );

Description

Retrieve current P&O output frame rate setting from tracker.

Parameters

eRate

[out]

Reference to ePiFrameRate enum that will receive the frame rate retrieved from the tracker.

Return Values

TRUE if function successfully retrieved the current frame rate setting from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetFrameRate is equivalent to sending the ASCII 'R' command to the tracker.

If function fails, content of eRate parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetFrameRate, Configure the Tracker

Rate at which tracker outputs P&O frames.


CPDIdev::GetLastResult

ePiErrCode GetLastResult ( VOID );

Description

Get numeric result of last operation.

Return Values

ePiErrCode result of the last operation performed by the CPDIdev object.

Notes

Use GetLastResult to retrieve a numeric result for the last CPDIdev operation.

Use GetLastResultStr to retrieve a string description of the result.

See Also

CPDIdev Overview, CPDIdev::GetLastResultStr, CPDIdev::ResultStr


CPDIdev::GetLastResultStr

LPCTSTR GetLastResultStr ( VOID );

Description

Get string result of last operation.

Return Values

Pointer to string representation of result of the last operation performed by the CPDIdev object.

Notes

Use GetLastResultStr to retrieve a string description of the result.

Use GetLastResult to retrieve a numeric result for the last CPDIdev operation.

See Also

CPDIdev Overview, CPDIdev::GetLastResult, CPDIdev::ResultStr


CPDIdev::GetMetric

BOOL GetMetric ( BOOL & bMetric );

Description

Retrieve output distance units setting from tracker.

Parameters

bMetric

[out]

Reference to BOOL that will receive the tracker's current metric output units setting.

TRUE indicates that the current output distance units are centimeters.

FALSE indicates inches.

Return Values

TRUE if function successfully retrieved metric output units setting from tracker.

If function failed, call GetLastResult to get more information.

Notes

GetMetric is equivalent to sending the ASCII 'U' command to the tracker.

If function fails, content of bMetric parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetMetric, Configure the Tracker

The tracker may be set for Metric or English output distance units. Metric distance values are output in centimeters. English distance values are output in inches.


CPDIdev::GetPosFilter

BOOL GetPosFilter ( CPDIfilter & cFilter );

Description

Retrieve current position filter setting from tracker.

Parameters

cFilter

[out]

Reference to a CPDIfilter object that will receive the position filter setting returned by the tracker.

Return Values

TRUE if function successfully retrieved the Position Filter from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetPosFilter is equivalent to sending the ASCII 'X' command to the tracker.

If function fails, content of cFilter parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetPosFilter, CPDIfilter Overview, Configure the Tracker


CPDIdev::GetSAlignment

BOOL GetSAlignment ( INT nSensor, PDI3vec & O, PDI3vec & X, PDI3vec & Y );

Description

Retrieve sensor alignment reference frame from tracker.

Parameters

nSensor

[in]

1-based sensor number

O

[out]

Reference to PDI3vec struct that will receive the origin of the sensor's reference frame.

X

[out]

Reference to PDI3vec struct that will receive the X-axis positive direction of the sensor's reference frame

Y

[out]

Reference to PDI3vec struct that will receive the Y-axis positive direction of the sensor's reference frame

Return Values

TRUE if function successfully retrieved the sensor alignment reference frame from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSAlignment is equivalent to sending the ASCII 'A' command to the tracker.

If function fails, contents of output parameters are indeterminate.

See Also

CPDIdev Overview, CPDIdev::ResetSAlignment, CPDIdev::SetSAlignment, Configure the Tracker

A set of three (X,Y,Z) position values that define 1) a new origin point where the (X,Y,Z) position measurements would equal (0,0,0) if the sensor were placed there, 2) the coordinates of the point defining the positive direction of the X-axis of the reference frame, and 3) the coordinates of the point defining the positive direction of the Y-axis. All P&O output data is referred to a sensor's current Alignment Reference Frame. The default sensor alignment reference frame is also the default Source Reference Frame, [(0,0,0),(200,0,0),(0,200,0)].


CPDIdev::GetSavedLabels

BOOL GetSavedLabels ( PDIlabels & cLabels );

Description

Retrieves currently saved configuration labels from tracker.

Parameters

cLabels

[out]

Reference to PDIlabels struct that will receive the saved labels returned by the tracker.

Return Values

TRUE if function successfully retrieved the currently saved labels from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSavedLabels is equivalent to sending the ASCII '^W' command to the tracker.

If function fails, content of cLabels parameter is indeterminate.

See Also

CPDIdev Overview,
 CPDIdev::GetCfgLabel,
 CPDIdev::GetStartupSlot,
 CPDIdev::SaveCfgToSlot,
 CPDIdev::SetCfgLabel,
 CPDIdev::SetStartupSlot,
 Using the Tracker Data store

Current Tracker configuration settings may be named and saved to the tracker for later retrieval on startup. Configuration labels are names given to configurations that have been saved to the tracker.


CPDIdev::GetSavedMaps

BOOL GetSavedMaps( PDIlabels & cLabels, INT & nCount );

Description

Reads names of compensation maps currently stored in the tracker and the number of stored maps.

Parameters

cLabels [out] Reference to PDIlabels struct that will receive the map labels returned by the tracker.

nCount

[out]

Reference to INT that will receive the number of saved maps returned by the tracker.

Return Value

TRUE if function successfully retrieved the currently stored map labels from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSavedMaps is equivalent to sending the ASCII '^D' command to the tracker.

The PDIlabels structure holds up to 4 label strings. However, the tracker can store only 3 maps.

GetSavedMaps does not reflect the current compensation status of the tracker. It only lists the stored maps. To enable or disable a map, use SetCompState. To query the current compensation status, use GetCompState.

See Also

CPDIdev::GetCompState, CPDIdev::SetCompState


CPDIdev::GetSBoresight

BOOL GetSBoresight ( INT nSensor, PDIori & oriBoresight );

Description

Retrieve current sensor boresight reference angles from tracker.

Parameters

nSensor

[in]

1-based sensor number

oriBoresight

[out]

Reference to PDIori struct that will receive the sensor's boresight reference angles.

Return Values

TRUE if function successfully retrieved the sensor boresight setting from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSBoresight is equivalent to sending the ASCII 'B' command to the tracker.

If function fails, content of oriBoresight parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::ClearSBoresight, CPDIdev::SetSBoresight, Configure the Tracker

Orientation angles (Az, El, Roll) to which the tracker references all of a sensors orientation output. All orientation outputs are relative to a sensor's boresight angles. The default boresight reference angles are (0, 0, 0).


CPDIdev::GetSDataList

BOOL GetSDataList ( INT nSensor, CPDImdat & cMDat );

Description

Retrieves sensor output motion data list from tracker.

Parameters

nSensor

[in]

1-based sensor number

cMDat

[out]

Reference to CPDImdat to be set.

Return Values

TRUE if function successfully retrieved the sensor output data list from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSDataList is equivalent to sending the ASCII 'O' command to the tracker.

If function fails, content of cMDat parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetSDataList, CPDImdat Overview, Collect Motion Data


CPDIdev::GetSerialIF

BOOL GetSerialIF ( CPDIser * pSer );

Description

If tracker connection exists, retrieves current serial port parameters from tracker. If no connection exists, retreives current local serial port parameters and does not retrieve any settings from tracker.

Parameters

pSer

[in]

Pointer to CPDIser object that will receive current serial port configuration parameters

Return Values

TRUE if connection is not established (can be determined by a call to CnxReady).

If a connection is established, the return value is TRUE if function successfully retrieved the serial port parameters from the tracker.

If function failed, call GetLastResult to get more information.

Notes

If connection is established, GetSerialIF is equivalent to sending the ASCII '^O' command to the tracker.

If function fails, content of pSer parameter not changed.

Call GetSerialIF to retrieve the serial port parameters currently configured in the tracker. If the tracker is currently connected by a serial connection, these are also the parameters of the current connection. This function is also useful for discovering the parameters after the fact when connection was previously created by a call to DiscoverCnx.

See Also

CPDIdev Overview,
 CPDIdev::ConnectSer,
 CPDIdev::DiscoverCnx,
 CPDIdev::SetSerialIF,
 Connecting to the Tracker


CPDIdev::GetSHemisphere

BOOL GetSHemisphere ( INT nSensor, PDI3vec & cVec );

Description

Retrieves current sensor Hemisphere of Operation from tracker

Parameters

nSensor

[in]

1-based sensor number

cVec

[out]

Reference to PDI3vec struct that will receive sensor's hemisphere of operation setting.

Return Values

TRUE if function successfully retrieved the sensor hemisphere of operation from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSHemisphere is equivalent to sending the ASCII 'H' command to the tracker.

If function fails, content of cVec parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetSHemisphere, CPDIdev::SetSHemiTrack, Configure the Tracker

Because of the symmetry of the magnetic fields generated by the source, there are two mathematical solutions to each set of sensor data processed. Therefore, only half of the total spatial sphere surrounding the source is practically used at any one time without experiencing an ambiguity (usually sign flips) in the X, Y, Z measurements. This half sphere is referred to as the current hemisphere. The chosen hemisphere is defined by an LOS (line of sight) vector from the source through a point at the zenith of the hemisphere, and is specified by the LOS direction cosines.


CPDIdev::GetSHemiTrack

BOOL GetSHemiTrack ( INT nSensor, BOOL & bEnabled );

Description

Retrieves current sensor Hemisphere Tracking enabled state from tracker

Parameters

nSensor

[in]

1-based sensor number.

bEnabled

[out]

Reference to BOOL that will receive sensor's current hemisphere tracking enabled status.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be configured.

GetSHemiTrack is equivalent to sending the ASCII 'H' command to the tracker.

If function fails, content of bEnabled parameter is indeterminate.

See Also

CPDIdev Overview,
 CPDIdev::GetSHemisphere,
 CPDIdev::SetSHemisphere,
 CPDIdev::SetSHemiTrack,
 Configure the Tracker


CPDIdev::GetSourceFrame

BOOL GetSourceFrame ( PDIori & oriSFR );

Description

Retrieves Source Frame Rotation setting from tracker.

Parameters

oriSFR

[out]

Reference to PDIori struct that will receive source frame rotation data retrieved from tracker.

Return Values

TRUE if function successfully retrieved the source frame rotation from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSourceFrame is equivalent to sending the ASCII 'G' command to the tracker.

If function fails, content of oriSFR parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetSourceFrame, Configure the Tracker


CPDIdev::GetSStylusMode

BOOL GetSStylusMode ( INT nSensor, ePiStylusMode & eMode );

Description

Retrieve current sensor stylus mode setting from tracker.

Parameters

nSensor

[in]

1-based sensor number

eMode

[out]

Reference ePiStylusMode enum that will receive the sensor's stylus mode setting

Return Values

TRUE if function successfully retrieved the setting from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSStylusMode is equivalent to sending the ASCII 'L' command to the tracker.

If function fails, content of eMode parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetSStylusMode, Configure the Tracker

The pushing of the stylus switch has no change on tracker output other than setting an event marker in the output record when the button is pressed. This marker is only output when specified in the output motion data list.


CPDIdev::GetStartupSlot

BOOL GetStartupSlot ( ePiConfigSlot & eSlot );

Description

Retrieve current startup configuration slot number from tracker.

Parameters

eSlot

[out]

Reference to ePiConfigSlot that will receive startup current startup slot ID.

Return Values

TRUE if function successfully retrieved the startup slot number from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetStartupSlot is equivalent to sending the ASCII '^W' command to the tracker.

If function fails, content of eSlot parameter is indeterminate.

See Also

CPDIdev Overview,
  CPDIdev::GetCfgLabel,
  CPDIdev::GetSavedLabels,
 CPDIdev::SaveCfgToSlot,
 CPDIdev::SetCfgLabel,
 CPDIdev::SetStartupSlot,
  Using the Tracker Data store


CPDIdev::GetStationMap

BOOL GetStationMap ( DWORD & dwMap );

Description

Retrieve current active station map from tracker.

Parameters

dwMap

[out]

Reference to DWORD that will receive active station map .

Return Values

TRUE if function successfully retrieved the active station map from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetStationMap is equivalent to sending the ASCII '^U' command to the tracker.

If function fails, content of dwMap parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::EnableSensor, CPDIdev::SetStationMap, Configure the Tracker

A bitmap that represents enabled stations in a tracker. Least significant bit (LSB) represents station one. A bit value of 1 indicates that station is enabled; 0 indicates disabled.

A bitmap that represents enabled stations in a tracker. Least significant bit (LSB) represents station one. A bit value of 1 indicates that station is enabled; 0 indicates disabled.

A bitmap that represents enabled stations in a tracker. Least significant bit (LSB) represents station one. A bit value of 1 indicates that station is enabled; 0 indicates disabled.


CPDIdev::GetSyncEnabled

BOOL GetSyncEnabled ( BOOL & bSync );

Description

Retrieve current external sync enabled setting from tracker.

Parameters

bSync

[out]

Reference to BOOL that will receive the sync enabled setting.

Return Values

TRUE if function successfully retrieved the sync enabled setting from the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetSyncEnabled is equivalent to sending the ASCII 'Z' command to the tracker.

If function fails, content of bSync parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetSyncEnabled, Configure the Tracker

Active signal on the tracker's external event input. Tracker may be configured to place an external sync marker in P&O output when signal detected, or to ignore external sync signals.


CPDIdev::LastPnoPtr

BOOL LastPnoPtr ( PBYTE & pBuf, DWORD & dwSize );

Description

Get last P&O frame collected.

Parameters

pBuf

[out]

Reference to PBYTE that will receive the pointer to the last frame received from the tracker.

dwSize

[out]

Reference to DWORD that will receive the size of the last frame received.

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

If function fails, contents of output parameters are indeterminate.

See Also

CPDIdev Overview, CPDIdev::ClearPnoBuffer,
 CPDIdev::ResetPnoPtr,
 CPDIdev::SetPnoBuffer,
 Collect Motion Data


CPDIdev::LastHostFrameCount

BOOL LastHostFrameCount ( DWORD & dwFrameCount );

Description

Get Host Frame Count of last P&O frame received.

Parameters

dwFrameCount

[out]

Reference to DWORD that will receive the count associated with the last frame received.

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

If function fails, contents of output parameters are indeterminate.

The Host Frame Count is automatically reset to 0 when continuous output mode data collection is started using StartContPno.

See Also

CPDIdev Overview, CPDIdev::ResetHostFrameCount, CPDIdev::StartContPno, Collect Motion Data

A host-side 32-bit frame counter incremented each time a complete P&O frame is received from the tracker. The Host Frame Count is automatically reset when Continuous Output Mode is started.


CPDIdev::MaxSensors

INT MaxSensors ( VOID );

Description

Get number of sensors supported by tracker.

Return Values

Maximum number of sensors supported by the tracker.

Notes

Tracker connection must have been established at one time for tracker type and maximum number of sensors to be known.

If no connection has been made, return value is indeterminate.

See Also

CPDIdev Overview


CPDIdev::ReadSinglePno

BOOL ReadSinglePno ( HWND hWnd );

Description

Request single P&O frame from tracker. Post received P&O frame to HWND asynchronously.

Parameters

hWnd

[in]

HWND handle of window to be notified when frame is received from tracker

Return Values

TRUE if function successfully sent P&O frame request to the tracker.

If function failed, call GetLastResult to get more information.

Notes

ReadSinglePno is equivalent to sending the ASCII 'P' command to the tracker.

The received frame will be passed to the calling HWND via the WM_PI_RAWDATA_READY windows message, or WM_PI_DATA_ERROR if error detected.

See Also

CPDIdev Overview, CPDIdev::ReadSinglePnoBuf, CPDIdev::StartContPno, Collect Motion Data


CPDIdev::ReadSinglePnoBuf

BOOL ReadSinglePnoBuf ( PBYTE & pBuf, DWORD & dwSize );

Description

Request single P&O frame from tracker.

Parameters

pBuf

[out]

Reference to PBYTE that will receive the pointer to the single frame received from the tracker.

dwSize

[out]

Reference to DWORD that will receive the size of the single frame received.

Return Values

TRUE if function successfully received P&O frame the tracker.

If function failed, call GetLastResult to get more information.

Notes

ReadSinglePnoBuf is equivalent to sending the ASCII 'P' command to the tracker.

If function fails, contents of output parameters are indeterminate.

See Also

CPDIdev Overview, CPDIdev::ReadSinglePno, CPDIdev::StartContPno, Collect Motion Data


CPDIdev::ResetFrameCount

BOOL ResetFrameCount ( VOID );

Description

Reset tracker P&O frame count to zero.

Return Values

TRUE if function successfully reset the tracker's frame count.

If function failed, call GetLastResult to get more information.

Notes

ResetFrameCount is equivalent to sending the ASCII 'Q1' command to the tracker.

See Also

CPDIdev Overview, CPDIdev::ResetTimeStamp, Collect Motion Data

A positive integer value reported by the tracker indicating the relative frame number since the last frame initialization (zero). Rollover occurs after 2^32 frames. The frame count is initialized automatically on tracker power up or restart. The frame counting feature is always enabled in the tracker; it is only output when specified in the output motion data list.


CPDIdev::ResetHostFrameCount

BOOL ResetHostFrameCount ( VOID );

Description

Reset P&O Host Frame Count to zero.

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

The next P&O frame received will increment the Host Frame Count to 1. The Host Frame Count is automatically reset to 0 when continuous output mode data collection is started using StartContPno.

See Also

CPDIdev Overview, CPDIdev::LastHostFrameCount, CPDIdev::StartContPno, Collect Motion Data

A host-side 32-bit frame counter incremented each time a complete P&O frame is received from the tracker. The Host Frame Count is automatically reset when Continuous Output Mode is started.


CPDIdev::ResetPnoPtr

BOOL ResetPnoPtr ( VOID );

Description

Reset P&O output pointer to the beginning of the client-supplied buffer.

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

The next P&O frame received will be placed at the beginning of the client-supplied buffer.

Function has no effect if client-supplied buffer has not been set using SetPnoBuffer.

See Also

CPDIdev Overview, CPDIdev::ClearPnoBuffer, CPDIdev::LastPnoPtr, CPDIdev::SetPnoBuffer, Collect Motion Data


CPDIdev::ResetSAlignment

BOOL ResetSAlignment ( INT nSensor );

Description

Resets sensor alignment reference frame to factory default.

Parameters

nSensor

[in]

1-based sensor number.

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be affected.

ResetSAlignment is equivalent to sending the ASCII '^R' command to the tracker.

Sensor alignment reference frames are cumulative. That is, each time SetSAlignment is called for a sensor, the new reference frame for the sensor is the sum of the previous reference frame and the new frame values supplied in the call. To prevent this cumulative effect, call ResetSAlignment prior to calling SetSAlignment.

If function fails, the tracker's actual sensor alignment reference frame is indeterminate.

See Also

CPDIdev Overview, CPDIdev::GetSAlignment, CPDIdev::SetSAlignment, Configure the Tracker

A set of three (X,Y,Z) position values that define 1) a new origin point where the (X,Y,Z) position measurements would equal (0,0,0) if the sensor were placed there, 2) the coordinates of the point defining the positive direction of the X-axis of the reference frame, and 3) the coordinates of the point defining the positive direction of the Y-axis. All P&O output data is referred to a sensor's current Alignment Reference Frame. The default sensor alignment reference frame is also the default Source Reference Frame, [(0,0,0),(200,0,0),(0,200,0)].


CPDIdev::ResetTimeStamp

BOOL ResetTimeStamp ( VOID );

Description

Reset tracker P&O timestamp .

Return Values

TRUE if function successfully reset the tracker's timestamp.

If function failed, call GetLastResult to get more information.

Notes

ResetTimeStamp is equivalent to sending the ASCII 'Q2' command to the tracker.

See Also

CPDIdev Overview, CPDIdev::ResetFrameCount, Collect Motion Data

A positive integer value reported by the tracker indicating the number of milliseconds since the last timestamp initialization or reset. Rollover occurs after 2^32 milliseconds. Timestamp is initialized automatically on tracker power up or restart. The time-stamping feature is always enabled in the tracker; timestamp is only output when specified in the output motion data list.


CPDIdev::RestartTracker

BOOL RestartTracker ( VOID );

Description

Restart tracker and terminate connection.

Return Values

TRUE if function successfully sent restart command to tracker.

If function failed, call GetLastResult to get more information.

If connection termination fails, the return value will still be TRUE. Call GetLastResult to verify that the disconnect was also successful.

Notes

RestartTracker is equivalent to sending the ASCII '^Y' command to the tracker.

After instructing the tracker to restart, the CPDIdev object disconnects the connection to the tracker. It is the responsibility of the caller to re-establish the connection after the tracker has restarted.

If function fails, the state of tracker and the connection is indeterminate.

Example Code

CPDIdev m_pdiDev;

INT nTries=10;

BOOL bConnected = FALSE;

if (m_pdiDev.RestartTracker())

{

::Sleep(5000); // sleep 5 seconds

for (INT i=0; i<nTries; i++) // retry connection for 10 seconds

{

if (m_pdiDev.DiscoverCnx() < 0)

{

::Sleep(1000); // sleep 1 second

}

else

{

// connection re-established

bConnected = TRUE;

break;

}

}

}

else

{

printf("%s\n", m_pdiDev.LastResultStr());

}

See Also

CPDIdev Overview


CPDIdev::ResultStr

LPCTSTR ResultStr ( ePiErrCode eCode, ePiDevError eDevCode );

Description

Convert enumerated result code to const string definition.

Parameters

eCode

[in]

ePiErrCode value to parse.

eDevCode

[in]

ePiDevError value to parse, or zero.

Return Values

Pointer to string representation of eCode parameter. If eCode has a value of PI_DEVICE_ERROR_FLAG, then the returned string will include a definition for the eDevCode parameter.

See Also

CPDIdev Overview, CPDIdev::GetLastResult, CPDIdev::GetLastResultStr


CPDIdev::SaveCfgToSlot

BOOL SaveCfgToSlot ( const ePiConfigSlot & eSlot);

Description

Saves current configuration to tracker data store.

Parameters

eSlot

[in]

ePiConfigSlot data store slot to fill.

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be configured.

SaveCfgToSlot is equivalent to sending the ASCII '^K' command to the tracker.

It is up to the caller to label the current configuration before calling SaveCfgToSlot. While it is not required that the label be unique in the set of saved labels, it is recommended. Read Using the Tracker Data store for a more thorough understanding of these operations.

Any modifications to the current configurations that are made after the configuration has been saved to the data store will not be persisted in the data store automatically. Additional calls to SetCfgLabel and SaveCfgToSlot will be necessary to accomplish this.

If function fails, tracker setting is indeterminate. Call GetSavedLabels to get current data store slot settings..

See Also

CPDIdev Overview,
 CPDIdev::GetCfgLabel,
  CPDIdev::GetSavedLabels,
 CPDIdev::GetStartupSlot,
 CPDIdev::SetCfgLabel,
 CPDIdev::SetStartupSlot,
 Using the Tracker Data store


CPDIdev::SetBinary

BOOL SetBinary ( BOOL bBinary );

Description

Configure binary output setting.

Parameters

bBinary

[in]

BOOL binary output enabled setting.

If TRUE, all tracker output will be streams of binary data. If FALSE, tracker will format all output as ASCII strings.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetBinary is equivalent to sending the ASCII 'F' command to the tracker.

If SetBinary(FALSE) is used to set the its output format to ASCII, the PDI will no longer be able to communicate properly with the tracker. The only functions that will operate properly in that state are SetBinary, GetBinary, and TxtCmd. TxtCmd may be used to send and receive ASCII commands and responses to the tracker.

If function fails, tracker setting is indeterminate. Call GetBinary to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetBinary, CPDIdev::TxtCmd, Configure the Tracker

The tracker may be set for ASCII or Binary output. When in Binary output mode, the tracker will respond to commands in binary, or computer-readable streams of data. The PDI requires binary output to communicate with the tracker, and automatically configures the tracker for binary output each time a connection is established.


CPDIdev::SetAttFilter

BOOL SetAttFilter ( const CPDIfilter & cFilter );

Description

Configure attitude filter setting in tracker.

Parameters

cFilter

[out]

CPDIfilter attitude filter to be set.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetAttFilter is equivalent to sending the ASCII 'Y' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetAttFilter to get current setting.

See Also

CPDIdev Overview, Configure the Tracker, CPDIdev::GetAttFilter

Sensitivity, Boundary, and Transition control parameters for the adaptive filter that operates on the attitude (az, el, roll) outputs of the tracker.


CPDIdev::SetCfgLabel

BOOL SetCfgLabel ( const LPCSTR szLabel );

Description

Assign string label to current configuration.

Parameters

szLabel

[in]

Null-terminated label string. Label must be less than or equal to 16 characters, including null terminator.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetCfgLabel is equivalent to sending the ASCII '^X' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetCfgLabel to get current setting.

See Also

CPDIdev Overview,
 CPDIdev::GetCfgLabel,
 CPDIdev::GetSavedLabels,
 CPDIdev::GetStartupSlot,
 CPDIdev::SaveCfgToSlot,
 CPDIdev::SetStartupSlot,
 Using the Tracker Data store


CPDIdev::SetCompState

BOOL SetCompState( INT nMap );

Description

Sets current compensation state of tracker.

Parameters

nMap

[in]

1-based map index; Use 0 to disable compensation.

Return Value

TRUE if function successfully set the tracker's current compensation state

If function failed, call GetLastResult to get more information.

Notes

SetCompState is used to enable or disable map compensation in the tracker. It is equivalent to sending the ASCII 'D' command to the tracker.

To disable compensation, set nMap equal to 0.

To enable compensation and select a map, set nMap equal to the 1-based index of a map saved in the tracker. Use GetSavedMaps to obtain a count and a list of saved map labels.

See Also

CPDIdev::GetCompState, CPDIdev::GetSavedMaps


CPDIdev::SetEcho

BOOL SetEcho ( BOOL bEcho );

Description

Configure Echo Mode setting in tracker.

Parameters

bEcho

[in]

BOOL echo mode setting to be sent to the tracker.

A TRUE value enables echo mode. FALSE disables echo mode..

Return Values

TRUE if function successfully configured the echo mode setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

GetEcho is equivalent to sending the ASCII '^E' command to the tracker.

If function fails, content of bEcho parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::GetEcho, Configure the Tracker

In echo mode, the tracker responds to configuration-modifying commands by "echoing" back the command that was received. This allows feedback to the ASCII user when modifying configuration settings. This may be most useful to a user that is operating the tracker directly through the RS-232 interface, and less useful when using the PDI.


CPDIdev::SetFrameRate

BOOL SetFrameRate ( const ePiFrameRate eRate );

Description

Configure P&O output frame rate setting in tracker.

Parameters

eRate

[out]

ePiFrameRate to be set.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetFrameRate is equivalent to sending the ASCII 'R' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetFrameRate to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetFrameRate, Configure the Tracker

Rate at which tracker outputs P&O frames.


CPDIdev::SetMetric

BOOL SetMetric ( BOOL bMetric );

Description

Configure output distance units setting in tracker.

Parameters

bMetric

[in]

BOOL metric output units setting to be sent to the tracker. A TRUE value indicates that the output distance units are centimeters. FALSE indicates inches.

Return Values

TRUE if function successfully configured the output distance units setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetMetric is equivalent to sending the ASCII 'U' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetMetric to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetMetric, Configure the Tracker

The tracker may be set for Metric or English output distance units. Metric distance values are output in centimeters. English distance values are output in inches.


CPDIdev::SetPnoBuffer

BOOL SetPnoBuffer ( PBYTE pBuf, DWORD dwSize );

Description

Set client-supplied motion output buffer pointer. P&O data collected from tracker will be placed in this buffer if present.

Parameters

pBuf

[in]

Pointer to buffer.

dwSize

[in]

Size of buffer.

Return Values

TRUE if function is successful.

Notes

Use SetPnoBuffer to specify the output P&O buffer. When the output P&O buffer pointer is set, raw P&O data will be reported via the WM_PI_RAWDATA_READY message, and will be deposited in the client-managed buffer. Each WM_PI_RAWDATA_READY message will provide a pointer to the P&O frame in the buffer. As P&O frames are collected, they will be placed in the buffer in circular fashion; when the end of the buffer is reached, the output will continue at the beginning of the buffer. The location of the last frame received can be retrieved by calling LastPnoPtr, and the location of the next frame to be received can be reset to the top of the buffer by calling ResetPnoPtr. See Collect Motion Data for more details.

See Also

CPDIdev Overview, CPDIdev::ClearPnoBuffer,
 CPDIdev::LastPnoPtr,
 CPDIdev::ResetPnoPtr,
 Collect Motion Data


CPDIdev::SetPosFilter

BOOL SetPosFilter ( const CPDIfilter & cFilter );

Description

Configure position filter setting in tracker.

Parameters

cFilter

[out]

CPDIfilter position filter to be set.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetPosFilter is equivalent to sending the ASCII 'X' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetPosFilter to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetPosFilter, Configure the Tracker


CPDIdev::SetSAlignment

BOOL SetSAlignment ( INT nSensor, const PDI3vec & O, const PDI3vec & X, const PDI3vec & Y );

Description

Configure sensor alignment reference frame setting to tracker.

Parameters

nSensor

[in]

1-based sensor number

O

[in]

Const reference to PDI3vec origin of the reference frame.

X

[in]

Const reference to PDI3vec describing X-axis positive direction of the reference frame

Y

[in]

Const reference to PDI3vec describing Y-axis positive direction of the reference frame

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be configured.

SetSAlignment is equivalent to sending the ASCII 'A' command to the tracker.

Sensor alignment reference frames are cumulative. That is, each time SetSAlignment is called for a sensor, the new reference frame for the sensor is the sum of the previous reference frame and the new frame values supplied in the call. To prevent this cumulative effect, call ResetSAlignment prior to calling SetSAlignment.

If function fails, tracker setting is indeterminate. Call GetSAlignment to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetSAlignment, CPDIdev::ResetSAlignment, Configure the Tracker

A set of three (X,Y,Z) position values that define 1) a new origin point where the (X,Y,Z) position measurements would equal (0,0,0) if the sensor were placed there, 2) the coordinates of the point defining the positive direction of the X-axis of the reference frame, and 3) the coordinates of the point defining the positive direction of the Y-axis. All P&O output data is referred to a sensor's current Alignment Reference Frame. The default sensor alignment reference frame is also the default Source Reference Frame, [(0,0,0),(200,0,0),(0,200,0)].


CPDIdev::SetSBoresight

BOOL SetSBoresight ( INT nSensor, const PDIori &, BOOL bReset );

Description

Configure sensor boresight reference angles setting to tracker and optionally reset sensor origin.

Parameters

nSensor

[in]

1-based sensor number

oriBoresight

[in]

const reference to PDIori boresight reference angles to be set

bReset

[in]

Reset sensor (x,y,z) origin to (0,0,0) with boresight.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be configured.

SetSBoresight is equivalent to sending the ASCII 'B' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetSBoresight to get current setting.

See Also

CPDIdev Overview, CPDIdev::ClearSBoresight, CPDIdev::GetSBoresight, Configure the Tracker

Orientation angles (Az, El, Roll) to which the tracker references all of a sensors orientation output. All orientation outputs are relative to a sensor's boresight angles. The default boresight reference angles are (0, 0, 0).


CPDIdev::SetSDataList

BOOL SetSDataList ( INT nSensor, const CPDImdat & cMDat );

Description

Configure sensor output motion data list setting in tracker.

Parameters

nSensor

[in]

1-based sensor number

cMDat

[out]

Const reference to CPDImdat output data list to be set.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be configured.

SetSDataList is equivalent to sending the ASCII 'O' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetSDataList to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetSDataList, CPDImdat Overview, Collect Motion Data


CPDIdev::SetSerialIF

BOOL SetSerialIF ( CPDIser * );

Description

Set current local serial port parameters.

Sets tracker serial port parameters if tracker is connected, and restarts the connection if serial.

Parameters

pSer

[in]

Pointer to CPDIser serial port configuration parameters to set

Return Values

TRUE if connection is not established (can be determined by a call to CnxReady).

If a connection is established, the return value is TRUE if function successfully set the serial port parameters in the tracker.

If the function fails, it may have failed in the setting of the new parameters to the tracker, or in restarting the connection with the new parameters (serial connection only). Call GetLastResult to get details about the cause of the failure.

Notes

If connection is established, SetSerialIF is equivalent to sending the ASCII '^O' command to the tracker.

If the current connection is a serial port connection: After setting the new parameters in the tracker successfully, the serial port connection will be restarted with the new parameters.

If the current connection is USB: The USB connection will remain unchanged.

See Also

CPDIdev::CnxReady,
 CPDIdev::CnxType,
 CPDIdev::DiscoverCnx,
 CPDIdev::ConnectSer,
 CPDIdev::Disconnect,
 CPDIdev::GetSerialIF,
 Connecting to the Tracker


CPDIdev::SetSHemisphere

BOOL SetSHemisphere ( INT nSensor, const PDI3vec & cVec );

Description

Configure current sensor Hemisphere of Operation setting in tracker

Parameters

nSensor

[in]

1-based sensor number

cVec

[out]

Const reference to PDI3vec hemisphere of operation setting.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be configured.

SetSHemisphere is equivalent to sending the ASCII 'H' command to the tracker.

Setting the sensor's hemisphere of operation disables hemisphere tracking for the sensor, if it was previously enabled.

If cVec parameter has value of (0,0,0), hemisphere tracking is enabled for the sensor(s). This may also be accomplished by calling SetSHemiTrack.

If function fails, tracker setting is indeterminate. Call GetSHemisphere to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetSHemisphere, CPDIdev::SetSHemiTrack, Configure the Tracker

Because of the symmetry of the magnetic fields generated by the source, there are two mathematical solutions to each set of sensor data processed. Therefore, only half of the total spatial sphere surrounding the source is practically used at any one time without experiencing an ambiguity (usually sign flips) in the X, Y, Z measurements. This half sphere is referred to as the current hemisphere. The chosen hemisphere is defined by an LOS (line of sight) vector from the source through a point at the zenith of the hemisphere, and is specified by the LOS direction cosines.


CPDIdev::SetSHemiTrack

BOOL SetSHemiTrack ( INT nSensor );

Description

Enable hemisphere tracking for sensor.

Parameters

nSensor

[in]

1-based sensor number.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be configured.

SetSHemiTrack is equivalent to sending the ASCII 'H0,0,0' command to the tracker.

Any hemisphere setting previously configured using SetSHemisphere is discarded by enabling hemisphere tracking.

If function fails, tracker setting is indeterminate. Call GetHemisphere to get current setting.

See Also

CPDIdev Overview,
 CPDIdev::GetSHemisphere,
 CPDIdev::GetSHemiTrack,
 CPDIdev::SetSHemisphere,
 Configure the Tracker


CPDIdev::SetSourceFrame

BOOL SetSourceFrame ( const PDIori & );

Description

Configure Source Frame Rotation setting in tracker.

Parameters

oriSFR

[out]

Const reference to PDIori struct to be set.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetSourceFrame is equivalent to sending the ASCII 'G' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetSourceFrame to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetSourceFrame, Configure the Tracker


CPDIdev::GetSStylusMode

Polhemus Tracker SDK v2.1.3

CPDIdev::SetSStylusMode

BOOL SetSStylusMode ( INT nSensor, ePiStylusMode eMode );

Description

Configure sensor stylus mode setting in tracker.

Parameters

nSensor

[in]

1-based sensor number

eMode

[in]

ePiStylusMode sensor stylus mode setting

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

If nSensor is -1, all sensors on the tracker will be configured.

SetSStylusMode is equivalent to sending the ascii 'L' command to the tracker.

If function fails, content of eMode parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::SetSStylusMode, CPDIdev::StartStylusPno, Configure the Tracker, Using a Stylus

The pushing of the stylus switch has no change on tracker output other than setting an event marker in the output record when the button is pressed. This marker is only output when specified in the output motion data list.


CPDIdev::SetStartupSlot

BOOL SetStartupSlot ( const ePiConfigSlot & eSlot );

Description

Configure startup configuration slot number in tracker.

Parameters

eSlot

[in]

Const Reference to ePiConfigSlot startup slot ID.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

Call SetStartupSlot to configure the power-up and restart configuration for the tracker. The data store slot selected must have been previously populated by a call to SaveCfgToSlot.

After a slot has been selected to be the startup slot: if a configuration with a different label is subsequently saved to the startup slot, SetStartupSlot must be called again. SetStartupSlot causes the tracker to read the label in the selected slot and retain the label until reboot or restart. If the label in the slot changes, the tracker will not be able to locate the startup configuration at boot time, and will revert to the default factory settings.

GetStartupSlot is equivalent to sending the ASCII '^W' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetStartupSlot to get current setting.

See Also

CPDIdev Overview,
  CPDIdev::GetCfgLabel,
  CPDIdev::GetSavedLabels,
  CPDIdev::GetStartupSlot,
 CPDIdev::SaveCfgToSlot,
 CPDIdev::SetCfgLabel,
  Using the Tracker Data store


CPDIdev::SetStationMap

BOOL SetStationMap ( const DWORD & dwMap );

Description

Configure active station map in tracker.

Parameters

dwMap

[out]

DWORD active station map to be set.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetStationMap is equivalent to sending the ASCII '^U' command to the tracker.

Call SetStationMap to enable & disable all sensors in one command to the tracker.

Alternatively, EnableSensor may be used to enable/disable sensors individually.

If function fails, tracker setting is indeterminate. Call GetStationMap to get current setting.

See Also

CPDIdev Overview, CPDIdev::EnableSensor, CPDIdev::GetStationMap, Configure the Tracker

A bitmap that represents enabled stations in a tracker. Least significant bit (LSB) represents station one. A bit value of 1 indicates that station is enabled; 0 indicates disabled.

A bitmap that represents enabled stations in a tracker. Least significant bit (LSB) represents station one. A bit value of 1 indicates that station is enabled; 0 indicates disabled.


CPDIdev::GetSyncMode

Polhemus Tracker SDK v2.1.3

CPDIdev::SetSyncEnabled

BOOL SetSyncEnabled ( BOOL & bSync );

Description

Configure external sync enabled setting in tracker.

Parameters

bSync

[out]

Const reference to BOOL sync enabled setting.

Return Values

TRUE if function successfully configured the setting in the tracker.

If function failed, call GetLastResult to get more information.

Notes

SetSyncEnabled is equivalent to sending the ASCII 'Z' command to the tracker.

If function fails, tracker setting is indeterminate. Call GetSyncEnabled to get current setting.

See Also

CPDIdev Overview, CPDIdev::GetSyncEnabled, Configure the Tracker

Active signal on the tracker's external event input. Tracker may be configured to place an external sync marker in P&O output when signal detected, or to ignore external sync signals.


CPDIdev::StartContPno

BOOL StartContPno ( HWND hWnd );

Description

Start continuous output mode P&O frame collection from tracker. Post start confirmation and received frames to HWND asynchronously.

Parameters

hWnd

[in]

HWND handle of window to be notified when frames are received from tracker. May be zero.

Return Values

TRUE if function successfully sent continuous P&O frame request to the tracker.

If function failed, call GetLastResult to get more information.

Notes

StartContPno is equivalent to sending the ASCII 'C' command to the tracker.

If asynchronous frame collection has not been previously enabled by a call to StartStylusPno, then StartContPno puts the tracker in continuous output mode, and then begins asynchronous frame collection.

The WM_PI_DATA_STARTED message is passed to the calling HWND asynchronously, indicating that asynchronous frame collection has begun.

Subsequently, received motion frames will be passed to the calling HWND via the WM_PI_RAWDATA_READY windows message, or WM_PI_DATA_ERROR if error detected.

If hWnd is zero, no Windows messages will be generated, and motion data can only be collected by synchronous calls to LastPnoPtr.

See Collect Motion Data for details.

If asynchronous frame collection has been previously enabled by a call to StartStylusPno, then StartContPno puts the tracker in continuous output mode and sets an internal flag indicating that the tracker is in continuous output mode. In this case, the WM_PI_DATA_STARTED message is not posted, as asynchronous frame collection is already active.

StartContPno resets the Host Frame Count to zero.

See Also

CPDIdev Overview,
 CPDIdev::ReadSinglePno,
 CPDIdev::SetPnoBuffer,
 CPDIdev::StartStylusPno,
 CPDIdev::StopContPno,
 Collect Motion Data

A host-side 32-bit frame counter incremented each time a complete P&O frame is received from the tracker. The Host Frame Count is automatically reset when Continuous Output Mode is started.


CPDIdev::StartPipeExport

BOOL StartPipeExport ( LPCTSTR szPipeName=PDI_EXPORT_PIPE_NAME );

Description

Starts raw P&O export on named pipe.

Parameters

szPipeName

[in]

Name of pipe.

Return Value

TRUE if successful.

Notes

Use StartPipeExport to export real-time raw P&O data to named pipe. Use of a named pipe is one possible way to export real-time motion data to another host computer for processing and possible performance improvements.

See Also

CPDIdev::CancelPipeExport


CPDIdev::StartStylusPno

BOOL StartStylusPno ( HWND hWnd );

Description

Start stylus-driven P&O frame collection. Post start confirmation and received frames to HWND asynchronously.

Parameters

hWnd

[in]

HWND handle of window to be notified when frames are received from tracker

Return Values

TRUE if function succeeded.

If function failed, call GetLastResult to get more information.

Notes

StartStylusPno will begin host capture of stylus-driven P&O frame generation.

If the tracker is not already in continuous output mode, this function will begin asynchronous frame collection in the PDI and the WM_PI_DATA_STARTED message will be passed to the calling HWND asynchronously, indicating that asynchronous frame collection has begun.

Subsequently, received motion frames will be passed to the calling HWND via the WM_PI_RAWDATA_READY windows message, or WM_PI_DATA_ERROR if errors are detected. Motion frames will be generated asynchronously by the tracker when a stylus button press is detected.

Note that there must be a stylus connected to the tracker, and the stylus must be configured to PDI_STYMODE_POINT, Stylus "Point/Track Mode." To set the stylus mode, use SetSStylusMode.

If the tracker is already in continuous output mode when StartStylusPno is called, this function sets an internal flag indicating that asynchronous collection is active, independent of the continuous output mode. In this case, the WM_PI_DATA_STARTED message is not posted, as asynchronous frame collection is already active.

When the tracker is in continuous output mode, the stylus button acts as an "on/off" switch to the flow of continuous data.

See Using a Stylus for details.

See Also

CPDIdev Overview,
 CPDIdev::ReadSinglePno,
 CPDIdev::SetPnoBuffer,
 CPDIdev::StartContPno,
 CPDIdev::StopContPno,
 CPDIdev::StopStylusPno,
 CPDIdev::SetSStylusMode,
 Collect Motion Data,
 Using a Stylus.

If the tracker is not in continous output mode, every time the button is pressed, a data record is sent to the host. [Note: The host must be aware of this mode. If the stylus button is pressed, the host must be polling for the data frame in order to capture the output data.] In continuous output mode, pressing the stylus switch serves as a toggle for continuous output (track mode). The first time the button is pressed, continuous output mode is turned off. The next time the button is pressed, continuous output mode is turned back on again and so on.

The configurable function of a stylus button: See " Mouse Mode " and "Point/Track Mode"

The pushing of the stylus switch has no change on tracker output other than setting an event marker in the output record when the button is pressed. This marker is only output when specified in the output motion data list.


CPDIdev::StopContPno

BOOL StopContPno ( VOID );

Description

Stop continuous output mode P&O frame collection. Post stop confirmation to HWND asynchronously.

Return Values

TRUE if function successful.

If function failed, call GetLastResult to get more information.

Notes

StopContPno is equivalent to sending the ASCII 'P' command to the tracker.

If asynchronous frame collection has not been previously enabled by a call to StartStylusPno, then StopContPno takes the tracker out of continuous output mode and ends asynchronous frame collection. The WM_PI_DATA_STOPPED message is passed asynchronously to the HWND that was supplied in the call to StartContPno, indicating that asynchronous frame collection has ended.

If asynchronous frame collection has been previously enabled by a call to StartStylusPno, then StopContPno takes the tracker out of continuous output mode and sets an internal flag indicating that the tracker is not in continuous output mode. In this case, the WM_PI_DATA_STOPPED message is not posted, as asynchronous frame collection will remain enabled until it is cancelled by a call to StopStylusPno.

See Collect Motion Data for details.

See Also

CPDIdev Overview,
 CPDIdev::StartContPno,
 CPDIdev::StartStylusPno,
 CPDIdev::StopStylusPno,
 Collect Motion Data


CPDIdev::StopStylusPno

BOOL StopStylusPno ( VOID );

Description

Stop stylus-driven P&O frame collection. Post stop confirmation to HWND asynchronously.

Return Values

TRUE if function successful.

If function failed, call GetLastResult to get more information.

Notes

StopStylusPno ends host capture of stylus-driven P&O frame generation.

If the tracker is not in continuous output mode, this function ends asynchronous frame collection in the PDI and the WM_PI_DATA_STOPPED message is passed asynchronously to the HWND that was supplied in the call to StartStylusPno, indicating that asynchronous frame collection has ended.

If the tracker is in continuous output mode (as a result of a prior call to StartContPno), then this function sets an internal flag indicating that asynchronous collection is not active independent of the continuous output mode. In this case, the WM_PI_DATA_STOPPED message is not posted, as asynchronous frame collection will remain enabled until the continuous output mode is cancelled by a call to StopContPno.

See Using a Stylus for details.

See Also

CPDIdev Overview, CPDIdev::StartContPno, CPDIdev::StartStylusPno, CPDIdev::StopContPno, Collect Motion Data, Using a Stylus


CPDIdev::TxtCmd

BOOL TxtCmd ( LPCTSTR szCmd, DWORD & dwRspSize, LPCTSTR szRsp=0 );

Description

Send text command to tracker.

Parameters

szCmd

[in]

Null-terminated string command to be sent to tracker.

dwRspSize

[in]

[out]

Reference to DWORD size of response expected from tracker. Can be zero.

Size of response received from tracker will be placed here.

szRsp

[in]

Pointer to buffer to place tracker response. If zero, tracker response will be discarded.

Return Values

TRUE if function successful.

If function failed, call GetLastResult to get more information.

Notes

Call TxtCmd to bypass PDI functions and send ASCII commands directly to the tracker. If tracker output format has been set to ASCII by a call to SetBinary(FALSE), this will be the only way to send commands to the tracker through the PDI.

The syntax of the command sent must be correct. The only processing the PDI does on the szCmd parameter is to test its length. If it is longer than PI_MAX_CMD_BUF_LEN, the function will fail with an error code of PI_API_INVALID_ARGS.

If no response is required, set the dwRspSize and szRsp parameters to zero.

If szRsp and dwRspSize are non-zero, the tracker's response (if any) will be placed in the szRsp buffer and the size of the response will be placed in dwRspSize.

If szRsp is non-zero, dwRspSize should be equal to the size of the szRsp buffer.

The length of szCmd should be no longer than PI_MAX_CMD_BUF_LEN (defined in PDIdefs.h).

See Also

CPDIdev Overview, CPDIdev::SetBinary


CPDIdev::TrackerType

ePiTrackerType TrackerType ( VOID );

Description

Get the tracker type.

Return Values

ePiTrackerType value reflecting type of tracker.

Notes

Tracker connection must have been established at one time for tracker type to be known.

Return value is PI_TRK_UNKNOWN if tracker type is unknown.

See Also

CPDIdev Overview, ePiTrackerType


CPDIdev::WhoAmI

BOOL WhoAmI ( LPCSTR & szWhoAmI );

Description

Retrieves tracker WhoAmI information.

Parameters

szWhoAmI

[in]

Reference to LPCSTR that will receive pointer to ASCII tracker WhoAmI information

Return Values

TRUE if function successfully retrieved WhoAmI information from the tracker.

If function failed, call GetLastResult to get more information.

Notes

WhoAmI is equivalent to sending the ASCII '^V' command to the tracker.

If function fails, content of szWhoAmI parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::WhoAmISensor


CPDIdev::WhoAmISensor

BOOL WhoAmISensor ( INT nSensor, LPCSTR & szWhoAmI );

Description

Retrieves source or sensor WhoAmI information.

Parameters

nSensor

[in]

1-based sensor number, or 0 for source

szWhoAmI

[in]

Reference to LPCSTR that will receive pointer to ASCII source/sensor WhoAmI information

Return Values

TRUE if function successfully retrieved source or sensor WhoAmI information from the tracker.

If function failed, call GetLastResult to get more information.

Notes

WhoAmI is equivalent to sending the ASCII '^V' command to the tracker.

If function fails, content of szWhoAmI parameter is indeterminate.

See Also

CPDIdev Overview, CPDIdev::WhoAmI


CPDImdat

Polhemus Tracker SDK v2.1.3

Class CPDImdat

The CPDImdat class is used for describing the programmable output data contained in motion frames received from the tracker. Use this class to configure the data you want in your motion frames on a sensor by sensor basis. The CPDIdev::SetSDataList() method uses this class to send the ASCII 'O' command to the tracker.

CPDImdat Member Functions

Header

Declared in CPDImdat.h; #include PDI.h.

Sample Code

PDImfc

See Also

Programming with the PDI


CPDImdat Functions

Name | Declaration | Description
CPDImdat::CPDImdat | CPDImdat( VOID ); | Constructor
CPDImdat::Append | VOID Append ( ePDIMotionData eItem ); | Appends ePDIMotionData eItem to end of list
CPDImdat::Empty | VOID Empty ( VOID ) | Empties list
CPDImdat::Insert | VOID Insert ( ePDIMotionData eItem, INT nIndex ); | Inserts ePDIMotionData eItem before item at nIndex
CPDImdat::ItemAt | ePDIMotionData ItemAt ( INT nIndex ); | Returns ePDIMotionData item at nIndex
CPDImdat::Remove | VOID Remove ( INT nIndex ); | Removes item at nIndex
CPDImdat::NumItems | INT NumItems ( VOID ); | Returns number of items in list.

Notes

For all CPDImdat operations: if the specified nIndex parameter value does not exist, no failure occurs.

See Also

CPDImdat Overview, CPDIdev::SetSDataList, CPDIdev::GetSDataList, Collect Motion Data


CPDIfilter

Polhemus Tracker SDK v2.1.3

Class CPDIfilter

The CPDIfilter class is used to configure alignment and position adaptive filters in the tracker.

CPDIfilter describes the sensitivity, boundary, and transition control parameters for the adaptive filter that operates on the attitude and position outputs of the tracker. The caller can adjust these parameters to fine-tune the overall dynamic response of the tracker.

The filter is a single-pole low-pass type with an adaptive pole location (i.e., a floating filter "parameter/variable"). The pole location is constrained within the boundary values m_fLowValue and m_fHighValue but is continuously self-adaptive between these limits as a function of the m_fSensitivity parameter and the sensed (ambient noise plus rotational rate) input conditions. For input "rate" conditions that fall within the adaptive range, the adaptive feature varies the pole location between the m_fLowValue and m_fHighValuelimits so as to maximize the output resolution for static inputs while minimizing the output lag for dynamic inputs. Whenever the input conditions cause the filter to make a transition to a narrower bandwidth (i.e., increased filtering), the transition rate of the pole location is constrained to a maximum allowable rate by the parameter m_fMaxTransRate.

CPDIfilter Functions | CPDIfilter Data Members

Header

Declared in CPDIfilter.h; #include PDI.h.

See Also

CPDIdev::SetAttFilter, CPDIdev::SetPosFilter, Programming with the PDI


CPDIfilter Functions

Polhemus Tracker SDK v2.1.3

CPDIfilter Functions & Operators

Functions

Name | Declaration | Description
CPDIfilter::CPDIfilter | CPDIfilter( FLOAT sens = PDI_FLT_OFF, FLOAT low = PDI_FLT_DEF_LOW, FLOAT high = PDI_FLT_DEF_HIGH, FLOAT maxt = PDI_FLT_DEF_MAXT ); | Default Constructor
CPDIfilter::CPDIfilter | CPDIfilter ( const CPDIfilter & rv ); | Copy Constructor
CPDIfilter::Disable | VOID Disable ( VOID ); | Disables filter
CPDIfilter::Disabled | BOOL Disabled ( VOID ) const; | Tests fSensitivity and returns disabled state

Operators

Name | Declaration | Description
CPDIfilter::operator = | CPDIfilter & operator = ( const CPDIfilter & rv ); | Assignment operator

See Also

CPDIfilter Overview, CPDIfilter Data Members, CPDIdev::SetAttFilter, CPDIdev::SetPosFilter, Configure the Tracker


CPDIfilter Data Members

Name | Declaration | Description
CPDIfilter::m_fSensitivity | FLOAT m_fSensitivity; | The sensitivity of the filter to dynamic input conditions. Specifies the proportion of new input data to recent average data that is to be used in updating the floating filter parameter/variable. Allowable range of values: (0.0, 1.0) exclusive.
CPDIfilter::m_fLowValue | FLOAT m_fLowValue; | The maximum allowable filtering to be applied to the outputs during periods of relatively static input conditions. Setting this value to 1.0 disables the filter. Allowable range of values: (0.0, m_fHighValue) exclusive, or 1.0 to disable filter.
CPDIfilter::m_fHighValue | FLOAT m_fHighValue; | The minimum allowable filtering to be applied to the outputs during periods of highly dynamic input conditions. Allowable range of values: (m_fLowValue, 1.0) exclusive.
CPDIfilter::m_fMaxTransRate | FLOAT m_fMaxTransRate; | The maximum allowable transition rate from minimum filtering (for highly dynamic input conditions) to maximum filtering (for relatively static input conditions). Proportionately limits the decay to the m_fLowValue limit whenever the input conditions effect a transition to a narrower bandwidth. Allowable range of values: (0.0, 1.0) exclusive.

See Also

CPDIfilter Overview, CPDIfilter Functions & Operators, CPDIdev::SetAttFilter, CPDIdev::SetPosFilter, Configure the Tracker


CPDIser

Polhemus Tracker SDK v2.1.3

Class CPDIser

The CPDIser class is used to configure serial port communication with the tracker.

CPDIser Functions

Header

Declared in CPDIser.h; #include PDI.h.

Sample Code

PDImfc

See Also

Connecting to the Tracker


CPDIser Functions

Name | Declaration | Description
CPDIser::CPDIser | CPDIser( ePiBaudRate eRate = PI_BR_115200, ePiParity ePar = PI_PARITY_NONE, INT nPort = 1 ); | Constructor
CPDImdat::GetBaudRate | ePiBaudRate GetBaudRate ( VOID ); | Returns ePiBaudRate baud member value.
CPDImdat::GetParity | ePiParity GetParity ( VOID ); | Returns ePiParity parity member value.
CPDImdat::GetPort | INT GetPort ( VOID ); | Returns port number member value.
CPDImdat::SetBaudRate | VOID SetBaudRate( ePiBaudRate eRate ); | Set ePiBaudRate baud rate member value.
CPDImdat::SetParity | VOID SetParity ( ePiParity ePar ); | Set ePiParity parity member value.
CPDImdat::SetPort | VOID SetPort ( INT nPort ); | Set port number member value.

See Also

CPDIser Overview, CPDIdev::SetSerialF, CPDIdev::ConnectSer, Connecting to the Tracker


ePDIMotionData

Description

An enumeration defining the data items that may be configured for motion data frames.

Item | Description | Binary Output size (BYTES)
PDI_ODATA_SPACE | ASCII space character 0x20 | 1
PDI_MODATA_CRLF | ASCII <cr><lf> 0x0d 0x0a | 2
PDI_MODATA_POS | (x, y, z) Cartesian pos coords | 12 ( 3 FLOATs )
PDI_MODATA_POS_EP | (x, y, z) Cartesian pos coords, extended precision Note: in Binary mode, this item type is redundant. Position coords are always output as 3 FLOATs | 12 ( 3 FLOATs )
PDI_MODATA_ORI | az, el, ro Euler ori angles | 12 ( 3 FLOATs )
PDI_MODATA_ORI_EP | az, el, ro Euler ori angles, extended precision Note: in Binary mode, this item type is redundant. Euler angles are always output as 3 FLOATs | 12 ( 3 FLOATs )
PDI_MODATA_DIRCOS | Direction Cosine Matrix | 36 (3x3 FLOATs)
PDI_MODATA_QTRN | Orientation Quarternion | 16 (4 FLOATS)
PDI_MODATA_TIMESTAMP | Timestamp (32-bit) | 4
PDI_MODATA_FRAMECOUNT | Frame Count (32-bit) | 4
PDI_MODATA_STYLUS | Stylus Flag (32-bit) (1 = Detected) | 4
PDI_MODATA_DISTLEV | Distortion Level (32-bit) ( 0 = None, 1 = Minor, or 2 = Significant ) | 4
PDI_MODATA_EXTSYNC | External Sync (32-bit) (1 = Detected) | 4
PDI_MODATA_CALFRAME | Calibration Frame Marker (32-bit) (1=Cal Frame) | 4

Declaration

typedef enum
{
PDI_ODATA_SPACE = 0
, PDI_MODATA_CRLF
, PDI_MODATA_POS
, PDI_MODATA_POS_EP
, PDI_MODATA_ORI
, PDI_MODATA_ORI_EP
, PDI_MODATA_DIRCOS
, PDI_MODATA_QTRN
, PDI_MODATA_TIMESTAMP
, PDI_MODATA_FRAMECOUNT
, PDI_MODATA_STYLUS
, PDI_MODATA_DISTLEV
, PDI_MODATA_EXTSYNC
, PDI_MODATA_CALFRAME

} ePDIMotionData;

Header

Declared in PDImdat.h; include PDI.h.

The tracker may be set for ASCII or Binary output. When in Binary output mode, the tracker will respond to commands in binary, or computer-readable streams of data. The PDI requires binary output to communicate with the tracker, and automatically configures the tracker for binary output each time a connection is established.

A positive integer value reported by the tracker indicating the number of milliseconds since the last timestamp initialization or reset. Rollover occurs after 2^32 milliseconds. Timestamp is initialized automatically on tracker power up or restart. The time stamping feature is always enabled in the tracker; timestamp is only output when specified in the output motion data list.

A positive integer value reported by the tracker indicating the relative frame number since the last frame initialization (zero). Rollover occurs after 2^32 frames. The frame count is initialized automatically on tracker power up or restart. The frame counting feature is always enabled in the tracker; it is only output when specified in the output motion data list.

Active signal on the tracker's external event input. Tracker may be configured to place an external sync marker in P&O output when signal detected, or to ignore external sync signals.

Level of magnetic distortion in the environment as detected by the tracker. The tracker reports three distortion levels in the output data frame: None, Minor, and Significant.

A 3x3 matrix representing the cosines of the angles between a sensor's x, y, z axes and the X, Y, Z axes of the measurement reference (alignment) frame.

A four-parameter quantity representing a vector and a scalar. The quaternion q = q0 + i q1 + j q2 + k q3 can be used to represent a sensor's orientation without the need for trigonometric functions.


ePiBaudRate

Declaration

typedef enum

{

PI_BR_1200 = 0

, PI_BR_2400

, PI_BR_4800

, PI_BR_9600

, PI_BR_19200

, PI_BR_38400

, PI_BR_57600

, PI_BR_115200

, PI_BR_MAX

} ePiBaudRate;

Header

Declared in PDIdefs.h; include PDI.h.


ePiCommType

Declaration

typedef enum
{
PI_CNX_NONE = -2
, PI_CNX_UNKNOWN = -1
, PI_CNX_USB = 0
, PI_CNX_SERIAL

} ePiCommType;

Header

Declared in PDIdefs.h; include PDI.h.


ePiConfigSlot

Declaration

#define PI_CONFIG_LABEL_LEN 16

typedef enum
{
PICFG_SLOT_DEFAULT=0
, PICFG_SLOT_1
, PICFG_SLOT_2
, PICFG_SLOT_3

, PICFG_MAX_SLOT
, PICFG_NO_SLOT = -1
} ePiConfigSlot;

typedef CHAR PDIlabels[PICFG_MAX_SLOT][PI_CONFIG_LABEL_LEN];

Header

Declared in PDIdefs.h; include PDI.h.


ePiDevError

Description

Enumerated set of error codes that may be produced by the tracker.

Error Code |  | Description
PI_DEVERR_NOERROR |  | No Error
Interface Errors | 0x01+ | Interface errors are errors in response to individual tracker commands.
PI_DEVERR_INVALID_COMMAND |  | Invalid Command
PI_DEVERR_STATION_OUT_OF_RANGE |  | Station Out of Range
PI_DEVERR_INVALID_PARAMETER |  | Invalid Parameter
PI_DEVERR_TOO_FEW_PARAMETERS |  | Too Few Parameters
PI_DEVERR_TOO_MANY_PARAMETERS |  | Too Many Parameters
PI_DEVERR_PARAMETER_BELOW_LIMIT |  | Parameter Below Limit
PI_DEVERR_PARAMETER_ABOVE_LIMIT |  | Parameter Above Limit
PI_DEVERR_SP_COM_FAILURE |  | SP Comm Failure
PI_DEVERR_SP1_INIT_FAILURE |  | SP1 Init Failure
PI_DEVERR_SP2_INIT_FAILURE |  | SP2 Init Failure
PI_DEVERR_SP3_INIT_FAILURE |  | SP3 Init Failure
PI_DEVERR_SP4_INIT_FAILURE |  | SP4 Init Failure
PI_DEVERR_SP_NONE_DETECTED |  | SP Not Detected
PI_DEVERR_SRC_INIT_FAILURE |  | SRC Init Failures
PI_DEVERR_MEM_ALLOC_ERROR |  | Mem Alloc Error
PI_DEVERR_EXCESS_CMD_CHARS |  | Excess Cmd Chars
PI_DEVERR_EXIT_UTH |  | Exit UTH Mode
PI_DEVERR_SOURCE_READ_ERROR |  | SRC Read Error
PI_DEVERR_READONLY_ERROR |  | Read-only command
PI_DEVERR_TEXT_MESSAGE |  | Non-fatal text message
PI_DEVERR_MAP_LOAD |  | Error loading map
PI_DEVERR_SYNC_SENSORS |  | Error synchronizing sensors
PI_DEVERR_FW_UPGRADE_REQ |  | FATAL: Firmware Upgrade Required for USB IOProc Compatability
PI_DEVERR_FW_UPGRADE_REC |  | IOProc Firmware Upgrade Recommended
Runtime Errors | 0x15+ | Runtime errors are reported only with motion data frames.
PI_DEVERR_RT_SRC_FAIL_a_X |  | SRC Fail X (a)
PI_DEVERR_RT_SRC_FAIL_b_Y |  | SRC Fail Y (b)
PI_DEVERR_RT_SRC_FAIL_c_XY |  | SRC Fail XY (c)
PI_DEVERR_RT_SRC_FAIL_d_Z |  | SRC Fail Z (d)
PI_DEVERR_RT_SRC_FAIL_e_XZ |  | SRC Fail XZ (e)
PI_DEVERR_RT_SRC_FAIL_f_YZ |  | SRC Fail YZ (f)
PI_DEVERR_RT_SRC_FAIL_g_XYZ |  | SRC Fail XYZ (g)
PI_DEVERR_RT_OUT_OF_MAP_u |  | Position outside of mapped area (u)
PI_DEVERR_RT_SRC_FAIL_A_X |  | SRC Fail X + BIT Errors (A)
PI_DEVERR_RT_SRC_FAIL_B_Y |  | SRC Fail Y + BIT Errors (B)
PI_DEVERR_RT_SRC_FAIL_C_XY |  | SRC Fail XY + BIT Errors (C)
PI_DEVERR_RT_SRC_FAIL_D_Z |  | SRC Fail Z + BIT Errors (D)
PI_DEVERR_RT_SRC_FAIL_E_XZ |  | SRC Fail XZ + BIT Errors (E)
PI_DEVERR_RT_SRC_FAIL_F_YZ |  | SRC Fail YZ + BIT Errors (F)
PI_DEVERR_RT_SRC_FAIL_G_XYZ |  | SRC Fail XYZ + BIT Errors (G)
PI_DEVERR_RT_BITERR |  | Built-In Test ( BIT ) Error(s) detected (I)

Header

Declared in PDItracker.h; include PDI.h.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.

Tracker Built-In-Test. BIT tests are run each time the tracker is powered up or restarted.


ePiErrCode

Description

Enumerated set of error codes that may be produced by PDI operations.

Error Code |  | Description
PI_NOERROR |  | No Error
System Errors | 0x20010000+ | System errors occurred during host system operations. OS level error codes usually accompany these PDI error.
PI_HOST_SYS_CNX_USB_CREATE_ERROR |  | Host System USB Connection Create Error
PI_HOST_SYS_CNX_SER_CREATE_ERROR |  | Host System Serial Connection Create Error
PI_HOST_SYS_WRITE_ERROR |  | Host System Write Error
PI_HOST_SYS_WAIT_WRITE_ERROR |  | Host System Write Event Wait Error
PI_HOST_SYS_WAIT_READ_ERROR |  | Host System Read Event Wait Error
PI_HOST_SYS_READ_ERROR |  | Host System Read Error
PI_HOST_SYS_CLOSE_ERROR |  | Host System Close Handle Error
PI_HOST_SYS_PIPE_CREATE_ERROR |  | Host System Pipe Create Error
PI_HOST_SYS_PIPE_DISC_ERROR |  | Host System Pipe Disconnect Error
PI_HOST_SYS_PIPE_WRITE_ERROR |  | Host System Pipe Write Error
PI_HOST_SYS_CREATE_THREAD_ERROR |  | Host System Thread Create Error
PI_HOST_SYS_GET_THREAD_STATUS_ERROR |  | Host System Get Thread Status Error
PI_HOST_SYS_TERM_THREAD_ERROR |  | Host System Terminate Thread Error
PI_HOST_SYS_DEVIO_ERROR |  | Host System DeviceIoControl Error
Host Errors | 0x20020000+ | Host errors originate from host PDI software components.
PI_HOST_NOCNX_ERROR |  | Host Connection Error: No Connection Established
PI_HOST_BUILD_CMD_ERROR |  | Host Error building tracker command string
PI_HOST_PARSE_RSP_ERROR |  | Host Error parsing tracker response
PI_HOST_STATE_ERROR |  | Host in invalid state to perform requested operation.
PI_HOST_NO_RESP |  | Read Resp Timed Out
PI_HOST_FRAME_ERROR |  | Comm Frame Error
PI_HOST_ASYNCINPROG_ERROR |  | Too many async operations
PI_HOST_OVERFLOW_ERROR |  | Host Frame Overflow
PI_HOST_FRAME_IGNORED |  | Frame ignored: no async operation
PI_HOST_CONT_CMD_SENT |  | Command sent in Cont mode, no response collected
Device Errors | 0x20040000+ | Device errors originate from the tracker or interaction with the tracker.
PI_DEVICE_NOT_DETECTED |  | Device not detected on serial port
PI_DEVICE_ERROR_FLAG |  | Device reported error. This will accompany an ePiDevError code.
PI_DEVICE_CMD_FAILED |  | Device command failed. Tracker did not perform command properly.
PI_DEVICE_NOT_RECOG |  | Device not recognized. The result of an invalid header value in tracker response. If tracker is in ASCII output mode, PDI will report this error.
PI_DEVICE_NOT_FOUND |  | Device not found on USB or serial ports
API Usage Errors | 0x20080000+ | Errors in PDI usage.
PI_API_INVALID_ARGS |  | Command has invalid argument(s)
PI_API_NO_HWND_PROVIDED |  | No HWND provided for async result

Header

Declared in PDIerror.h; include PDI.h.

The tracker may be set for ASCII or Binary output. When in ASCII output mode, the tracker will respond to commands in ASCII, or human-readable strings of data. The PDI requires binary output to communicate with the tracker, and automatically configures the tracker for binary output each time a connection is established.


ePiFrameRate

Declaration

typedef enum
{
PI_FRATE_120 = 3
, PI_FRATE_240

} ePiFrameRate;

Header

Declared in PDIdefs.h; include PDI.h.


ePiParity

Declaration

typedef enum
{
PI_PARITY_NONE
, PI_PARITY_ODD
, PI_PARITY_EVEN

, PI_PARITY_MAX
} ePiParity;

Header

Declared in PDIdefs.h; include PDI.h.


ePiStylusMode

Description

An enumeration defining the ways that a stylus button may be configured to function.

Stylus Mode

Description

PI_STYMODE_MOUSE

Mouse Mode. The pushing of the stylus button has no change on tracker output other than setting a stylus event marker in the output record when the button is pressed.

PI_STYMODE_POINT

Point/Track Mode. If the tracker is not in continuous output mode, every time the button is pressed, a data record is sent to the host.

[Note: The host must be aware of this mode. If the stylus button is pressed, the host must be polling for the data frame in order to capture the output data.]

If the tracker is continuous output mode, pressing the stylus button serves as a toggle for continuous output (track mode). The first time the button is pressed, continuous output mode is turned off. The next time the button is pressed, continuous output mode is turned back on again and so on.

Declaration

typedef enum

{

PI_STYMODE_MOUSE

, PI_STYMODE_POINT

} ePiStylusMode;

Header

Declared in PDIdefs.h; include PDI.h.


ePiTrackerType

Declaration

typedef enum

{

PI_TRK_LIBERTY

, PI_TRK_PATRIOT

, PI_TRK_UNKNOWN

, PI_TRK_MAX = PI_TRK_UNKNOWN

} ePiTrackerType;

Header

Declared in PDItracker.h; include PDI.h.


PDI3vec

Polhemus Tracker SDK v2.1.3

PDI3vec, PDIori, PDIpos

Description

Typedefs used for containing FLOAT 3-tuples commonly used for position and Euler angle orientation.

Declaration

typedef FLOAT PDI3vec[3];

typedef PDI3vec PDIpos;
typedef PDI3vec PDIori;

Header

Declared in PDIdefs.h; include PDI.h.


PDIlabels

Declaration

#define PI_CONFIG_LABEL_LEN 16

typedef enum
{
PICFG_SLOT_DEFAULT=0
, PICFG_SLOT_1
, PICFG_SLOT_2
, PICFG_SLOT_3

, PICFG_MAX_SLOT
, PICFG_NO_SLOT = -1
} ePiConfigSlot;

#define PDI_DEFAULT_CONFIG_LABEL "Default\0"
#define PDI_VACANT_CONFIG_LABEL "***************\0"

typedef CHAR PDIlabels[PICFG_MAX_SLOT][PI_CONFIG_LABEL_LEN];

Header

Declared in PDIdefs.h; include PDI.h.


WM_PI_DATA_STARTED

The WM_PI_DATA_STARTED message is sent when asynchronous continuous P&O collection begins as a result of calling CPDIdev::StartContPno or CPDIdev::StartStylusPno.

A window receives this message through its WindowProc function.

Callback Declaration:

Win32: LRESULT CALLBACK WindowProc( HWND hWnd, INT uMsg, WPARAM wP, LPARAM lP );

MFC: afx_msg LRESULT OnDataError ( WPARAM wP, LPARAM lP );

Callback Parameters

wP

[in]

Not Used.

lP

[in]

Not Used

Example Code

LRESULT
CPDImfcDlg::OnDataStarted( WPARAM wP, LPARAM lP )
{
TRACE("CPDImfcDlg::OnDataStarted\n");
CString msg;
msg.Format("WM_PI_DATA_STARTED received\r\n");
AddMsg(msg);

m_bCont = TRUE;
m_dwContFrameCount = 0;
m_dwFramesDisplayed = 0;
m_dwOverflowCount = 0;

StartContTimer();

UpdateData(FALSE);

return 0;
}

See Also

CPDIdev Overview, CPDIdev::StartContPno, CPDIdev::StartStylusPno, Collect Motion Data, Using a Stylus


WM_PI_DATA_STOPPED

The WM_PI_DATA_STOPPED message is sent when asynchronous continuous P&O collection ends as a result of calling CPDIdev::StopContPno or CPDIdev::StopStylusPno.

A window receives this message through its WindowProc function.

Callback Declaration:

Win32: LRESULT CALLBACK WindowProc( HWND hWnd, INT uMsg, WPARAM wP, LPARAM lP );

MFC: afx_msg LRESULT OnDataError ( WPARAM wP, LPARAM lP );

Callback Parameters

wP

[in]

Not Used.

lP

[in]

Not Used

Example Code

LRESULT
CPDImfcDlg::OnDataStopped( WPARAM wP, LPARAM lP )
{
TRACE("CPDImfcDlg::OnDataStopped\n");
CString msg;
msg.Format("WM_PI_DATA_STOPPED received, %d frames collected,
%d frames dropped, %d frames displayed\r\n",
m_dwContFrameCount, m_dwOverflowCount, m_dwFramesDisplayed);
AddMsg(msg);

m_bCont = FALSE;
UpdateData(FALSE);

return 0;
}

See Also

CPDIdev Overview, CPDIdev::StopContPno, CPDIdev::StopStylusPno, Collect Motion Data, Using a Stylus


WM_PI_RAWDATA_ERROR

The WM_PI_RAWDATA_ERROR message is sent if an error occurred during P&O data collection. A window receives this message through its WindowProc function.

Callback Declaration:

Win32: LRESULT CALLBACK WindowProc( HWND hWnd, INT uMsg, WPARAM wP, LPARAM lP );

MFC: afx_msg LRESULT OnDataError ( WPARAM wP, LPARAM lP );

Callback Parameters

wP

[in]

ePiErrCode of encountered error.

lP

[in]

ePiDevErrCode if wP is PI_DEVICE_ERROR_FLAG

Notes

If continuous P&O data collection is in progress, data collection will continue until stopped by a call to CPDIdev::StopContPno.

Use CPDIdev::ResultStr to parse the error code returned in wP.

Example Code

LRESULT
CPDImfcDlg::OnRawDataError( WPARAM wP, LPARAM lP )
{
CString msg;
msg.Format("WM_PI_RAWDATA_ERROR received: %s\r\n",
m_pdiDev.ResultStr( (ePiErrCode)lP ));
AddMsg(msg);

if ((IS_PI_SYS_ERROR(lP)) && m_bCont)
{
ToggleCont();
}

if ((ePiErrCode)lP == PI_HOST_OVERFLOW_ERROR)
{
m_dwOverflowCount++;
}

return 0;
}

See Also

CPDIdev Overview, Collect Motion Data


WM_PI_RAWDATA_READY

The WM_PI_RAWDATA_READY message is sent when a motion frame has been collected from the tracker. A window receives this message through its WindowProc function.

Callback Declaration:

Win32: LRESULT CALLBACK WindowProc( HWND hWnd, INT uMsg, WPARAM wP, LPARAM lP );

MFC: afx_msg LRESULT OnDataError ( WPARAM wP, LPARAM lP );

Callback Parameters

wP

[in]

Size in BYTEs of new frame buffer.

lP

[in]

Pointer to new frame buffer.

Notes

If a client-managed output buffer has been supplied to the CPDIdev object via a call to CPDIdev::SetPnoBuffer, then the lP parameter will point to a location within that buffer. In this case, it is not necessary to process the data immediately. The motion frame can be retrieved at a later time by a call to CPDIdev::LastPnoPtr.

If no output buffer has been supplied, then the lP parameter points to a private buffer owned by the CPDIdev object. This pointer cannot be recovered later, and may be overwritten at any time.

Example Code

LRESULT
CPDImfcDlg::OnRawDataReady( WPARAM wP, LPARAM lP )
{

PBYTE pBuf = (PBYTE)lP;

DWORD dwSize = (DWORD)wP;

m_dwContFrameCount++;

ParseFrame( pBuf, dwSize );

if (m_dwContFrameCount > 10)
{
m_pdiDev.StopContPno();
}

return 0;
}

See Also

CPDIdev Overview, Collect Motion Data


WM_PI_RAWDATA_WARNING

The WM_PI_RAWDATA_WARNING message is sent if an non-fatal condition occurred during P&O data collection. A window receives this message through its WindowProc function.

Callback Declaration:

Win32: LRESULT CALLBACK WindowProc( HWND hWnd, INT uMsg, WPARAM wP, LPARAM lP );

MFC: afx_msg LRESULT OnDataWarning ( WPARAM wP, LPARAM lP );

Callback Parameters

wP

[in]

ePiErrCode of encountered error.

lP

[in]

ePiDevErrCode if wP is PI_DEVICE_ERROR_FLAG

Notes

If continuous P&O data collection is in progress, data collection will continue until stopped by a call to CPDIdev::StopContPno.

Use CPDIdev::ResultStr to parse the error code returned in wP.

Warning conditions do not indicate a malfunction of the tracker or host system. For example, the device ePiDevErrorCode PI_DEVERR_RT_OUT_OF_MAP_u indicates the the sensor's position is currently outside of the mapped area (if map compensation is enabled; see CPDIdev::GetCompState). This error code indicates a transient condition, not a malfunction.

Example Code

LRESULT
CPDImfcDlg::OnRawDataWarning( WPARAM wP, LPARAM lP )
{
CString msg;
msg.Format("WM_PI_RAWDATA_WARNING received: %s\r\n",
m_pdiDev.ResultStr( (ePiErrCode)lP ));
AddMsg(msg);

return 0;
}

See Also

CPDIdev Overview, Collect Motion Data