VIPER Command Interface SDK (VPcmdIF) Limited Distribution Notes 220919a 0.0.0.58

Summary of Changes:

00058 –  (220609a) Bugfix: Command response buffer overflow after extended period of time sending/receiving commands.  Not affected by long periods of continuous P&O collection.

(220919a) New: Continuous pno collection filters out frames that contain invalid sensor numbers. 

Downloads:

1. VPwinDist_220919a.7z – VPcmdIF libraries, source files and samples.

2. VPwinDist_SYMB_220919a.7z. – Symbol files for debugging with VPcmdIF. 

Description:

(220919a) It has been observed that at 960 Hz it is possible for the tracker to initially emit syntactically correct frames that have invalid sensor ids.  This is a transient occurrence that has been observed occasionally at the start of pno collection.  This new filtering addition to the SDK validates the sensor ID to 0 thru 15, the maximum number of sensors supported by Viper.  The Filter does not detect the model Viper that is connected to find the upper limit of the sensor ID filter.  Corrupt sensor IDs have been consistently observed to be outside [0,15] 

Filtered frames are not buffered, so the caller will never receive them.  This may result in a skipped frame number at the beginning of continuous pno.

The filter is engaged automatically, and at all update rates.  If it is necessary to disengage the filter for performance, declare and call the following function locally as it is not declared in any header file:

int VPCMD_API vpdev_pnovalidate_sensor(vpcmd_context, vpdev_hnd, bool bvalidate);

History:

220117a      00057        CMD_OOR_MODE implemented to change behavior when sensors move 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

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