Pelco VideoXpert SDK 1.1 Quick Start Guide. VideoXpert_SDK_QSG-B 03 / 2016

Transcription

1 Pelco VideoXpert SDK 1.1 Quick Start Guide 03 / 2016

2 Contents Contents What Is the Pelco VideoXpert SDK?...3 Before Installing the Pelco VideoXpert SDK...5 Installing the Pelco VideoXpert SDK...6 Running the CPP Sample Program...14 Looking at the Source Code...21 Overview of the Pelco VideoXpert SDK Pelco VideoXpert SDK 1.1 Quick Start Guide

3 What Is the Pelco VideoXpert SDK? What Is the Pelco VideoXpert SDK? Pelco by Schneider Electric offers the Pelco VideoXpert Software Development Kit (VideoXpert SDK) to help our development partners write applications that communicate with Pelco products and integrate with non-pelco products and software. The Pelco VideoXpert SDK handles the interface to VideoXpert, which then communicates with various Pelco devices on behalf of your application. The Pelco VideoXpert SDK encapsulates the following Pelco products and features. Table 1: Pelco VideoXpert SDK Features Functionality VideoXpert Device Collection System Auto Discovery N Login Live Streaming Playback Delivery Mode (Unicast/Multicast) Stream Protocol (RTP/RTSP) RTSP only MJPEG Support Low Bandwidth Video Query Manual Recording Network Display Support N Audio Continuous Pan Continuous Tilt Continuous Movement Stop Continuous Movement Pan to a specific position Tilt to a specific position Determine if camera supports PTZ Move to a specific position Move to a position relative to the current location Get the Camera's current position Manage the Magnification (Zoom) value Manage the Focus value Iris control Get existing Presets and Patterns Create a Preset N Create a Pattern N Go to an existing Preset Remove an existing Preset N Pelco VideoXpert SDK 1.1 Quick Start Guide 3

4 What Is the Pelco VideoXpert SDK? Functionality VideoXpert Update an existing Pattern N Execute an existing Pattern Stop a Pattern currently being executed Toggle Wiper N Export a Single Clip Export Multiple Clips via Clip Collection Remote Export Include Overlays in Export N Event Subscription/Unsubscription Insert Events Manage Situations To get started with the Pelco VideoXpert SDK you can: Make sure you meet the right hardware and software requirements before you begin. Install the Pelco VideoXpert SDK on your computer. Run a sample VideoXpert SDK application. From Visual Studio, view the source code. Learn more about the classes provided with Pelco VideoXpert SDK. 4 Pelco VideoXpert SDK 1.1 Quick Start Guide

5 Before Installing the Pelco VideoXpert SDK Before Installing the Pelco VideoXpert SDK Before installing the Pelco VideoXpert SDK on your local machine, make sure your computer meets the following hardware and software requirements. Hardware Requirements The Pelco VideoXpert SDK requires a Pelco VideoXpert systemwith which to communicate. Other than that there are no hardware requirements, only a recommended minimum configuration. Recommended Configuration: CPU: Intel Core i7 2.4GHz Quad Core (or greater) Memory: 4 GB (or greater) Graphics: Dedicated graphics card with at least 1024 MB of memory, and a PCI Express bus Hard disk: 1GB available hard disk space NOTE: The Pelco VideoXpert SDK does not support displaying video on virtual machines. Software Requirements When developing your application with the Pelco VideoXpert SDK, the following dependencies apply. Microsoft.NET Framework Installation Directory By default, the Pelco VideoXpert SDK installs into one of the following directories: 64-bit systems: C:\Program Files (x86)\pelco\vxsdk 32-bit systems: C:\Program Files\Pelco\VxSdk What's Next? Follow the installation instructions. Pelco VideoXpert SDK 1.1 Quick Start Guide 5

6 Installing the Pelco VideoXpert SDK Installing the Pelco VideoXpert SDK Follow these steps to install the Pelco VideoXpert SDK on your local computer. NOTE: The installation must be performed from an account with Administrator privileges. 1. Get the latest Pelco VideoXpert SDK installation package from 2. Launch the Pelco VideoXpert SDK installer.exe file to start the SDK install process. Follow the prompts to perform the installation. 3. Confirm the install location. 6 Pelco VideoXpert SDK 1.1 Quick Start Guide

7 Installing the Pelco VideoXpert SDK 4. The installer provides progress updates. 5. Installation complete! Pelco VideoXpert SDK 1.1 Quick Start Guide 7

8 Installing the Pelco VideoXpert SDK 6. The installer launches the KeyGen application as the final step of the process. KeyGen allows the user to enter project-specific information, and then produces a key corresponding to the integration project. The key is then inserted into the VideoXpert SDK. It provides the project information as part of the Feedback tool. In the future the role of the key may expand. 8 Pelco VideoXpert SDK 1.1 Quick Start Guide

9 Installing the Pelco VideoXpert SDK 7. All fields are required. Attempting to generate a key without filling in each field results in the application displaying a reminder. 8. After filling in all fields, click Generate Key. The key field contains a long string that corresponds to the hashed project information. Retain the key value for use when using the Feedback application. Pelco VideoXpert SDK 1.1 Quick Start Guide 9

10 Installing the Pelco VideoXpert SDK 9. The Pelco VideoXpert SDK root folder contains a SDK folder and a Tools folder. 10 Pelco VideoXpert SDK 1.1 Quick Start Guide

11 Installing the Pelco VideoXpert SDK 10. The SDK/ folder contains 32- and 64-bit Debug and Release builds of the SDK. Pelco VideoXpert SDK 1.1 Quick Start Guide 11

12 Installing the Pelco VideoXpert SDK 11. Tools/ holds the KeyGen and Feedback tools used by the SDK. The various build folders share a common structure, as shown in the following screenshot. 12 Pelco VideoXpert SDK 1.1 Quick Start Guide

13 Installing the Pelco VideoXpert SDK The directories installed under each VideoXpertSDK\SDK\ build folder contain the following: Pelco VideoXpert API directory Description Bin Supporting libraries Include Header files for all SDK classes Lib Primary SDK libraries NOTE: The installer does not add or update environment variables to reference these folders. our projects should include any necesary paths in the project settings. The next section illustrates one of the sample programs available for the Pelco VideoXpert SDK. Pelco VideoXpert SDK 1.1 Quick Start Guide 13

14 Running the CPP Sample Program Running the CPP Sample Program The Pelco VideoXpert SDK has available for download several sample programs to help you become familiar with the SDK. These sample programs are packaged as Visual Studio projects and may be installed separately from the SDK. This section discusses the process of building and running the C++ sample program called CPP. The application logs in to a VideoXpert system and gets a list of the cameras that the system recognizes. ou can select a camera from the list and view its live video stream and play back recorded video. ou can also export video, view events, and perform PanTilt-Zoom operations on cameras that support PTZ. ou will need the IP address, user name, and password of the VideoXpert system in order to log in. 1. From Visual Studio, open CPP.vcxproj. 2. From the Build menu, select Build Solution. 3. If the project does not build check the project properties. If it cannot find the include files, check the Project > Properties > Configuration Properties > C/C++ > Additional Include Directories. 14 Pelco VideoXpert SDK 1.1 Quick Start Guide

15 Running the CPP Sample Program Ensure the path to the SDK header files and third party application header files are listed. If the project does not link, check Project > Properties > Configuration Properties > Linker > Additional Library Directories. Pelco VideoXpert SDK 1.1 Quick Start Guide 15

16 Running the CPP Sample Program Ensure the paths to the SDK libraries and third party application files are listed. 4. Edit the application Constants.h file. Set the IP address, user name, and password of the VideoXpert system. Communication with VideoXpert occurs over port 443, so ensure that port is open. 5. Start the application. The application starts and reads from its Constants.h file the IP address, user name, and password of the VideoXpert system. It then attempts to connect to the system and fetch the system device list. 16 Pelco VideoXpert SDK 1.1 Quick Start Guide

17 Running the CPP Sample Program 6. Once connected to the system the application displays a main menu. 7. Select 1. Devices The application displays the Devices menu. Pelco VideoXpert SDK 1.1 Quick Start Guide 17

18 Running the CPP Sample Program 8. Select 1. View all Devices The application displays a list of attached Devices. 9. From the Devices menu, select 4. Live Streaming. Choose a camera index and follow the prompts. 18 Pelco VideoXpert SDK 1.1 Quick Start Guide

19 Running the CPP Sample Program The application pops up a separate window containing the video stream. Pelco VideoXpert SDK 1.1 Quick Start Guide 19

20 Running the CPP Sample Program This example provided an overview of what a Pelco VideoXpert SDK application can do. The next section discusses the source code for this application. 20 Pelco VideoXpert SDK 1.1 Quick Start Guide

21 Looking at the Source Code Looking at the Source Code The CPP application provides an example of how to use the SDK in your Pelco applications. The SDK provides a set of C++ structs, in some cases POD (plain old data), in many cases including member functions. The CPP application wraps the structs in classes and adds member functions. There's a lot going on in the CPP application, so this discussion focuses on the code required to get a video stream from a camera and display it. Here, the CPP program: 1. Connects to a VideoXpert system 2. Creates a System object to represent the VideoXpert system. 3. Gets a list of the system's devices and filters it for a list of cameras. Main Program Start with main(), located in the file main.cpp. The application first creates an instance of the CPPConsole::System class. A connection is automatically initiated to the system using credentials from the application's Constants.h file. After successfully logging in, the application fetches the list of devices connected to the VideoXpert system. int main( int argc, char* argv[] ) cout << "VxSDK C++ console application - Started.\n\n"; // Create an instance of wrapper class, all the SDK methods will be called with the help of wrapper classes CPPConsole::System* sys = new CPPConsole::System(); cout << "Connecting to system " << ksysip << "...\n"; bool loggedin = sys->login( ksysip, kportnum, kusername, kpassword ); if (!loggedin ) cout << "Failed to login!!\n"; else cout << "Logged into system:" << ksysip << " as " << kusername << "\n"; cout << "Fetching devices from system, Please wait...\n"; list<cppconsole::device*>* devices = sys->getdevices(); cout << devices->size() << " devices found.\n";... The application then displays the main menu (not shown) and waits for input from the user. Connecting to a VideoXpert System Open the System.cpp file and locate the CPPConsole::System::Login method. This is the first step in a Pelco VideoXpert SDK application: connect to the appropriate system. NOTE: Communication with VideoXpert occurs over port 443, so ensure that port is open. bool CPPConsole::System::Login( const char* ip, int port, const char* user, const char* passwd ) VxSdk::VxLoginInfo logininfo; strncpy_s( logininfo.ipaddress, ip, sizeof( logininfo.ipaddress ) ); logininfo.port = 443; logininfo.ssl = true; strncpy_s( logininfo.username, user, sizeof( logininfo.username ) ); strncpy_s( logininfo.password, passwd, sizeof( logininfo.password ) ); VxSdk::IVxSystem* system = nullptr; VxSystemLogin( &logininfo, &system ); _system = system; Pelco VideoXpert SDK 1.1 Quick Start Guide 21

22 Looking at the Source Code if ( _system!= nullptr ) return true; else return false; Getting the Device List The following method fetches the collection of devices from the System object. This method provides a good example of how the application classes access the returned structures and create local copies. The remote device collection (of type VxSdk::VxCollection<VxSdk::IVxDevice**>) contains IVxDevice objects. These are copied to the application's _devicelist object. The method releases the remote objects (devices) prior to returning. Note the size checking and validation of return codes. list<cppconsole::device*>* CPPConsole::System::GetDevices() if ( _devicelist!= nullptr ) for ( std::list<cppconsole::device*>::const_iterator iterator = _devicelist->begin(), end = _devicelist->end(); iterator!= end; ++iterator ) delete *iterator; delete _devicelist; _devicelist = new list<cppconsole::device*>(); VxSdk::VxCollection<VxSdk::IVxDevice**> devices; VxSdk::VxResult::Value result = _system->getdevices( &devices ); if ( result == VxSdk::VxResult::kInsufficientSize ) devices.collection = new VxSdk::IVxDevice*[ devices.collectionsize ]; result = _system->getdevices( &devices ); if ( result == VxSdk::VxResult::kOK ) for ( int i = 0; i < devices.collectionsize; i++ ) _devicelist->push_back( new CPPConsole::Device( devices.collection[ i ] ) ); delete[] devices.collection; return _devicelist; Get a Camera's Video Streams In main.cpp, the DoLiveStreamingOption method provides a more complex example of how to use the properties of a camera to find a video stream. A camera contains data sources (streams), each of which uses a specific data interface protocol (MJPEG or RTP/RTSP). This method starts by reading the user input for the camera index, which is the number listed in the GetDevices call. The user selects whether the streaming should be done using MJPEG or RTP/RTSP. The method iterates over the data sources and data interfaces for the camera until it finds a match for the protocol selected by the user. Note that the method fails silently if a match is not found. void DoLiveStreamingOption( list<cppconsole::device*>* devices ) int camnum; 22 Pelco VideoXpert SDK 1.1 Quick Start Guide

23 Looking at the Source Code cout << "\n\n Enter camera index: "; cin >> camnum; std::list<cppconsole::device*>::iterator it = std::next( devices->begin(), camnum - 1 ); if ( (*it)->getdevicetype()!= CPPConsole::Device::DeviceType::Camera ) cout << "\n Device you selected is not a camera!!\n"; return; bool ismjpegenabled = false; string mjpegoption = "N"; cout << "\n Do you want to play MJPEG (/N) [Default is RTSP]: "; cin >> mjpegoption; if ( mjpegoption == "" mjpegoption == "y") ismjpegenabled = true; ShowDeviceDetails( *it ); std::list<cppconsole::datasource*>* datasources = (*it)->getdatasources(); CPPConsole::DataSource* datasourceselectedforstreaming = NULL; for (std::list<cppconsole::datasource*>::const_iterator iterator = datasources->begin(), end = datasources->end(); iterator!= end; ++iterator ) std::list<cppconsole::datainterface*>* datainterfaces = (*iterator)>getdatainterfaces(); for ( std::list<cppconsole::datainterface*>::const_iterator datainterfaceiter = datainterfaces->begin(), end = datainterfaces->end(); datainterfaceiter!= end; + +datainterfaceiter ) if ( ismjpegenabled == true ) if ( (*datainterfaceiter)->getprotocol() == CPPConsole::DataInterface::StreamProtocol::kStreamProtocolMjpegPull ) datasourceselectedforstreaming = (*iterator); break; else if ( (*datainterfaceiter)->getprotocol() == CPPConsole::DataInterface::StreamProtocol::kStreamProtocolRtspRtp ) datasourceselectedforstreaming = (*iterator); break; if ( datasourceselectedforstreaming!= NULL ) StartStreamingForDataSource( datasourceselectedforstreaming, ismjpegenabled, nullptr ); Pelco VideoXpert SDK 1.1 Quick Start Guide 23

24 Looking at the Source Code Start a Video Stream The StartStreamingForDataSource method in main.cpp initiates streaming for either the MJPEG or RTP stream. It uses third-party libraries to create and display the stream. If the camera supports Pan-Tilt-Zoom (PTZ), the available PTZ commands are listed in the console window. The user can enter a PTZ command in the console and see the result in the stream window. 24 Pelco VideoXpert SDK 1.1 Quick Start Guide

25 Overview of the Pelco VideoXpert SDK Overview of the Pelco VideoXpert SDK The Pelco VideoXpert SDK contains a number of libraries and header files that represent pieces of a Pelco video management system. The header files contain C++ struct declarations that represent systems and connected devices, such as cameras, recorders, encoders, decoders, and monitors. There are also structs for locally-created objects. The naming convention is as follows: Prefix Description Example IVx Interface for an object passed from VideoXpert to the client application. IVxDevice Vx "Plain old data" types created in the client application. VxLoginInfo The top-level namespace is VxSdk::, which encompasses most of the SDK classes/structs. There is one child namespace, VxSdk::Utilities, for commonly-used utiity functions. Structs of Pelco VideoXpert SDK 1.1 The list below introduces the Pelco VideoXpert SDK header files and their contents. This list is not exhaustive. Refer to the SDK reference documentation for more details, such as enumerated type values. Header Filename (.h) Description IVxBookmark Represents a point in time of interest with reference to a particular data source. IVxClip Represents a contiguous duration of stored media originating from a single DataSource. IVxDataInterface Represents an interface to a data source. IVxDataObject Represents a custom serialized data object submitted by a client and stored on the server. The data is completely opaque to the server and other types of clients. IVxDataSession Represents a data session that is being transmitted by a data source, via a data interface, to a client. IVxDataSource Represents a data producer in the system hosted by a device. Each DataSource provides a list of DataInterface, which provide a particular protocol used to transmit and control the data produced by this DataSource. IVxDevice Represents a particular physical device in the system. IVxDeviceAssignment Represents a device assignment on a data storage. It can also specify the driver to use to communicate with the physical device. IVxDriver Represents a device communication driver. IVxEvent Represents an instance of a particular situation that has occurred. IVxExport Represents an exported data set that is archived within the system. IVxExportClip Represents an individual range of media data belonging to an Export. This data shall be exported when the Export is triggered. IVxPattern Represents a predefined sequence of movement that a PTZ device can perform when triggered. A running pattern will be halted upon any other PTZ request. Pelco VideoXpert SDK 1.1 Quick Start Guide 25

26 Overview of the Pelco VideoXpert SDK Header Filename (.h) Description IVxPreset Represents a predefined point that a PTZ device can PTZ to when triggered. IVxPrivilege Represents a specific permission that is given to a role. IVxPtzController Represents a controller for a device that has pan, tilt, and/or zoom functionality. IVxPtzLock Represents a lock for a ptz controller. IVxRole Represents a collection of permissions which can be assigned to a user. IVxSchedule Represents a recording schedule. A schedule is a group of 0 or more resources associated with a set of time and/or event based schedule triggers that, when any are active, cause the scheduled action to be performed. IVxScheduleTrigger Represents a schedule trigger. A schedule trigger is a time range and an optional event that together act as a trigger to activate a schedule and cause it to perform its configured action. IVxSituation Represents a particular situation configuration that specifies how corresponding events shall be generated and handled when the situation is detected. IVxSystem Represents a VideoXpert system and allows the user to manage the system and devices. IVxTag Represents a non-hierarchical identifier typically associated with one or more resources (i.e. device or data source). A tag helps to describe a resource and allows it to be found more efficiently. IVxUser Represents information about a system user. VxAuthInfo Represents the information needed to log in to a VideoXpert system. VxCollection Represents a collection of resources. VxCollectionFilter Represents a filter to be used when creating a VxCollection. VxKvObject Represents a key/value pair object. VxLoginInfo Represents the information needed to log in to a VideoXpert system. VxMacros Miscellaneous macros, such as array-zeroing VxNewBookmark Represents a new bookmark to be created. VxNewDataObject Represents a new data object to be created. VxNewDeviceAssignment Represents a new device assignment to be created. VxNewEvent Represents a request for a new event to be generated. The event will be generated based upon the NewEvent data, its Situation configuration, and will receive a unique identifier. VxNewExport Represents a new export to be created. VxNewExportClip Represents a clip that will be exported as part of a VxNewExport. VxNewPrivilege Represents a new privilege to be created. VxNewSchedule Represents a new schedule to be created. A schedule is a group of 0 or more resources associated with a set of time and/ or event based schedule triggers that, when any are active, cause the scheduled action to be performed. 26 Pelco VideoXpert SDK 1.1 Quick Start Guide

27 Overview of the Pelco VideoXpert SDK Header Filename (.h) Description VxNewScheduleTrigger Represents a new schedule trigger to be created. A schedule trigger is a time range and an optional event that together act as a trigger to activate a schedule and cause it to perform its configured action. VxNewSituation Represents a new situation configuration that specifies how corresponding events shall be generated and handled when the situation is detected. VxNewTag Represents a new tag to be created. VxNewUser Represents a new user to be created. VxPrimitives Enumerated constant values. VxSdk Umbrella header that includes the other header files. VxSnapshotFilter Represents a filter to be used when creating a VxCollection. VxUtilities String copy functions. Pelco VideoXpert SDK 1.1 Quick Start Guide 27

28 Pelco by Schneider Electric 3500 Pelco Way Clovis, California USA (800) Tel (800) Fax +1 (559) International Tel +1 (559) International Fax Schneider Electric. All Rights Reserved. All trademarks are owned by Schneider Electric Industries SAS or its affiliated companies.