VIPER Command Interface SDK (VPcmdIF) Distribution Notes 251107a 0.0.0.64
Summary of Changes:
00064 – (251107a) Only x64 built DLL and static .lib builds are included in this distribution.
Built using windows platform toolset vc143, distribution folder hierarchy modified to reflect this.
(251029a) DLL optimization build flags /Ob1 normalized across all DLLs
(250925a) Bugfix: access violation may occur when ending USB connection.
Downloads:
1. VPwinDist_251107a.7z – VPcmdIF libraries, source files and samples.
2. VPwinDist_SYMB_251107a.7z. – Symbol files for debugging with VPcmdIF.
3. VpwinDist_src_251107a.7z – Source files and Visual Studio project files.
Description:
USB Disconnect bugfix:
· Fixed occasional timing problem where libusb async transfers may not be fully cancelled before libusb_close() is called. Extend async transfer cancellation wait time to 2 seconds, retry 3x.
Modified distribution folder hierarchy:
VPwinDist_251107a
├───Inc
└───x64
├───Debug
│
└───v143
│ ├───dll
│ ├───lib
│ └───samples
└───Release
└───v143
├───dll
├───lib
└───samples
History:
250618a 00063 Unreleased build.
241028a 00062 Notes here.
Serial connection improvements and bugfixes,
Experimental CPVSeuPnoII class added to VPif.h
Bugfix: E_VPERR _CMDRSP_MISMATCH error reported sometimes even when correct reponse is found in the command response queue.
240513a 00061 Internal build.
231114a 00060 Add vpdev_cmd_generic1() to retrieve all fields of response frame to a generic command. Notes here
230803a 00059 CMD_SELF_LEVEL added. VPcmdConsole sample modified. CVPSeuPno::Report and CSVreport. Notes here
220919a 00058 Bugfix build. Notes here
220117a 00057 Out-Of-Range mode command CMD_OOR_MODE implemented to change behavior when sensor moves out of range. Notes here
211201b 00056 USB close connection more robust. Trace improved: no longer steps on stdout; levels tidied up.
210618a 00055 Improved block pno count read concurrency.
210527a 00054 limited distribution
200511a 00053 CMD_CAL_DISABLE support. Notes here.
201223c 00046 USB performance improvement prevents lost frames at higher frame rates
200519a 00044 3rd Pre-Release distribution
200130a 00037 2nd Pre-Release distribution.
190927a 00031 Initial Pre-Release distribution
License
VPcmdIF and contributing Libraries and Sample Code are distributed as part of our commercial hardware device package.
While the device itself is a proprietary product, the VPcmdIF source code is free for Viper users to use, modify and redistribute WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License https://www.gnu.org/licenses/gpl-3.0.html for more details.
Any redistribution or linked inclusion of this software package must also be Open-Source according to these terms.
Polhemus accepts no responsibility or liability for any use of this code.
Contents of the Extracted InstallDir:
InstallDir\Inc\
All the header files needed to build against this distribution of VPcmdIF. In practice, you will only need to minimally include one file: VPcmdif.h.
InstallDir\Win32\
InstallDir\x64\
Prebuilt Win32 and x64 platform VPcmdIF binaries. Release and Debug configurations:
VPcmdIF :
· The main SDK library.
· Most projects only need to link/run with this, $(Platform)\$(Configuration)\dll\VPcmdIF.lib/.dll
Also available in DLL and .LIB form are:
VPusbIO
· This library wraps libusb-1.0.lib. It is included in VPcmdIF as a static library, but may be used directly in either form.
VPserIO
· This library is included by VPcmdIF as a static library for establishing RS422 connection to Viper.
· It may be used by itself. The VPcmdWinConsole links with this library in addition to the VPcmdIF in order to use some handy methods in the CVPserIO class for enumerating available COM ports. Refer to ListSerialPorts() in the VPcmdWinConsole.cpp
InstallDir\src
Source projects and files for the VPcmdIF windows build, for your reference.
Source projects and files for the sample project is here as well.
Sample Code
At this time there is one sample app: VPcmdWinConsole.
InstallDir\src\VPcmdConsole Source files and Visual Studio 2015 and 2019 project files for VPcmdWinConsole.
InstallDir\{Win32,x64}\{Release,Debug}\samples Pre-built Sample app executables.
Commenting in the VPcmdWinConsole.cpp briefly describes how to use the VPcmdIF and is reproduced here:
General Instructions for using VPcmdIF to discover Viper SEUs, configure, and collect P&O***
***
1. Initialize the VPcmdIF and create a vpcmd_context. The context is the handle by which you will manage your connection to the associated device(s).
· Call vpcmdif_init( vpcmd_context &). The context will be returned in the vpcmd_context & argument.
· Demonstrated in the Connect() function below.
· The vpcmd_context will now be used in almost every call into the VPcmdIF.
2. Using the vpcmd_context, get a device handle (vpdev_hnd) by connecting to a device.
· Call either vpctx_connectusb( vpcmd_context, vpdev_hnd &, pid) or vpctx_connect_ser(vpcmd_context &, vpdev_hnd &).
· Demonstrated in function Connect() below.
· The vpdev_hnd will now be used to specify this device. It is possible to create >1 connection and have >1 device handle.
3. A note about VPcmdIF function naming conventions:
· Examine Inc/VPcmdIF.h to understand the capabilities of the library.
· VPcmdIF API-centric function names begin with vpcmdif_
· Context-centric function names begine with vpctx_
· Device-centric function names begin with vpdev_
· Configuration command function names pertaining to the device begin with vpcmd_dev_
· Configuration command function names pertaining to the sensor begin with vpcmd_sns_
· Sensor-ids in vpcmd_sns_ function arguments may be wildcarded by using -1.
· All sensor- and device-id numbers are zero-based in the VPcmdIF and tracker interface constructs.
4. Trace.
· By default, VPcmdIF trace output is disabled. In this sample app, it is enabled and set to level 3, "VPCMD_TRACE_3_NORMALIO".
· Use the Options menu T selection to try different levels and see more of the I/O between the host and devices.
· To use trace functions in your own code, include VPTrace.h.
5. P&O.
Single Frame:
· Call vpcmd_dev_singlepno().
· Demonstrated in GetSingle() below.
· Single frames are returned in the PAYLOAD of the vpcmd_dev_singlepno command response.
· In this payload, the pno frame does not include the leading PREAMBLE and SIZE fields.
Continuous:
· Call vpcmd_dev_contpno().
· Demonstrated in StartCont() below.
Continuous streamed frame collection:
There are several VPcmdIF methods for collecting streamed P&O. The choice depends on how the caller is using the data.
· If it is required that ALL data is collected, for post processing and analysis, then use the vpcmd_dev_fifo...() functions. FIFO="first in, first out". So the caller will collect the next unread p&o frame from the collection buffer.
· To capture only the most current position of the tracked object for real time simulations/VR, use the vpcmd_dev_last...() functions.
· Demonstrated in ContLoop() below.
There is one last variation on the Pno functions: Raw frames or not.
· Raw Frames include the entire Viper Frame PREAMBLE leader, size, and CRC.
· PNO frames don't include the leader and size.
· When collecting the frame pointer through any of these methods, the pointed-to data is in thesame collection buffer.
· The reason for the two types is so that the same code can be used to parse and display single frames as is used for continuous frames. (Recall that single frames are picked out of the Single P&O command's payload and do not include the preamble and size.) This program uses the PNO frame capture rather than the Raw Frame capture for this reason.
· Demonstrated in ContLoop().
6. A note about frames.
· All Frames of data (CMD or PNO) received from devices are referenced by an instance of vpFrameInfo struct. (or CVPFrameInfo class).
· vpFrameInfo contains a pointer to the raw frame buffer and the size of the buffer.
7. Command structures.
· The ViperInterface.h header declares the raw command structures as consumed by the Viper device.
· The VPif.h file includes C++ classes for these same structures.
· The C++ classes provide a common programming interface for initializing, copying, filling/preparingm printing/exporting contents of the command struct without writing any additional code.
NOTE: VPcmdIF Report functions, or any other functions that you may find that use STD C++ 11 containers will require extra care when used by a calling app. Especially for reports, make sure that the std::string & passed into the report function already has reserved space to hold the generate string without allocating additional space. If the Report function causes a realloc in these objects there will be heap exceptions. Call std::string::reserve() first. Likewise, if you are passing in STD C++ objects that are not compatible with the STD C++ build in VPcmdIF, you will likely have problems. This is why the main VPcmdIF interface does not include STD C++ objects You can get around most of this by pulling in the VPif.h and VPif.cpp files into your own local project and building them yourself.
++++++++++++++++++++++++++++++++++
+++ Building with VPcmdIF. ++++++++
++++++++++++++++++++++++++++++++++
Build Notes:
· All builds of the VPcmdIF binaries are UNICODE.
· The VPcmdIF is available as a DLL. A future build will also produce a static library. Use of static library is not recommended unless the target app is built with the same compiler and linker as VPcmdIF.
Header Files:
At a minimum your code will need to include the following header files:
· VPcmdIF.h
· VPtrace.h -- only if you want use trace output in your own code.
Build settings:
Compiler:
Include Dirs: $(InstallDir)\Inc
Linker:
If using the VPcmdIF as a DLL:
Dirs: $(InstallDir)\$(Platform)\$(Configuration)\dll
Inputs: VPcmdIF.lib