MVE™ API User`s Guide
Contents
1. to an MVE device IP address or domain name of the device which contains MVE TCP port numbers where the MVE device is listening user name and password for the authentication process pointer to a callback function that handles the incoming messages The IP address can be found in the user s manual of the given device or the network administrator can provide this information if the IP assignments are managed by a DHCP server The TCP port numbers are 12000 and 12001 There is one TCP port for the device to host and one for the host to device com munication The user name and the password are specified in the user s manual of the device Rev 0 6 Sept 28 2015 9 MVE V2 API User s Guide Eutecus Inc HicH LeveL MVE API The API sends all the messages that come from the MVE device to the application via a callback func tion This callback function needs to be implemented at the application level and the prototype of this function can be found in Bii_HostData h as The last two parameters specify the ini files that contain the application parameters for all channels The usage of the function is shown in the following example void BIIAPI ProcessInformation unsigned int message void wParam void lParam Message handling needs to be implemented here Moss char IniFiles ParametersCHl ini ParametersCH2 ini ParametersCH3 ini ParametersCH4 ini Weel nne eegen Mii2. 1 2 Control MESSAGES 1 nt eben ege e tr oerte ert ltd 10 3 2 Parameter Handling de tete a 10 3 2 1 Synchronizing the Parameter Structure with the MVE device ssusessse 10 3 2 2 Set Get Parameter Values sss nennen sensns 11 3 9 Metadata Mandl ing EE 11 3 3 1 Opening a Metadata Stream sssssssssssssssssssss semen nnne 11 3 3 2 Closing a Metadata Giream hehehe nennen Aa nnne 12 3 3 3 Metadata Connection Check 12 3 3 4 Metadata Package Handling ccoooncccccoonnocccononnnnccnnnncncnonnnnnnnnnnnoncnnnnnnnnnnnnnncnnnanane 12 3 3 5 Sample Metadata Capture Application ssssssseeeeemeennn n 13 Rev 0 6 Sept 28 2015 3 MVE V2 API User s Guide List of Examples 3 1 Single Command Configuratio M cece eee a aa e eene neret a E nnne nnns enses nnne 10 3 2 Sample Metadata Capture Application sess nemen nnne 13 Rev 0 6 Sept 28 2015 4 MVE V2 API User s Guide 1 API Overview 1 1 Introduction The MVE Application Programing Interface is a cross platform API that can control and configure an MVE device From the MVE API s point of view the MVE device hereinafter the device functions as a server so it listens on different TCP ports waiting for connections from a remote client hereinafter the host and provides its services through these ports 1 2 Supported Platforms The MVE API has been imple
3. Multi core Video Analytics Engine MVE V2 API User s Guide V0 6 Sept 28 2015 www eutecus com Eutecus Inc 1936 University Ave Suite 360 Berkeley CA 94704 info eutecus com Phone 510 540 9603 Fax 510 649 7808 Copyright 2015 Eutecus Inc Copyright Altera Cyclone Nios Qsys and Quartus are trademarks of Altera Co Products and specifications discussed herein are for evaluation and reference purposes only and are subject to change by Eutecus Inc without notice All information discussed herein is provided on an as is basis Eutecus Inc makes no warranties expressed or implied as to its accuracy and assumes no liability in connection with any use of this product Table of Contents TAP OVGPVIOW t ters et Ce ea EE Ei t a t eue Eed ES 5 L t ott e2 sec Save rmm 5 1 2 Supported Platforms 2 tte t Ee e tetendit tatit oe edet a e eek 5 ALIVIO WS dp 5 A A e et ette ee eO i E E edem E ied tede etaed 5 2 Low Level MVE M AP eoe deett tak etta e ee e Mee 6 2 1 Firmware Update Service i inet o eie perire tr idee LEES E oem du Eo p Leu 6 A A ett dessin rete dt be defeat tee dtr tta dene redd 6 2 1 2 Gompute Firmware Flash ais tee o pide ero Ee beoe eee tite iata 6 22 SO o IR UR Re ud Lese E tr c 6 2 3 Sample Firmware Update Application With Version Check 7 3 EiobtzEevek uude Em 9 cie eren este ETE 9 3 1 1 Single Command Configuration sssssssssssssseneeeeen nennen nnns 9 3
4. SA LEO QU OOO 120 User Password ProcessInformation 4 IniFiles Example 3 1 Single Command Configuration 3 1 2 Control Messages The device sends control messages to inform the host about an event Typically the first event that will trigger the callback function is the MSG_CONNECT This message informs the host that the connection with the MVE device has been established The following control messages are supported by the high level MVE API BII_MSG_CONNECT Connection established message from the device BII_MSG_DISCONNECT Disconnect request by the host and disconnect notification by the device 3 2 Parameter Handling Parameter handling is the most important part of the high level MVE API This provides an interface to set the MVE algorithmic parameters and the device configuration parameters 3 2 1 Synchronizing the Parameter Structure with the MVE device Synchronizing the parameter structure is an essential part of the parameter handling Without this syn chronization the parameters cannot be set to the MVE device The synchronization process is fully au tomatic and handled by the MVE API The MVE API will fill out the parameter description structure during the configuration process The MVE device provides all the information about the parameters like type address and range and the MVE API responds with the parameter values based on the ini file that was set with th
5. argv 0 lt lt CTIPLADDRESS Elemwareltolder lt lt std endl std cout lt lt Validating firmware version numbers lt lt std endl bool firmware_update_required true std cout lt lt Connecting to secondary device status interface SIN A lt lt ev lt lt Jm lt lt giecls seimclilp void StatusServiceHandle Bii_StatusServiceConnect argv 1 12011 2 if nullptr StatusServiceHandle std cerr lt lt Error connecting secondary device Status port is unavailable lt lt std endl else std cout lt lt Get FPGA firmware hash lt lt std endl auto SystemHashMap Bii_StatusServiceGetSystemHash StatusServiceHandle Bii_StatusServiceDisconnect StatusServiceHandle if 2 gt SystemHashMap size std cout lt lt Get FPGA firmware hash FAILED lt lt SystemHashMap size lt lt lt lt std endl else std cout lt lt Get FPGA firmware hash DONE lt lt std hex lt lt std endl for auto const amp hash SystemHashMap Sed eener hasse lt lt lt lt mera secon sss tci na Siecle Bicxowble lt lt lt Gueule dee std ecoute lt lt Gee an SS aon U lt lt een L it lt lt VV coe lt lt siecle seinnelils auto FirmwareFileHash Bii_FirmwareHash argv 2 if FirmwareFileHash empty std cerr lt lt Get firmware file hash from lt lt argv 2 e UN AIDE No Elrmware cound lt lt siecl
6. device address communication port and an optional timeout value an opaque handle ob ject is returned which shall be used for subsequent service requests After the last request the connec tion shall be closed by calling Timestamping reboot status version and hardware ID retrieval functions are available via the and functions respectively The hashes of the current device firmware parts can be fetched by the function which returns with an containing the firmware part name and its Rev 0 6 Sept 28 2015 6 MVE V2 API User s Guide Eutecus Inc Low LeveL MVE API hash This can be used to compare the firmware on the device and on storage To compute the hashes of a firmware stored in the filesystem please refer to the function of the Firmware Update Service 2 3 Sample Firmware Update Application With Version Check Utilizing the status service s facilities it is possible to write an automatic firmware update application which only updates the firmware if it does not match with the firmware in the MVE device include lt iostream gt include Bii_FirmwareUpdate h include Bii StatusService h void BIIAPI UpdateStatus Bii UpdateStage stage unsigned int percentage Std cout Updating firmware Bii UpdateStage2String stage ror lt lt percentage lt lt lt lt std endl alme menla Gba enee elacue aga a EET std cerr lt lt Usage Return lt lt
7. e Firmware Up date Service and the Status Service 2 1 Firmware Update Service 2 1 1 Firmware Update The facilities in Bii_FirmwareUpdate h allows updating the device firmware by calling the function which requires 1 the device IP or domain name address 2 the path to the firmware directory 3 a callback function which gets called regularly with the current status of the firmware update 4 a firmware update target optional defaults to Application firmware update 5 send receive timeout optional defaults to 2000 ms Both the callback function prototype lt and a helper function to convert the update stage enum to a textual representation is available in the Bii_FirmwareUpdate h header file 2 1 2 Compute Firmware Hash A device firmware consists of several parts The hashes of these parts of a firmware stored in the filesys tem can be computed by the function which returns with an contain ing the firmware part name and its hash This can be used for example to compare the firmware on the device and on storage To compute the hashes of the current firmware on a device please refer to the function of the Status Service 2 2 Status Service System status retrieval reboot timestamping version and device ID fetch and firmware hash functionality is provided via the status service API defined in the Bii StatusService h header Upon successfully connecting to the status service via the function passing the
8. e enal else Sede Cout soc Estgen Ellen Jeer aon UY lt lt ees iteg Vo NIMMT Sed peo lt lt ne asi W lt lt ele glues lt lt siecle e alt for auto const amp hash FirmwareFileHash SES OS hash cirst lt lt US U lt lt hash second lt lt std eendi Siecle Beebe S Gicicls EOS Rev 0 6 Sept 28 2015 7 MVE V2 API User s Guide Eutecus Inc Low LeveL MVE API if 2 lt SystemHashMap size FPGA firmware is matching with firmware in sciendi SrCe Seele ee lt lt a AO need firmware_update_required if firmware_update_required Silica Ol tama bool retval std cout lt lt Firmware upd return 0 to update false d FPGA firmware update is needed Bii FirmwareUpdate argv 1 ate was SystemHashMap FirmwareFileHash amp amp argv 2 Sciens UpdateStatus SUCCESSFUL WNGINISIOC CIS SE Ws lt lt lt reels sreiqvelil 2 Rev 0 6 Sept 28 2015 MVE V2 API User s Guide 3 High Level MVE API The high level MVE API provides complex control and configuration options for the MVE device This API makes it easy to set the algorithmic parameters for the MVE or receive the metadata stream from the device The high level MVE API interface is declared in the MVE_ h header files 3 1 Control Service The Control Service is declared in the MVE_Control h header file The functionality is pr
9. e or functions The parameter description structure contains the path of the parameter the type the address in the devi ce s memory for the parameter update and the parameter value This structure has to be initialized in or Rev 0 6 Sept 28 2015 10 MVE V2 API User s Guide Eutecus Inc HicH LeveL MVE API der to modify a parameter value The structure can be initialized based on the XML description which will be available in future releases 3 2 2 Set Get Parameter Values The parameter values can be set changed or modified after the parameter description structure was ini tialized There are two ways to initialize this structure by synchronizing it to the MVE device or using the XML based parameter description available in future releases The following functions can be used to access the parameters The e function which can set the new parameter value requires the path of the parameter and the new parameter value with the same type as the original parameter The different types of parameters are supported by functions with different argument types The enumeration type parameters are used as integer parameters and the string based enumeration handling will be availa ble in future releases The MVI e function requires the path of the parameter and returns with the value of the parameter The different parameter types are supported by functions with different return types The enumeration type sup
10. mented in C and has been compiled and tested on Windows and Linux platforms More generally it is a cross platform API that can be used on any platform where a suitable C compiler thread support libraries and BSD socket networking are available The API package includes binary and header files The header files are the same for all platforms and these combined is the unified interface of the MVE API The binary file includes the precompiled C codes for the given platform and it has to be linked to or dynamically loaded by the application 1 2 1 Windows The MVE API is compiled with MS Visual Studio 2013 for Microsoft Windows 7 The must be linked to the application Make sure that the include and library paths are set properly to point to the include and lib folders respectively of the MVETM API package 1 2 2 Linux The MVE API is compiled with GNU GCC s g version 4 7 4 9 depending on the project for Linux The C 3SAl has to be linked and the pthread library has to be added to the project for a suc cessful compilation Make sure that the include and library paths are set properly to point to the include and lib folders of the MVE API package Rev 0 6 Sept 28 2015 5 MVE V2 API User s Guide 2 Low Level MVE API The low level MVE API provides the basic services for an MVE device The interface is declared in the Bii_ h header files named after the service name The implemented services are th
11. ovided via an opaque handler object The function initializes and returns the high level MVE API handler object without starting analytics on the device thus allowing off line parameter tuning and or parameter set up The e function creates a new parameter and can only be used in off line mode The M and M i i functions get and set a parameter value re spectively The function returns a description of a parameter These functions can be used in both on line and off line parameter tuning The function starts the video analytics on the device with the parameters stored in the han dler object and optionally pre tuned off line The e function shall be used to close an established connection to an MVE device The connection state can be checked by the function which checks both the host to device and the device to host connection state Note that this process is a passive check i e not an echo reply check so it only knows about already encountered errors 3 1 1 Single Command Configuration If off line parameter tuning is not needed the high level MVE API provides a very simple interface to configure an application on the MVE device with only one function call Only the function has to be called and it loads the parameters from storage establishes the connection with the device up loads all the parameters and starts video analytics This function requires the following information to establish a connection
12. port is the same as for the set function 3 3 Metadata Handling Metadata handling is a callback oriented one directional interface originating in the MVE V2 metadata capable device Based on the analyzed video frame metadata is grouped into packages Each metadata package has a header describing the frame timestamp etc and consists of metadata containers about that single frame only All metadata about a certain frame is sent in a single metadata package The metadata handling interface is declared in the MVE_MetadataV2 h header files 3 3 1 Opening a Metadata Stream The top level metadata streaming class is the rac qe iors UR class ideciared in MVE_Metada taV2Capture h An object of this class is created by the z i r function Metadata handling shall be mplementea ina callback function It is recommended to register the callback function with a before connecting to the MVE device and starting the metadata streaming not to ioe any metadata package The callback will be called with the metadata package header object TMetadataV2Header and an std vector con sisting of the metadata containers in the package The signature of the callback function is the following void IMetadataV2Header const amp package header Std vector std shared ptr TMetadataV2Container amp amp containers To start the metadata streaming pass the IP address for Comain nea of the MVE device and option ally the metadata port
13. tadata containers are described in the Metadata Streaming Specification document Rev 0 6 Sept 28 2015 12 MVE V2 API User s Guide Eutecus Inc HicH LeveL MVE API 3 3 5 Sample Metadata Capture Application void SignalHandler int printf SIGINT signal has been received n if MetaDataHandle printf Sending metadata capturing stop message n MetaDataHandle gt StopCapture void PackageHandler IMetadataV2Header const amp h std vector lt std shared_ptr lt TMetadataV2Container gt gt amp amp containers Siecle sean lt lt la lt e Nails ena AUTO Cene e e CONE ANSeS Shae cout SI A IO std unique_ptr lt TMetadataV2Capturer gt MetaDataHandle MVE MetadataV2 Capturer Create ao ena miae or Mc hadas qma signal SIGINT SignalHandler E targa 593p A printf Usage s ip address port n argv 0 return 1 MetaDataHandle gt RegisterPackageHandler PackageHandler Std cout MVE Metadata capture start std endl MetaDataHandle gt StartCapture argv 1 atoi argv 2 while MetaDataHandle gt IsConnected ifdef WIN32 Sleep 10 else LINUX usleep 10000 endif std cout lt lt MVE Metadata capture stop lt lt std endl return 0 Example 3 2 Sample Metadata Capture Application Rev 0 6 Sept 28 2015 13 MVE V2 API User s Guide
14. to the T apture function The registered metadata package callback function will be called each time a metadata package is received The IP address of the device can be found in the user s manual of the device or the network administra tor can provide this information if the IP address range is managed by a DHCP server Rev 0 6 Sept 28 2015 11 MVE V2 API User s Guide Eutecus Inc HicH LeveL MVE API Refer to the basic metadata capture setup in the sample metadata capture example Section 3 3 5 Sam ple Metadata Capture Application 3 3 2 Closing a Metadata Stream To close a metadata connection simply call the T1 3 j function Note It is important that the application has to handle the meta data packages until the metadata connection towards the device is fully closed otherwise the data pack ages will be lost The MVE device will drop metadata packages if it detects that the communication channel is stalled 3 3 3 Metadata Connection Check The metadata connection can be checked by the r and the al ing func tions If the handler is running its termination can be waited for by the Wai sh func tion 3 3 4 Metadata Package Handling The metadata packages are provided to the application through the callback function that were registered with the metadata streamer object The callback function can access the data structures that contain all the elements of the metadata con tainers The content of the me
Download Pdf Manuals
Related Search