Pelco VideoXpert SDK 1.1 Quick Start...

Pelco VideoXpert SDK 1.1Quick Start Guide

VideoXpert_SDK_QSG-B 03 / 2016

Contents

2 | Pelco VideoXpert SDK 1.1 Quick StartGuide

VideoXpert_SDK_QSG-B

ContentsWhat Is the Pelco VideoXpert SDK?..............................................................................................................................3Before Installing the Pelco VideoXpert SDK...............................................................................................................5Installing the Pelco VideoXpert SDK.............................................................................................................................6Running the CPP Sample Program...............................................................................................................................14Looking at the Source Code...........................................................................................................................................21Overview of the Pelco VideoXpert SDK.....................................................................................................................25

What Is the Pelco VideoXpert SDK?

VideoXpert_SDK_QSG-B Pelco VideoXpert SDK 1.1 Quick Start Guide | 3

What Is the Pelco VideoXpert SDK?Pelco by Schneider Electric offers the Pelco VideoXpert Software Development Kit (VideoXpert SDK) to help our developmentpartners write applications that communicate with Pelco products and integrate with non-Pelco products and software. The PelcoVideoXpert SDK handles the interface to VideoXpert, which then communicates with various Pelco devices on behalf of yourapplication.

The Pelco VideoXpert SDK encapsulates the following Pelco products and features.

Table 1: Pelco VideoXpert SDK Features

Functionality VideoXpert

Device Collection Y

System Auto Discovery N

Login Y

Live Streaming Y

Playback Y

Delivery Mode (Unicast/Multicast) Y

Stream Protocol (RTP/RTSP) RTSP only

MJPEG Support Y

Low Bandwidth Y

Video Query Y

Manual Recording Y

Network Display Support N

Audio Y

Continuous Pan Y

Continuous Tilt Y

Continuous Movement Y

Stop Continuous Movement Y

Pan to a specific position Y

Tilt to a specific position Y

Determine if camera supports PTZ Y

Move to a specific position Y

Move to a position relative to the current location Y

Get the Camera's current position Y

Manage the Magnification (Zoom) value Y

Manage the Focus value Y

Iris control Y

Get existing Presets and Patterns Y

Create a Preset N

Create a Pattern N

Go to an existing Preset Y

Remove an existing Preset N

What Is the Pelco VideoXpert SDK?



Functionality VideoXpert

Update an existing Pattern N

Execute an existing Pattern Y

Stop a Pattern currently being executed Y

Toggle Wiper N

Export a Single Clip Y

Export Multiple Clips via Clip Collection Y

Remote Export Y

Include Overlays in Export N

Event Subscription/Unsubscription Y

Insert Events Y

Manage Situations Y

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.

Before Installing the Pelco VideoXpert SDK


Before Installing the Pelco VideoXpert SDKBefore installing the Pelco VideoXpert SDK on your local machine, make sure your computer meets the following hardware andsoftware requirements.

Hardware RequirementsThe Pelco VideoXpert SDK requires a Pelco VideoXpert systemwith which to communicate. Other than that there are no hardwarerequirements, 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 RequirementsWhen developing your application with the Pelco VideoXpert SDK, the following dependencies apply.

• Microsoft .NET Framework 4.5.1

Installation DirectoryBy 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.

Installing the Pelco VideoXpert SDK



Installing the Pelco VideoXpert SDKFollow 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 http://pdn.pelco.com/content/videoxpert-sdk-related-downloads.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.

http://pdn.pelco.com/content/videoxpert-sdk-related-downloads



4. The installer provides progress updates.

5. Installation complete!




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.



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.




9. The Pelco VideoXpert SDK root folder contains a SDK folder and a Tools folder.



10. The SDK/ folder contains 32- and 64-bit Debug and Release builds of the 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.



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. Your projects should include anynecesary paths in the project settings.

The next section illustrates one of the sample programs available for the Pelco VideoXpert SDK.

Running the CPP Sample Program



Running the CPP Sample ProgramThe Pelco VideoXpert SDK has available for download several sample programs to help you become familiar with the SDK. Thesesample programs are packaged as Visual Studio projects and may be installed separately from the SDK. This section discusses theprocess 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. You can select a camerafrom the list and view its live video stream and play back recorded video. You can also export video, view events, and perform Pan-Tilt-Zoom operations on cameras that support PTZ.

You 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.



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 LibraryDirectories.




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.



6. Once connected to the system the application displays a main menu.

7. Select 1. Devices The application displays the Devices menu.




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.



The application pops up a separate window containing the video stream.




This example provided an overview of what a Pelco VideoXpert SDK application can do. The next section discusses the sourcecode for this application.

Looking at the Source Code


Looking at the Source CodeThe 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 inclasses and adds member functions. There's a lot going on in the CPP application, so this discussion focuses on the code requiredto get a video stream from a camera and display it. Here, the CPP program:

1. Connects to a VideoXpert system2. 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 ProgramStart with main(), located in the file main.cpp. The application first creates an instance of the CPPConsole::System class. Aconnection is automatically initiated to the system using credentials from the application's Constants.h file. After successfullylogging 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 SystemOpen the System.cpp file and locate the CPPConsole::System::Login method. This is the first step in a Pelco VideoXpertSDK 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;




if ( _system != nullptr ) return true; else return false;}

Getting the Device ListThe following method fetches the collection of devices from the System object. This method provides a good example ofhow the application classes access the returned structures and create local copies. The remote device collection (of typeVxSdk::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 validationof 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 StreamsIn main.cpp, the DoLiveStreamingOption method provides a more complex example of how to use the properties of a camerato find a video stream. A camera contains data sources (streams), each of which uses a specific data interface protocol (MJPEG orRTP/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 sourcesand data interfaces for the camera until it finds a match for the protocol selected by the user. Note that the method fails silently if amatch is not found.

void DoLiveStreamingOption( list<CPPConsole::Device*>* devices ){ int camNum;



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 (Y/N) [Default is RTSP]: "; cin >> mJPEGOption; if ( mJPEGOption == "Y" || 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 ); }}




Start a Video StreamThe StartStreamingForDataSource method in main.cpp initiates streaming for either the MJPEG or RTP stream. It usesthird-party libraries to create and display the stream. If the camera supports Pan-Tilt-Zoom (PTZ), the available PTZ commands arelisted in the console window. The user can enter a PTZ command in the console and see the result in the stream window.

Overview of the Pelco VideoXpert SDK


Overview of the Pelco VideoXpert SDKThe Pelco VideoXpert SDK contains a number of libraries and header files that represent pieces of a Pelco video managementsystem. 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 asfollows:

Prefix Description Example

IVx Interface for an object passed fromVideoXpert to the client application.

IVxDevice

Vx "Plain old data" types created in the clientapplication.

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.1The list below introduces the Pelco VideoXpert SDK header files and their contents. This list is not exhaustive. Refer to the SDKreference documentation for more details, such as enumerated type values.

Header Filename (.h) Description

IVxBookmark Represents a point in time of interest with reference to aparticular data source.

IVxClip Represents a contiguous duration of stored media originatingfrom a single DataSource.

IVxDataInterface Represents an interface to a data source.

IVxDataObject Represents a custom serialized data object submitted by aclient and stored on the server. The data is completely opaqueto the server and other types of clients.

IVxDataSession Represents a data session that is being transmitted by a datasource, 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 providea particular protocol used to transmit and control the dataproduced by this DataSource.

IVxDevice Represents a particular physical device in the system.

IVxDeviceAssignment Represents a device assignment on a data storage. It canalso specify the driver to use to communicate with the physicaldevice.

IVxDriver Represents a device communication driver.

IVxEvent Represents an instance of a particular situation that hasoccurred.

IVxExport Represents an exported data set that is archived within thesystem.

IVxExportClip Represents an individual range of media data belonging toan Export. This data shall be exported when the Export istriggered.

IVxPattern Represents a predefined sequence of movement that a PTZdevice can perform when triggered. A running pattern will behalted upon any other PTZ request.





IVxPreset Represents a predefined point that a PTZ device can PTZ towhen triggered.

IVxPrivilege Represents a specific permission that is given to a role.

IVxPtzController Represents a controller for a device that has pan, tilt, and/orzoom functionality.

IVxPtzLock Represents a lock for a ptz controller.

IVxRole Represents a collection of permissions which can be assignedto a user.

IVxSchedule Represents a recording schedule. A schedule is a group of 0or more resources associated with a set of time and/or eventbased schedule triggers that, when any are active, cause thescheduled action to be performed.

IVxScheduleTrigger Represents a schedule trigger. A schedule trigger is a timerange and an optional event that together act as a trigger toactivate a schedule and cause it to perform its configuredaction.

IVxSituation Represents a particular situation configuration that specifieshow corresponding events shall be generated and handledwhen the situation is detected.

IVxSystem Represents a VideoXpert system and allows the user tomanage the system and devices.

IVxTag Represents a non-hierarchical identifier typically associated withone or more resources (i.e. device or data source). A tag helpsto 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 VideoXpertsystem.

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 VideoXpertsystem.

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. Theevent will be generated based upon the NewEvent data, itsSituation 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 aVxNewExport.

VxNewPrivilege Represents a new privilege to be created.

VxNewSchedule Represents a new schedule to be created. A schedule is agroup 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.




VxNewScheduleTrigger Represents a new schedule trigger to be created. A scheduletrigger is a time range and an optional event that together actas a trigger to activate a schedule and cause it to perform itsconfigured action.

VxNewSituation Represents a new situation configuration that specifies howcorresponding events shall be generated and handled when thesituation 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 by Schneider Electric3500 Pelco Way Clovis, California 93612-5699 USA(800) 289-9100 Tel (800) 289-9150 Fax+1 (559) 292-1981 International Tel+1 (559) 348-1120 International Faxwww.pelco.com © 2016 Schneider Electric. All Rights Reserved. All trademarks are owned by Schneider Electric IndustriesSAS or its affiliated companies. www.schneider-electric.com


Pelco VideoXpert SDK 1.1 Quick Start...

Documents

Transcript of Pelco VideoXpert SDK 1.1 Quick Start...