VIPER Command Interface SDK (VPcmdIF) Distribution Notes 241028a 0.0.0.62

Summary of Changes:

00062 –  (241028a) Serial connection improvements and bugfixes.

(240807a) Experimental CVPSeuPnoII class added to VPif.h

(240606a) Bugfix: E_VPERR_CMDRSP_MISMATCH error reported sometimes even when correct response is found in the command response queue.

Downloads:

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

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

Description:

Serial connection improvements:

· Command frame validation added to serial connection (COM port specified) and serial connection discovery (COM port wildcarded).  This change verifies that the device on the other end of the connection is actually a Viper.  Validation uses the CMD_SEUID command and involves verifying that the Viper preamble is at the front of the received frame and the correct number of bytes are received.

· Bugfix: During discovery, if no ports are present, discovery fails with VPERR_NOT_FOUND.

· Bugfix: During discovery, if a port fails validation, discovery moves on to the next detected port.  Trace messages show the number of detect ports and each port as it is tested.

· Bugfix: Setting trace level to 5 does not cause serio lib to output a slew of traces for looped reads.  If you really want that, use level 7.  

· Included Release build of VPcmdConsole uses level 3, Debug build uses 5.  Select ‘s’ to connect via Serial port.  This wildcards the port number and initiates COM port discovery.

Experimental CVPSeuPnoII class:

The native VP_PNO base structure for the original CVPSeuPno contains a simple array of sensor data:

SENFRAMEDATA sarr[SENSORS_PER_SEU].  

If non-sequential sensors are connected to Viper, the index into this array will not match the sensor number in the SENFRAMEDATA because Viper does not output data for sensors that are not present. 

When data is extracted from a raw buffer with CVPSeuPnoII::ExtractrawII(), it maps sensors data to std::map so sensor data accessible by specifying sensor num rather than index into sarr[].

Use this class if you need to reference data from individual non-sequential sensor numbers. To reference output from an non-sequential individual sensor, call CVPSeuPnoII::SensFrameII(int sns) to retrieve sensor data.

Original ExtractRaw() and SensFrame() methods are still available in the new class.

Note, this class is not derived from CVPSeuPno.  It is a copy—in the future it could be modified to be a derivation.

History:

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

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