VIPER Command Interface SDK (VPcmdIF) Distribution Notes 231114a 0.0.0.60

Summary of Changes:

00060 –  (231114a) Add vpdev_cmd_generic1() to retrieve all fields of response frame to a generic command.

(231108a) Add vpctx_dev_count() to retrieve number of devices connected via one context

Downloads:

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

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

Description:

vpdev_cmd_generic1() function added to enable manual parsing checking of all command frame fields returned in command response from tracker.

vpctx_dev_count() utility function for managing multiple devices connected under one context.

History:

220803a     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

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