VIPER Command Interface SDK (VPcmdIF) Limited Distribution Notes 210511a 0.0.0.53

Summary of Changes:

00053 - Limited distribution includes support for VIPER™ CAL DISABLE command.

 

Downloads:

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

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

Description:

New VIPER™ command CMD_DISABLE_CAL allows the programmer to suppress the VIPER™ cal cycle for up to one minute.  The duration of the cal cycle suspension is expressed as a number of frames and is dependent on the currently configured update rate.  For example, to suppress the cal cycle for 5 seconds at 960 Hz, input a frame count of 960*5 or 4800 frames.  To re-engage the cal cycle, input zero.

 

The CMD_DISABLE_CAL is executed with function cmd_dev_generic()in VPcmdIF.h:

int VPCMD_API vpcmd_dev_generic(vpcmd_context, vpdev_hnd, eCmdActions, uint32_t cmd, void * pay_buf, uint32_t size, uint32_t arg1, uint32_t arg2);

Example code for using this is found in the VPcmdWinConsole sample app.

Command is exercised from the main menu of the sample app, using menu selections 'G'.

Sample code for these functions is in CommandTest.h and also reproduced here:

 

void DoCalDisableTest()

{

   // first get frame rate

   CFrameRateCfg fcfg;

   int r = 0;

   r = vpcmd_dev_framerate(g_ctx, g_hnd, CMD_ACTION_GET, fcfg);

   DisplayError(r, "vpcmd_dev_framerate CMD_ACTION_GET");

 

   uint32_t fps = fcfg.EffectiveRate();

   int32_t maxdisabled = fps * 60; // max 1 minute worth of frames

   int32_t frames = maxdisabled;

   eCmdActions eact = CMD_ACTION_SET;

   if (CalDisablePrompt(frames, fcfg, eact))

   {

     r = vpcmd_dev_generic(g_ctx, g_hnd, eact, CMD_DISABLE_CAL, &frames, sizeof(int32_t), 0, 0);

     std::string s("vpcmd_dev_generic CMD_DISABLE_CAL ");

     s += CVPcmd::actstr(eact);

     DisplayError(r, s.c_str());

   }

}

History:

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