Beruflich Dokumente
Kultur Dokumente
2 Programming Guide
C5617M-A
C5617M-A
C5617M-A | Contents
Contents
Chapter 1: Introduction...............................................................................7
Getting Started with the Pelco SDK.....................................................................................................................7
General Requirements.......................................................................................................................................... 8
Installing the Pelco SDK.......................................................................................................................................9
System Environment Settings for the Pelco SDK..............................................................................................10
Including Required SDK Components For Your Application..............................................................................10
Setting Up Sample Projects............................................................................................................................... 10
Registering the ActiveX Control............................................................................................................. 10
Setting Up the Working Directory...........................................................................................................11
Adding References to Managed Libraries for C#...................................................................................14
Contents | C5617M-A
C5617M-A | Contents
Chapter 8: Discovery................................................................................ 77
Device and Service Discovery Overview........................................................................................................... 77
Initializing the Pelco SDK System Manager Wrapper........................................................................................78
Automatically Determining the System Managers IP Address and Port Number..............................................79
Logging In and Logging Out.............................................................................................................................. 79
Querying Available Devices from the System Manager.................................................................................... 80
Retrieving the System Managers Time Zone........................................................................................81
Retrieving the Network Time Server Address........................................................................................81
Retrieving a Web Services ID............................................................................................................... 82
Retrieving a Specific Web Services Control URL................................................................................. 82
Retrieving the NVR Associated with the Device.................................................................................... 83
Retrieving the Devices Friendly Name.................................................................................................. 84
Retrieving the Devices Device Description File (DDF) URL................................................................. 84
Retrieving All Web Services Available on a Device...............................................................................85
Retrieving Device Attributes............................................................................................................................... 85
Retrieving a System Managers Attribute...............................................................................................87
Retrieving a Web Services Attribute..................................................................................................... 88
Creating an IDeviceStorage Class..................................................................................................................... 88
Appendix A: Logging................................................................................ 91
Appendix B: Product Compatibility.........................................................93
Appendix C: Endura..................................................................................95
Appendix D: General Event Messages................................................... 99
Appendix E: Hardware Diagnostics Event Messsages........................101
ConfigurationButton (20180)............................................................................................................................. 101
DriverFailure (20150)........................................................................................................................................ 102
Fans (20020).....................................................................................................................................................103
HardDrives (20060)........................................................................................................................................... 104
ImproperShutdown (20070)...............................................................................................................................106
LinkSpeed (20200)............................................................................................................................................ 107
PowerSupply (20120)........................................................................................................................................108
UPS (20170)..................................................................................................................................................... 109
Contents | C5617M-A
Appendix G: Glossary.............................................................................119
Chapter
1
Introduction
Getting Started with the Pelco SDK
The Pelco SDK is a powerful software developer kit to help third parties use Pelco products alongside non-Pelco
products and software. While the Pelco API is both flexible and powerful, it can also potentially overwhelm some
users; of course, developers are still free to directly use the Pelco API as they wish. However, Pelco has found that
many of our customers enjoy the convenience and ease of use that the Pelco SDK provides. The Pelco SDK provides
programmers ease of use with the following functionality:
Video rendering
Device and service discovery
User and role management
Pan, tilt, and zoom (PTZ) control
Eventing support
Video export
Audio and video meta-data parsing
Features / Functionality
Device discovery
Service discovery
Display and control MPEG-4 and H.264 streams from Pelco cameras
and DVRs / NVRs / NSMs.
Control Pan/Tilt/Zoom on Pelco PTZ-enabled cameras.
1
2
PelcoGsoap is not a separately installable library, but it is included in the other components as required.
EventArbiter component also contains Event Manager. Therefore, Event Manager is not a separately installable
component.
C5617M-A | Introduction
Exporter
Export video streams into a variety of popular video formats: AVI, 3GP,
or PEF
Overlay data on exported video
The Pelco SDK also contains sample projects for the following:
Code Sample
Default Location
C:\Program Files\Pelco\API\SampleCode\EventArbiterSample
C:\Program Files\Pelco\API\SampleCode\EventArbiterSample
Exporter Sample
C:\Program Files\Pelco\API\SampleCode\ExporterSample
MetaDataParser Sample
C:\Program Files\Pelco\API\SampleCode\MetaDataParserSample
C:\Program Files\Pelco\API\SampleCode\PelcoAPIViewerSample
C:\Program Files\Pelco\API\SampleCode
\PTZControlWrapperSample
C:\Program Files\Pelco\API\SampleCode
\SystemManagerWrapperSample
General Requirements
Hardware
The minimum hardware requirements for the client machine to use for completing the steps outlined in this document
are the following:
In addition to your client machine, a Pelco SDK compatible Pelco device is required. A list of currently compatible
Pelco hardware can be found in the Appendix.
Software
The software requirements for completing the steps outlined in this document are the following:
Windows XP, Windows Vista [32 bit / 64 bit], Windows Server 2003 [32 bit / 64 bit], Windows Server 2008 [32 bit /
64 bit], Windows 7 [32 bit / 64 bit]
C5617M-A | Introduction
DirectX 9.0 c (must be installed separately, even if your system already includes DirectX 10 or 11 as part of
Windows Vista or higher)
Visual Studio 2008
Microsoft .NET Framework 3.5
NOTE: Improper use of audio/visual recording equipment may subject you to civil and criminal penalties.
Applicable laws regarding the use of such capabilities vary between jurisdictions and may require, among
other things, express written consent from the recorded subjects. You are solely responsible for insuring strict
compliance with such laws and for strict adherence to any/all rights of privacy and personalty.
Description
C:\Program Files\Pelco\API\Include
3
\C++\PelcoAPI
Header files for all of the Pelco SDK related classes can be found
here.
C:\Program Files\Pelco\API\Libs
3
\Release
C:\Program Files\Pelco\API\Libs
3
\Debug
Pelco SDK debug module libraries can be found within the Debug
directory.
C:\Program Files\Pelco\API\Libs
3
\Release\Plugins
C:\Program Files\Pelco\API
3
\SampleCode
C:\Program Files\Pelco\API
3
\WebServices
The WSDLs files for web services are in this directory. Please note
that the XSDs are embedded within the WSDL files themselves.
Our WSDLs, along with the embedded XSDs, provide the definition
for Pelco web services and related data types. For details, please
refer to the following links:
http://www.w3.org/TR/wsdl20/
http://www.w3.org/XML/Schema.html
C:\Program Files\Pelco\API\Logging
NOTE:
Each Pelco SDK component may have additional installation and / or configuration requirements.
C5617M-A | Introduction
EVEREST_BIN - the location of all the binaries. By default, this is set to C:\Program Files\Pelco\API\Libs
EVEREST_ROOT - Location of all the Pelco header files. By default this is set to C:\Program Files\Pelco
\API\Include\C++
PATH - This initially points to the C:\Program Files\Pelco\API\Libs\Debug folder
NOTE: If you want to build the SDK in release mode, you must change the PATH variable to point to the
Release directory (e.g., C:\Program Files\Pelco\API\Libs\Release). If any of the paths have been
changed from the defaults, you will be responsible for removing the path if the SDK is uninstalled.
10
C5617M-A | Introduction
11
C5617M-A | Introduction
C# Example
Now click on the Debugging menu item on the left navigation of the sample projects property page window.
12
C5617M-A | Introduction
13
C5617M-A | Introduction
Depending on whether you would like to use the release version of the Pelco SDK libraries or the debug version,
change the Working Directory value as appropriate. If you kept the default installation directory for the Pelco SDK,
use C:\\Program Files\Pelco\API\Libs\Release to use the production version of the Pelco SDK libraries.
Conversely, use C:\\Program Files\Pelco\API\Libs\Debug to use the debug version of the Pelco SDK
libraries.
On a 64 bit machine, set the Platform target to support x86.
NOTE: Be sure to set the character set to "Use Multi-Byte Character Set" under the project properties for the
sample code to compile properly.
A dialog window should now appear. Click on the Browse tab. Assuming the default installation directory was not
changed, users should be able to find the managed DLL file within the directory C:\Program Files\Pelco\API
\Libs\Debug. Now select the managed DLL file and click on the Ok button.
14
C5617M-A | Introduction
NOTE: These references may already appear in the project, possibly with yellow exclamation marks. ("!") In
general, these Pelco library references should still be deleted and re-added, after installing or reinstalling the
SDK.
Now that youve added the managed DLL reference to the project, we need to add the managed Pelco API MPF
Viewer.
To add the managed Pelco API MPF Viewer, follow the same steps as before for the managed DLL.
A dialog window should now appear. Click on the Browse tab. Assuming the default installation directory was not
changed, users should be able to find the PelcoAPIMPFViewer.dll file within the directory C:\Program Files
\Pelco\API\Libs\Debug. Now select the PelcoAPIMPFViewer.dll file and click on the Ok button.
You should now see both the managed ManagedPTZControlWrapper reference and the PelcoAPIMPFViewer
reference within the project. At this point you should be able to run the Pelco API Viewer sample C# project.
15
C5617M-A | Introduction
NOTE: With the PelcoAPICOMViewer.ocx control, you may need to clean and rebuild this project several
times before the OCX control will work. This is apparently a Visual Studio / OCX limitation.
16
Chapter
2
Displaying and Controlling Video Streams
Overview
The most important thing in any security imaging system, is for the security operator to see what images his IP
cameras are capturing. Consequently displaying a video stream and controlling its playback is most likely what you will
need to get working first.
Where Does the Pelco SDK Fit?
To display and control video streams, use the Pelco API Viewer. The Pelco API Viewer is an easy to use Windows
based tool for viewing MPEG-4 and H.264 streams from Pelco IP cameras and DVRs / NVRs / NSMs. It provides a
Pelco supported player for integrating Pelco devices with 3rd party applications. This player can be configured to work
in both RTP and RTSP mode. In RTP mode, the player uses one of several Pelco API methods to initiate and control
streams. While in RTSP mode, the player expects to work with either devices, such as a Sarix IP camera, where RTSP
is supported by default; or software solutions like the RTSP Server.
The Pelco API Viewer can be used in three ways:
1. C++
2. C#
3. OCX (ActiveX Control)
Support is provided for viewing both MPEG-4 and H.264 streams, but changing a video configuration from one format
to the other causes the video to stop streaming.
Whats Ahead
There are two major tasks for viewing a video stream using the Pelco API Viewer:
17
The plug-in directory contains components that are key to the SDKs encoding, decoding, and transcoding
capabilities. Without a proper reference, key features of the Pelco SDK may not function properly. Please note that
the plug-in directory is dependent on where you installed the Pelco SDK.
NOTE: The related source code for this entry can be found in main.cpps main function, which resides in
the PelcoAPIViewer sample project.
_pViewer.SetPluginDir("C:\\Program Files\\Pelco\\API\\Libs\\Debug\\Plugins\\");
3. Create a new window handle and associate it to the Pelco API Viewer instance.
Please note that logic to create the window handle can be found in the _DbgCreateParentWindow method.
HWND _hWndParent = NULL;
//... Logic to create a window and display it. Refer to _DbgCreateParentWindow ...
m_pViewer->SetWindowHandle((_hWnd ? _hWnd : this->m_hWnd));
18
try
{
_pViewer.SetPluginDir(_txtFolder.Text);
_pViewer.SetupStream(_txtIP.Text, _txtPort.Text,
_txtServiceId.Text,_txtTransport.Text);
}
catch (Exception /*ex*/) { }
}
19
The last number of the web service endpoint URL of a camera. For example, when an endpoint URL
ends with VideoOutput-4 then 4 is the service ID.
szCamUuid
The IP cameras UPnP Unique Device Name (UDN)
NOTE: The IP cameras UDN is required if you want to start manual recording on a
live stream. Otherwise, this parameter is optional.
bLowBandwidth
The flag to start a low bandwidth stream. Live only
pStreamInfo
Streaming data to be filled in. This value can be passed back to live or playback StartStream call
in RTP only.
20
The NVRs ID (optional for a live RTP stream. Required for manual recording of a live RTP stream
and for a playback RTP stream)
ITimeStampDelegate
Signals if you want the timestamp returned by the API. If no timestamp is required, do not supply a
value for this parameter.
bVideoOnly
Stream video without audio. By default, this parameter is set to FALSE for backwards compatibility.
bLowBandwidth
Sets the stream to low bandwidth stream from camera. The camera needs to be configured or have
secondary low bandwidth stream enabled. This parameter is set to FALSE by default for backwards
compatibility.
NOTE: This parameter is only valid for live streams.
StreamInfo
If you have already queried the NSM/Camera using the VideoQuery method then you can pass the
stream information back into the StartStream call with this parameter. This parameter is set to NULL
by default for backwards compatibility.
For a live RTP stream:
MyAppNamespace::TimeStamp _pDelegate;
const char* pszSesId = NULL;
//... Other logic ...
pszSesId = _pViewer.StartStream(const char* StartTime, const *endTime,
"10.220.196.149", "49154", "1", "rtp://10.220.196.148:7162",
"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", "1", &_pDelegate, False, False,
NULL);
where:
StartTime is the time you want to start video. For live streams, use the value as "NOW",
endTime is the time you want the video to end. For live streams, use the value INFINITE.
NOTE: For NULL/optional values, use for strings and NULL for interface values.
If successful, these methods will return a session ID, pszSesId, of the stream. This will be used throughout this
document for tasks related to the Pelco API Viewer.
21
2. Start the video stream to display, by calling the StartStream method, passing in the following parameters:
The location of the RTSP stream
The username to use for authentication (Optional)
The password to use for authentication (Optional)
A boolean indicating whether or not the stream is multicast
The timestamp parameter is an object that implements the ITimeStampDelegate interface, or NULL if
you dont want to receive timestamps as the video plays. (Optional)
MyAppNamespace::TimeStamp _pDelegate;
const char* pszSesId = NULL;
//... Other logic e.g. setting up windows, and so on ...
//Live example:
pszSesId = _pViewer.StartStream(
"rtsp://10.220.196.169/?deviceid=uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15",
NULL, NULL,
false, &_pDelegate);
//Playback example:
pszSesId = _pViewer.StartStream(
"rtsp://10.221.224.35/?deviceid=uuid:01b766f9-9d87-4613a168-5e5d179d339d&starttime=2011-12-04T10:00:00&endtime=2011-12-04T11:00:00",
NULL, NULL,
false, &_pDelegate);
If successful, the method will return a session ID of the stream. Keep this in mind, as this will be used throughout
for tasks related to the Pelco API Viewer.
22
This entry assumes that you have already completed the steps outlined in the Opening, Playing, and Displaying an
RTSP Stream entry.
To pause currently running video stream, call the Pelco API Viewer instances Pause method; passing in the target
video streams session ID.
const char* pszSesId = NULL;
//... Get pszSesId, the streams session ID, by starting a stream ...
if(_pViewer.Pause(pszSesId) !=0 ){
//... Handle error ...
}
23
24
To perform a stop playback of a currently running video stream, call the Pelco API Viewer instances StopStream
method; passing in the target video streams session ID.
const char* pszSesId = NULL;
//... Get pszSesId, the streams session ID, by starting a stream ...
if(_pViewer.StopStream(pszSesId) !=0 ){
//... Handle error ...
}
25
C++ Example:
PelcoAPI::ViewerOverlayInfo overlay;
PelcoAPI::COLOR fontColor = {0xFF, 0xFF, 0xFF, 0xA0};
PelcoAPI::COLOR fontBgColor = {0x00, 0x00, 0x00, 0x00};
overlay.m_dateFormat = PelcoAPI::VIEWER_DATE_FORMAT_MMDDYY;
overlay.m_timeFormat = PelcoAPI::VIEWER_TIME_FORMAT_TTHHMMSS;
overlay.m_fontColor = fontColor;
overlay.m_fontBgColor = fontBgColor;
overlay.m_location = PelcoAPI::VIEWER_OVERLAY_LOCATION_TOP_LEFT;
overlay.m_nFontSize = 12;
overlay.m_fontNameStr = "Arial";
bool bSuccess = _pViewer.DisplayTimestampOverlay(pszSesId, true, &overlay);
C# Example:
System.Drawing.Color fontColor = System.Drawing.Color.FromArgb(0xFF, 0xFF, 0xFF,
0xA0);
System.Drawing.Color fontBgColor = System.Drawing.Color.FromArgb(0x00, 0x00, 0x00,
0x00);
ViewerOverlayInfoNet overlay = new ViewerOverlayInfoNet();
overlay.m_location =
PelcoAPI.ViewerOverlayLocationNet.OVERLAY_LOCATION_BOTTOM_LEFT;
overlay.m_dateFormat = PelcoAPI.ViewerDateFormatNet.DATE_FORMAT_MMDDYYYY;
overlay.m_timeFormat = PelcoAPI.ViewerTimeFormatNet.TIME_FORMAT_HHMMSSTT;
overlay.m_fontNameStr = "Arial";
overlay.m_nFontSize = 16;
overlay.m_fontColor = fontColor;
overlay.m_fontBgColor = fontBgColor;
Boolean bSuccess = _rtpViewer.DisplayTimestampOverlay(_rtpSessionId, true,
overlay);
NOTE: Live and playback RTSP streams from Sarix cameras are unable to display timestamp information.
26
Taking a Snapshot of the Current Video Frame for RTP and RTSP Streams
To take a snapshot of the current video frame, call the Pelco API Viewer instances TakeSnapShot method;
passing in the target video streams session ID, and the desired resulting filename and file path.
const char* pszSesId = NULL;
//... Get pszSesId, the streams session ID, by starting a stream ...
nResult = m_pViewer->TakeSnapShot(szSessionId, "C:\\snapshots.jpg");
Pan, Tilt, Zoom (PTZ) Control for RTP Stream Using PelcoAPIViewer
Cameras with PTZ functionality can also be controlled using the PelcoAPIViewer. For more information, see Pan, Tilt,
Zoom (PTZ) Control.
NOTE: This only works with PelcoAPIViewer in RTP Live mode.
27
28
Chapter
3
Pan, Tilt, Zoom (PTZ) Control
Overview
WARNING: Any provided sample code is meant to be a reference implementation focused on educating
developers about Pelco devices. Though there are exceptions, in general Pelco sample code is NOT intended
for immediate production use without modification.
WARNING: The content below assumes that the default target installation directory was chosen during
installation.
For the latest Pelco documentation, visit http://pdn.pelco.com.
After youve found the IP camera on your network and displayed its live stream on your display, you will probably want
to start controlling your cameras viewing position: up and down and left and right, as well as magnification (zoom),
focus, and camera iris.
The StopContinuous method is available to stop the camera from continually moving, and the Stop() call is
available to stop Lens control (zoom, iris, and focus) actions. To stop continuous positioning calls, pass in a 0 value.
For example, after executing ContinuousMove, call ContinuousMove(0, 0) to stop moving.
Where Does the Pelco SDK Fit?
To move your IP cameras current view, you need to start using the Pelco SDKs PTZ Control Wrapper. The PTZ
Control Wrapper is an easy to use tool for controlling various PTZ and lens related functionality. For this section well
only focus on panning and tilting the camera.
As in the previous section well be examining the sample project code. Specifically, this section covers the PTZ Control
Wrapper. This sample project exhibits PTZ Control Wrapper functionality.
NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methods
described in this topic, there is an equivalent method in the PelcoAPIViewer API.
29
C++ Example
PelcoAPI::PTZControlWrapper ptzControlWrapper("10.220.196.144, 49152, 1);
After you are finished, stop all PTZ Control Wrapper actions:
bool bSuccess = ptzControlWrapper.Stop();
NOTE: The following stop actions are available:
To stop Lens control actions such as zoom, iris, and focus, use the Stop() call.
To stop continuous movement triggered by ContinuousMove, ContinuousPan, and ContinuousTilt,
use the StopContinuous() call.
C# Example
ManagedPTZControlWrapperNet managedPTZControl = new
ManagedPTZControlWrapperNet("10.220.196.144, 49152, 1);
After you are finished, stop all PTZ Control Wrapper actions:
Boolean bSuccess = managedPTZControl.Stop();
NOTE: The following stop actions are available:
To stop Lens control actions such as zoom, iris, and focus, use the Stop() call.
To stop continuous movement triggered by ContinuousMove, ContinuousPan, and ContinuousTilt,
use the StopContinuous() call.
Continuous Panning
NOTE: The related source code for this entry can be found in main.cpps main function (for C++) or
Program.css Main function (for C#), which belongs to the PTZ Control Wrapper sample project.
NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methods
described in this topic, there is an equivalent method in the PelcoAPIViewer API.
This entry covers the portion of the sample project that deals with moving the camera left and right.
1. Initialize the PTZ Control Wrapper.
Refer to Initializing the PTZ Control Wrapper for details.
2. Call the PTZ Control Wrapper instances ContinuousPan method.
For more details on the ContinuousPan method, please refer to the PTZ Control Wrapper API reference
documentation.
C++ Example:
//panning left
bool bSuccess = ptzControlWrapper.ContinuousPan(-10000);
//panning right
bool bSuccess = ptzControlWrapper.ContinuousPan(10000);
C# Example:
//panning left
Boolean bSuccess = managedPTZControl.ContinuousPan(-10000);
//panning right
Boolean bSuccess = managedPTZControl.ContinuousPan(10000);
30
3. When you want to stop the camera from continually moving, use the StopContinuous() method (refer to
Continuous Stop for details), or pass in a 0 value to the ContinuousPan method as shown in the following
example.
C++ Example:
bool bSuccess = ptzControlWrapper.ContinuousPan(0);
C# Example:
Boolean bSuccess = managedPTZControl.ContinuousPan(0);
Continuous Tilting
NOTE: The related source code for this entry can be found in main.cpps main function (for C++) or
Program.css Main function (for C#), which belongs to the PTZ Control Wrapper C++ sample project.
NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methods
described in this topic, there is an equivalent method in the PelcoAPIViewer API.
This entry covers the portion of the sample project that deals with moving the camera up and down.
1. Initialize the PTZ Control Wrapper.
Refer to Initializing the PTZ Control Wrapper for details.
2. Call the PTZ Control Wrapper instances ContinuousTilt method.
To tilt the IP camera down, pass in a negative rotational y value for the second parameter.
To tilt the IP camera up, pass in a positive value for the rotational y parameter. Disregard the last four
parameters.
For more details on the ContinuousTilt method, please refer to the PTZ Control Wrapper API reference
documentation.
C++ Example:
//tilting down
bool bSuccess = ptzControlWrapper.ContinuousTilt(-9000);
//tilting up
bool bSuccess = ptzControlWrapper.ContinuousTilt(9000);
C# Example:
//tilting down
Boolean bSuccess = managedPTZControl.ContinuousTilt(-9000);
//tilting up
Boolean bSuccess = managedPTZControl.ContinuousTilt(9000);
3. When you want to stop the camera from continually moving, use the StopContinuous() method (refer to
Continuous Stop for details), or pass in a 0 value to the ContinuousTilt method as shown in the following
example.
C++ Example:
bool bSuccess = ptzControlWrapper.ContinuousTilt(0);
C# Example:
Boolean bSuccess = managedPTZControl.ContinuousTilt(0);
31
NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methods
described in this topic, there is an equivalent method in the PelcoAPIViewer API.
This entry covers the portion of the sample project that deals with continuously moving the camera in a diagonal
manner.
1. Initialize the PTZ Control Wrapper.
Refer to Initializing the PTZ Control Wrapper for details.
2. Call the ContinuousMove method.
The first parameter represents both speed and direction on the X plane. Use a negative integer to pan left and a
positive integer to pan right. The second parameter represents both speed and direction on the Y plane. Use a
negative integer to tilt down and a positive integer to tilt up. For more details on the ContinuousMove method,
pplease refer to the PTZ Control Wrapper API reference documentation.
C++ Example:
//tilting down
bool bSuccess = ptzControlWrapper.ContinuousMove(10000, -10000);
//tilting up
bool bSuccess = ptzControlWrapper.ContinuousMove(10000, 10000);
C# Example:
//tilting down
Boolean bSuccess = managedPTZControl.ContinuousMove(10000, -10000);
//tilting up
Boolean bSuccess = managedPTZControl.ContinuousMove(10000, 10000);
3. When you want to stop the camera from continually moving, use the StopContinuous() method (refer to
Continuous Stop for details), or pass in a 0 value to the ContinuousMove method as shown in the following
example.
C++ Example:
bool bSuccess = ptzControlWrapper.ContinuousMove(0,0);
C# Example:
Boolean bSuccess = managedPTZControl.ContinuousMove(0,0);
32
C# Example:
Boolean bSuccess = managedPTZControl.SetLowLatencyMode(true);
Zoom API calls over UDP currently work on Sarix firmware 1.7.41.
For more details on the AbsolutePan method, please refer to the PTZ Control Wrapper API reference
documentation.
Generally, the panning range is limited to 0 to 360 degrees (0 to 36,000 centidegrees). This limit might differ,
depending on the type of camera used.
C++ Example:
bool bSuccess = ptzControlWrapper.AbsolutePan(36000);
C# Example:
Boolean bSuccess = managedPTZControl.AbsolutePan(36000);
For more details on the AbsoluteTilt method, refer to the PTZ Control Wrapper API reference documentation.
Generally, the tilting range is limited to 0 to -90 degrees (0 to -9000 centidegrees). This limit might differ, depending
on the type of camera used.
C++ Example:
bool bSuccess = ptzControlWrapper.AbsoluteTilt(-9000);
33
C# Example:
Boolean bSuccess = managedPTZControl.AbsoluteTilt(-9000);
Passing a negative value for X moves the camera left of the home position.
Passing a positive value for X moves the camera right of the home position.
Passing a negative value for Y moves the camera down from horizontal.
Passing a positive value for Y moves the camera up from horizontal.
Refer to your camera models specifications for tilt position limits. For more details on the AbsoluteMove method,
please refer to the PTZ Control Wrapper API reference documentation.
C++ Example:
bool bSuccess = ptzControlWrapper.AbsoluteMove(20, 40);
C# Example:
Boolean bSuccess = managedPTZControl.AbsoluteMove(20, 40);
34
For more details on the GetAbsolutePosition method, please refer to the PTZ Control Wrapper API reference
documentation.
C++ Example:
int positionX = 0;
int positionY = 0;
bool bSuccess = ptzControlWrapper.GetAbsolutePosition(&positionX, &positionY);
C# Example:
int positionX = 0;
int positionY = 0;
Boolean bSuccess = managedPTZControl.GetAbsolutePosition(ref positionX,
ref positionY);
35
Iris Control
NOTE: The related source code for this entry can be found in main.cpps main function (for C++) or
Program.css Main function (for C#), which belongs to the PTZ Control Wrapper sample project.
NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methods
described in this topic, there is an equivalent method in the PelcoAPIViewer API.
NOTE: We recommend that you let your IP camera manage its iris automatically.
36
This section demonstrates how to open and close your cameras iris.
1. Initialize the PTZ Control Wrapper.
Refer to Initializing the PTZ Control Wrapper for details.
2. Call the SetIris method, passing in the desired iris command.
For a little background, the SetIris method takes only following values:
0
To stop all iris related operations.
1
To start closing the iris.
2
To start opening the iris.
If the request was successful, your cameras iris should now be changing (unless you passed a 0). This will not
stop until the SetIris request is made with a different value, or if you call the Stop method, which will stop
movement or lens related action the camera is currently doing.
C++ Example:
bool bSuccess = ptzControlWrapper.SetIris(1);
bool bSuccess = ptzControlWrapper.SetIris(2);
C# Example:
Boolean bSuccess = managedPTZControl.Iris(1);
Boolean bSuccess = managedPTZControl.Iris(2);
3. Alternatively the recommended way of controlling the iris is to let your IP camera manage it automatically. To
enable this feature, call the AutoIris method and pass a boolean value of true. To disable it, just pass a boolean
value of false.
C++ Example:
bool bSuccess = ptzControlWrapper.AutoIris(true)
C# Example:
Boolean bSuccess = managedPTZControl.AutoIris(true)
Scripting
One of Pelcos most powerful features enables users to manage and run scripts. Scripts allow you to extend the
behavior of Pelco devices with little effort. Before we show you how to use the SDKs scripting related features, its
important to know about the different types of Pelco scripts:
Preset
A preset is a script that allows you to save a camera's stationary position, zoom, and other settings such as auto-iris
and auto-focus, collectively known as a bookmark. Users can save multiple presets per camera. For example if youre
monitoring several specific points using the same camera, you can set one preset for each location that needs to be
monitored; each with its own set of zoom, iris, and focus values.
Presets that you create must be names, such as PRESETX, where the keyword PRESET must be used (uppercase)
followed by a positive integer. For example, PRESET9.
The number of presets that can be saved and activated is dependent on the Pelco device.
Pattern
A pattern is like a group of presets combined. For example, you might control an IP PTZ camera guarding a hallway
with two entrances and a window. With patterns, you can set a bookmark for camera behavior that changes the
cameras view from one of the three points of interest to another every 15 seconds.
37
Patterns that you create must be names as PATTERNX, where the keyword PATTERN must be used (uppercase)
followed by a positive integer. For example, PATTERN5.
NOTE: There are pre-configured patterns that cannot be created. You cannot create a Pattern by combining
existing Presets.
Like a preset, patterns are typically only relevant for IP cameras. The number of patterns that can be recorded and
activated is dependent on the Pelco device. For example, the 16X and 18X models of the Spectra IV can store only a
single pattern, while the 22X, 23X and 35X Spectra IV models can store up to eight patterns.
Normal Script
A general script consists of a group of commands that run over a set period of time. It is akin to a macro.
Creating a Preset
NOTE: The related source code for this entry can be found in main.cpps main function (for C++) or
Program.css Main function (for C#), which belongs to the PTZ Control Wrapper sample project.
NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methods
described in this topic, there is an equivalent method in the PelcoAPIViewer API.
These steps will show you how to create a preset.
1. Initialize the PTZ Control Wrapper.
Refer to Initializing the PTZ Control Wrapper for details.
2. Now set up your Pelco IP camera with a combination of settings that you want to save.
For example, the IP cameras current viewing position, iris setting, focus setting, zoom, and so on.
3. Then call the SetPreset method, passing in the desired name of the preset.
Depending on whether the preset already exists or not, it will either create a new one or modify an existing one by
that name.
C++ Example:
bool bSuccess = ptzControlWrapper.SetPreset("PRESET99");
C# Example:
Boolean bSuccess = managedPTZControl.SetPreset("PRESET99");
Creating a Pattern
NOTE: The related source code for this entry can be found in main.cpps main function (for C++) or
Program.css Main function (for C#), which belongs to the PTZ Control Wrapper sample project.
NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methods
described in this topic, there is an equivalent method in the PelcoAPIViewer API.
This is just like creating a preset, except you will be saving more than one camera state.
1. Initialize the PTZ Control Wrapper.
Refer to Initializing the PTZ Control Wrapper for details.
2. Now set up your Pelco IP camera with a combination of settings that you want to save.
For example, the IP cameras current viewing position, iris setting, focus setting, zoom, and so on.
3. Then call the StartPatternRecording method, passing in the desired name of the preset.
38
Depending on whether the pattern already exists or not, it will either create a new one or modify an existing one by
that name.
C++ Example:
bool bSuccess = ptzControlWrapper.StartPatternRecording("PATTERN99");
C# Example:
Boolean bSuccess = managedPTZControl.StartPatternRecording("PATTERN99");
4. At this point start performing the actions that youd want your camera to remember as a pattern.
For example, if you have three points of interest you would first go to the first point of interest with a certain zoom
and focus level. After waiting for some predetermined time, you then move the cameras view into the second point
of interest which has a different zoom level and iris setting; and do the same for the final point of interest.
5. Finally, call the EndPatternRecording method, passing in the same pattern name as you did before.
C++ Example:
bool bSuccess = ptzControlWrapper.EndPatternRecording("PATTERN99");
C# Example:
Boolean bSuccess = managedPTZControl.EndPatternRecording("PATTERN99");
39
C# Example:
Boolean bSuccess = managedPTZControl.RemovePreset("PRESET99");
40
Chapter
4
Events and Alarms
Overview
WARNING: Any provided sample code is meant to be a reference implementation focused on educating
developers about Pelco devices. Though there are exceptions, in general Pelco sample code is NOT intended
for immediate production use without modification.
WARNING: The content in this section assumes that the default target installation directory was chosen
during installation.
NOTE: For the latest Pelco documentation, visit http://pdn.pelco.com.
For a list of the latest special issues and problems regarding the Event Arbiter library, visit http://pdn.pelco.com/
content/event-arbiter-library-issues.
For a list of the latest special issues and problems regarding the Event Manager, visit http://pdn.pelco.com/content/
event-manager-issues.
Events and alarms are essentially XML formatted messages triggered by Pelco products, when some particular criteria
is met. Specifically Pelco products, acting as event providers, send these events and alarms to their subscribers.
Typically event providers are web services, while subscribers are software clients. For example, if an IP cameras
MotionDetection service detected movement within a particular region in the video frame, it can send an event to all of
its subscribers such as a VMS.
41
Arbiter Library now also handles subscription renewals automatically. You will no longer have to worry about renewing
an event subscription.
Environment
No System Manager
Event Manager
The Event Manager represents a new tool for eventing and a new component within the Pelco SDK. The Event
Manager provides another abstraction on top of the Event Arbiter Library, and simplifies event operations even
further. It allows subscriptions to all available web services for all devices on a given network that fall under a specific
category. To subscribe, all you have to provide is the event category. The categories are as follows:
No System Manager
Event Manager
42
Whats Ahead
This is a high level overview of what steps are needed for handling events.
1. Subscribe to the desired web service's events through the Event Arbiter Library or the Event Manager.
2. Create the method that will handle the event. Associate that method with the Event Arbiter Library instances event
handler. Wait for an event to occur (or trigger an event to test), then handle it.
3. When no longer interested in receiving events (or when finished testing), unsubscribe from the subscribed web
service.
Details of implementation are left to the user. However in the MyEventAgent sample class, we demonstrate basic
functionality for accessing event related data.
C++ Example:
#ifndef MYEVENTAGENT_H
#define MYEVENTAGENT_H
#include "PelcoAPI/IEventAgent.h"
using namespace PelcoAPI;
class MyEventAgent : public IEventAgent
{
public:
STDCALL MyEventAgent();
virtual STDCALL ~MyEventAgent();
void STDCALL NotifyEvent(const char * szResponse, const Event *
pEvent);
private:
int m_nCounter;
};
#endif
C# Example:
class MyEventAgentNet:PelcoAPI.IEventAgentNet
{
Int32 nCounter = 0;
public void NotifyEvent(String sResponse, PelcoAPI.EventNet
eventNet)
{
Console.Write("\nNotify EVENT {0}:\n", ++nCounter);
Console.Write("\tUDN: {0}\n", eventNet.m_sUdn);
Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId);
Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime);
Console.Write("\tType: {0}\n", eventNet.m_nType);
Console.Write("\tFriendly Name: {0}\n",
eventNet.m_sDeviceFriendlyName);
if (eventNet.m_nType == 1)
{
Console.Write("\tAssociated Camera UDN: {0}\n",
eventNet.m_sAssociateCameraUdn);
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0);
i++)
{
Console.Write("\tAlarm ID: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nId);
43
Console.Write("\t\tSeverity: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nSeverity);
Console.Write("\t\tState: {0}\n",
(eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off"));
}
}
else if (eventNet.m_nType == 2)
{
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0);
i++)
{
Console.Write("\tAlarm ID: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nId);
Console.Write("\t\tState: {0}\n",
(eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off"));
}
}
else if (eventNet.m_nType == 4)
{
Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" :
"Off"));
}
else if (eventNet.m_nType == 8)
{
Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" :
"Off"));
Console.Write("\tSeverity: {0}\n",
eventNet.m_nVideoAnalyticsSeverity);
}
Console.Write("EVENT Details:\n{0}\n", sResponse);
}
}
44
45
46
Using the Event Arbiter Library to Subscribe Using the Devices IP Address
NOTE: This entry is relevant for users who are not relying on either the System Manager or its EventArbiter
service. The related source code for this entry can be found in EventArbiterSample.cpps main function
(for C++) or ManagedEventArbiterSample.css main function (for C#), which belongs to the Event Arbiter
Library sample project.
This topic describes how to use the Event Arbiter Library to subscribe to a specific devices particular web service
using the devices IP address. Having an event subscription simply tells a device that you would like to receive its
event notifications. To request a event subscription, the following must be done:
1. Initialize the Event Arbiter Library.
Refer to Initializing the Event Arbiter Library for details.
2. Call the Event Arbiter wrapper instance's SubscribeToEvents method (SubscribeEvents in C#), passing the
event subscription URL.
For details, refer to Returning the Event Subscription URL. If the request was successful, the method will return
the event subscription's unique ID which will allow users to either renew or unsubscribe the event subscription. If
unsuccessful, the method returns NULL.
NOTE: Pelco SDK now automatically handles subscription renewals.
C++ Example:
const char * szSid_1 = pEventArbiter->SubscribeToEvents("http://10.220.196.184:80/
event/AlarmArrayConfiguration-1");
C# Example:
String strSid_1 = pEventArbiter.SubscribeEvents(
"http://10.220.196.184:80/event/AlarmArrayConfiguration-1);
Using the Event Arbiter Library to Subscribe Using the Event Subscription URL
This topic describes how to use the Event Arbiter Library to subscribe to a specific devices particular web service
using the Event Subscription URL.
NOTE: This entry is ONLY relevant for users who use an Endura network, specifically with an
active System Manager and an enabled EventArbiter service on the System Manager. The related
source code for this entry can be found in EventArbiterSample.cpps main function (for C++) or
ManagedEventArbiterSample.css main function (for C#), which belongs to the Event Arbiter Library
sample project.
1. Initialize the Event Arbiter Library.
Refer to Initializing the Event Arbiter Library for details.
2. Construct an event service ID.
It consists of the devices UDN and the web services URN, which is its namespace on its WSDL file. (For details
on determining a web services ID, refer to Returning the Event Subscription URL.)
C++ Example:
std::string strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15/
urn:pelco-com:serviceId:AlarmArrayConfiguration-1";
C# Example:
String strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15/
urn:pelcocom:serviceId:AlarmArrayConfiguration-1";
47
3. Call the Event Arbiter Library instance's SubscribeToEvents method (SubscribeEvents in C#), passing the
event service ID.
If the request was successful, the method will return the event subscription's unique ID which will allow users to
either renew or unsubscribe the event subscription.
NOTE: Pelco SDK now automatically handles subscription renewals.
C++ Example:
const char * szSid_1 = pEventArbiter>SubscribeToEvents(strEventServiceId.c_str());
C# Example:
String strSid_1 = pEventArbiter.SubscribeEvents(strEventServiceId);
48
To unsubscribe from an existing event subscription, call the Event Arbiter wrapper instance's
UnSubscribeToEvents method (UnsubscribeEvents in C#), passing the subscription identifier.
You should receive subscription IDs on successful calls to SubscribeToEvents. If the request was successful,
the method will return a 1 (for C++) or true (for C#). Otherwise it will return a 0 (for C++) or false (for C#).
C++ Example:
const char * szSid_1 = pEventArbiter->SubscribeToEvents(
"urn:schemas-pelco-com:service:MotionDetection:1");
// ... misc logic ...
pEventArbiter->UnSubscribeToEvents(strSid_1);
C# Example:
String strSid_1 = pEventArbiter.SubscribeEvents(
"urn:schemas-pelco-com:service:MotionDetection:1");
// ... misc logic ...
Boolean ret = pEventArbiter.UnsubscribeEvents(strSid_1);
49
50
This is where you will process any incoming event notifications. Events will be represented by the Event struct as
defined in the EventArbiterDefs header. (The raw event XML string data will be encapsulated by the parameter.)
Common to most events are the following attributes (listed below respectively):
C++ Example:
void MyEventAgent::NotifyEvent(const char * szResponse, const Event *
pEvent)
{
//... other logic ...
pEvent->m_strUdn.c_str();
pEvent->m_strServiceId.c_str();
pEvent->m_strUtcEventTime.c_str();
pEvent->m_nType;
pEvent->m_strDeviceFriendlyName.c_str();
C# Example:
Int32 nCounter = 0;
public void NotifyEvent(String sResponse, PelcoAPI.EventNet
eventNet)
{
Console.Write("\nNotify EVENT {0}:\n", ++nCounter);
Console.Write("\tUDN: {0}\n", eventNet.m_sUdn);
Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId);
Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime);
Console.Write("\tType: {0}\n", eventNet.m_nType);
Console.Write("\tFriendly Name: {0}\n",
eventNet.m_sDeviceFriendlyName);
If the incoming event is an alarm from the AlarmArrayConfiguration web service, it will provide information on
the camera it is associated with as well as general alarm data.
C++ Example:
if (pEvent->m_nType ==
PelcoAPI::EVENT_TYPE_ALARM_ARRAY_CONFIGURATION)
{
//the camera associated to this event
pEvent->m_strAssociateCameraUdn.c_str();
for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size();
i++)
{
//alarm ID
pEvent->m_alarmOrRelayInfo[i]->m_nId;
//alarm severity
pEvent->m_alarmOrRelayInfo[i]->m_nSeverity;
//the state of the alarm 0 off 1 on
pEvent->m_alarmOrRelayInfo[i]->m_bState;
}
}
C# Example:
if (eventNet.m_nType == 1)
{
Console.Write("\tAssociated Camera UDN: {0}\n",
eventNet.m_sAssociateCameraUdn);
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0);
i++)
{
Console.Write("\tAlarm ID: {0}\n",
51
eventNet.m_alarmOrRelayInfo[i].m_nId);
Console.Write("\t\tSeverity: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nSeverity);
Console.Write("\t\tState: {0}\n",
(eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off"));
}
}
If the incoming event is an alarm from the RelayArrayConfiguration web service, it will provide as general
relay data such as the relay ID and whether or not it is enabled.
C++ Example:
if (pEvent->m_nType ==
PelcoAPI::EVENT_TYPE_RELAY_ARRAY_CONFIGURATION)
{
for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size();
i++)
{
pEvent->m_alarmOrRelayInfo[i]->m_nId;
pEvent->m_alarmOrRelayInfo[i]->m_bState;
}
}
C# Example:
else if (eventNet.m_nType == 2)
{
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0);
i++)
{
Console.Write("\tAlarm ID: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nId);
Console.Write("\t\tState: {0}\n",
(eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off"));
}
}
If the incoming event is from the MotionDetection web service, it will show whether or not the motion detection
region is active or inactive.
C++ Example:
if (pEvent->m_nType ==
{
pEvent->m_bAlarmState;
}
PelcoAPI::EVENT_TYPE_MOTION_DETECTION)
C# Example:
else if (eventNet.m_nType == 8)
{
Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" :
"Off"));
Console.Write("\tSeverity: {0}\n",
eventNet.m_nVideoAnalyticsSeverity);
}
The szResponse parameter contains the raw event data in XML format. This is useful for debugging, or XML data
binding to your classes.
C++ Example:
TRACE_INFO("EVENT Details: \n%s\n", szResponse);
52
C# Example:
Console.Write("EVENT Details:\n{0}\n", sResponse);
Polling Events
NOTE: The related source code for this entry can be found in EventArbiterSample.cpp's main function
(for C++) or ManagedEventArbiterSample.cs's Main function (for C#), which belongs to the Event Arbiter
Library sample project. The availability of some data is dependent on the availability of a System Manager on
your network, that is, if a System Manager is not online, then some event data will be missing.
This API allows you to poll events instead of having to perform a callback.
1. Set the EventAgent to NULL in the RegisterEventAgent method.
C++ Example:
pEventArbiter->RegisterEventAgent(NULL);
C# Example:
MyEventAgentNet pAgent = null;
2. To poll events one by one using Event Arbiter or Event Manager, call the Event Arbiter or Event Manager
instance's PollEvent method.
std::string strRawEvent;
PelcoAPI::Event pelcoEvent
// Additional logic...
if (pEventArbiter->PollEvent(strRawEvent, pelcoEvent))
// ...
String sRawEvent = "";
PelcoAPI.EventNet pelcoEvent = null;
// Additional logic...
if (pEventManager.PollEvent(ref sRawEvent, ref pelcoEvent))
// ...
53
54
Chapter
5
Extracting Audio and Video Metadata
Extracting Audio and Video Metadata
WARNING: Any provided sample code is meant to be a reference implementation focused on educating
developers about Pelco devices. Though there are exceptions, in general Pelco sample code is NOT intended
for immediate production use without modification.
WARNING: The content below assumes that the default target installation directory was chosen during
installation.
NOTE: For the latest Pelco documentation, visit http://pdn.pelco.com.
There will always be special situations, such as custom video analytics, that call for processing video meta-data like
timestamps.
Where Does the Pelco SDK Fit?
The Meta-data Parser is a utility for parsing Pelco Video Elementary Stream (VES) meta-data from Pelco streams.
Pelco VES frames contain the following meta-data:
The Meta-data Parser consists of an interface that provides access to the various objects within the elementary
stream.
55
Motion detection involves computing the difference between two images. If the difference between the compared
images crosses a certain threshold value, then motion is detected and the selected Alert is triggered.
The key to Pelcos motion detection feature is the Region of Interest (ROI). The ROI denotes a motion detection region
within a video frame. A motion detection region is essentially a grid of motion detection 16x16 pixel cell blocks. These
cells have sensitivity and movement threshold limits. The sensitivity level dictates the amounts of movement that are
registered within the ROI, while the threshold dictates the amounts of blocks that are registered within the ROI before
the selected alarm is triggered.
What motion detection metadata is available? Currently in terms of metadata, each video frame can only hold a single
ROI. Consequently, for each frame, the metadata describes the length and width of the ROI, while also holding a Pelco
base64 bit mask for the state of the ROI.
NOTE: The difference between Pelco base64 and standard base64 implementations is that the Pelco version
always appends an = character at the end of the encoded value.
Drawing primitives are basic graphical elements. They encompass drawing points, fills, lines, arcs, and even text. This
basically contains information related to the points, lines, arcs, and so on.
Timestamps
Timestamp metadata represents the exact date and time when the video frame was captured. The Metadata Parser
Library can return this data in a number of ways.
struct timeval
The timestamp represented as a struct timeval.
tv_sec
The time interval in seconds since the epoch.
tv_usec
The time interval in microseconds since the epoch.
typedef struct timeval {
long tv_sec;
long tv_usec;
} timeval;
struct tm
The timestamp represented as a struct tm.
tv_sec
The time interval in seconds. (0-59)
56
tv_min
The time interval in minutes. (0-59)
tv_hour
The time interval in hours. (0-23)
tv_mday
The time interval in day of the current month. (1-31)
tv_mon
The time interval in months since January. (0-11)
tv_year
The time interval in years since 1900.
tv_wday
The time interval in days since Sunday. (0-6)
tv_yday
The time interval in days since January 1st. (0-365)
tv_isdst
A boolean that is true if it is currently daylight savings time, false otherwise.
typedef struct tm {
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday;
int tm_yday;
int tm_isdst;
}
In addition to returning the data above, the Metadata Parser Library also returns the daylight savings offset, the current
timezone, and values in local time.
Getting Started
For more information about getting started and setting up the working directory, refer to Setting Up Sample Projects.
Depending on whether you would like to use the release version of the Pelco SDK libraries or the debug version,
change the Working Directory value as appropriate. Assuming that you did not change the default installation directory
for the Pelco SDK, use C:\\Program Files\Pelco\API\Libs\Release to use the production version of the
Pelco SDK libraries. Conversely, use C:\\Program Files\Pelco\API\Libs\Debug to use the debug version of
the Pelco SDK libraries.
Whats Ahead
This is a high level overview of possible tasks related to metadata:
1. Access the metadata from the stream.
2. Render metadata onto a video frame.
57
2. Call its SetData method, passing the buffer containing the data to analyze and the buffer length as parameters.
PelcoAPI::MetaDataParser parser;
parser.SetData(videoBuffer, length);
58
2. Verify whether the parser has found a timestamp by calling the HasTimeStamp method, which will return true if
found, false otherwise.
if(true == parser.HasTimestamp()){
3. If there is a timestamp, call the GetTimeStampAsString method, passing in a local time Boolean parameter,
which if true returns the timestamp in local time, while false returns the UTC value:
std::string timestamp = parser.GetTimestampAsString(true, "%c");
2. Check if the parser has found motion detection data. Call the HasMotionData method, and if true, retrieve the
motion metadata.
if(true == parser.HasMotionData()){
PelcoAPI::MotionData *data = parser.GetMotionData();
3. After you retrieve the motion detection metadata, declare your MetaDataRenderer class.
SampleMetaDataRenderer renderer;
59
4. Create a new COLOR struct, setting the desired alpha transparency and colors to display on the screen. In this
example, the colors (red, green, blue) are fully opaque with zero transparency.
PelcoAPI::COLOR color = {255,0,128,255};
5. Render the motion metadata onto the screen by calling the RenderMotionData method.
renderer.RenderMotionData();
Drawing Metadata
Retrieving Drawing Metadata
NOTE: The related source code for this entry can be found in main.cpps ProcessDrawingData function,
which belongs to the Metadata Parser C++ sample project.
1. Initialize the MetaDataParser. For details, refer to Initializing the Meta-Data Parser Class.
2. Determine if the parser has found drawing data by calling the HasDrawingData method, which will return true if
found, false otherwise.
if(true == parser.HasDrawingData()){
3. If drawing metadata is found, call the GetDrawingData method, pulling the result into a DrawingData instance.
PelcoAPI::DrawingData *data = parser.GetDrawingData();
4. Parse the resulting data by iterating through the returned drawing primitives.
PelcoAPI::DrawingPrimitive *primitive = data->GetNextPrimitive();;
while(primitive != NULL){
primitive->GetPrimitiveType();
PelcoAPI::DrawingPrimitive::FreePrimitive(primitive);
primitive = data->GetNextPrimitive();
}
2. Determine if the parser has found drawing data by calling the HasDrawingData method, and if true, retrieve the
drawing metadata by calling the GetDrawingData.
if(true == parser.HasDrawingData()){
PelcoAPI::DrawingData *data = parser.GetDrawingData();
3. After you grab the drawing metadata, declare your MetaDataRenderer class.
SampleMetaDataRenderer renderer;
4. Create a new COLOR struct, setting the desired alpha transparency and colors to show on the screen. In this
example, the colors (red, green, and blue) are fully opaque with zero transparency.
PelcoAPI::COLOR color = {255,0,128,255};
5. Render the drawing metadata onto the screen by calling the RenderDrawingData method.
renderer.RenderDrawingData();
60
61
62
Chapter
6
Exporting Video
Overview
WARNING: Any provided sample code is meant to be a reference implementation focused on educating
developers about Pelco devices. Though there are exceptions, in general Pelco sample code is NOT intended
for immediate production use without modification.
NOTE: The content in this section assumes that the default target installation directory was chosen during
installation.
NOTE: For the latest Pelco documentation, visit http://pdn.pelco.com.
At some point, youll need to export your video into a variety of major formats.
63
a codec does not support the ISO MPEG-4 SP profile, the video received from the Endura system will not play back.
Fortunately there are many complete ISO MPEG-4 codecs available; ranging from free, open source versions to highly
optimized commercial versions
Getting Started
For more information about getting started and setting up the working directory, refer to Setting Up Sample Projects.
Whats Ahead
This is a high level overview of possible tasks related to export.
1. Set up desired video clips to export.
Configure desired parameters for each video clip to export.
If overlays are desired, set up overlays for each video clip.
2. Start the export, and continue to poll its status until it finishes successfully or encounters an error.
64
If performing a single video clip export as described in Exporting A Single Video Clip, the user must use the
OverlayData method for each desired overlay type before starting the export.
exporter.OverlayData(PelcoAPI::OVERLAY_TYPE_TIMESTAMP,
PelcoAPI::OVERLAY_LOCATION_BOTTOM_LEFT, NULL, FONTNAME, 10,
fontColor, fontBgColor, 0);
pEnduraExporterNet.OverlayData(PelcoAPI.OverlayTypeNet.OVERLAY_TYPE_TIMESTAMP,
PelcoAPI.OverlayLocationNet.OVERLAY_LOCATION_BOTTOM_LEFT, "",
FONTNAME, 10, FONTCOLOR, FONTBGCOLOR, 0, DATEFORMAT,
TIMEFORMAT);
If performing a stitched video clip export described in Stitching Multiple Clips Into a Single Video Export, the
user must use an OverlayInfo/OverlayInfoNet instance for each overlay type wanted before starting the
export.
exportInfo[i].overlayInfo = new
PelcoAPI::OverlayInfo[overlayNum];
exportInfo[i].overlayInfo[0].type =
PelcoAPI::OVERLAY_TYPE_TIMESTAMP;
// configure other parameters for the 1st overlay
PelcoAPI.OverlayInfoNet overlayInfo_0 = new
PelcoAPI.OverlayInfoNet();
overlayinfo_0.type =
PelcoAPI.OverlayTypeNet.OVERLAY_TYPE_TIMESTAMP;
// configure other parameters for the 1st overlay
OverlayData Parameters
OverlayData contains the following parameters. (Note that PPX export does not currently support overlays.)
timestamp
The overlay displays a timestamp that provides the time in local time.
cameraname
65
The overlay displays a cameras name. Typically the camera name displayed is the source of the
video stream.
textstring
The overlay displays text that the user specifies.
picture
The overlay displays a picture that the user specifies.
Now create a new instance of OverlayInfoNet and, based on the type of overlay you chose, simply start assigning
the desired values with it such the font to use, the color of the font, the location of the overlay, and so on.
The following is a list of other overlay settings (some may or may not apply to certain overlay types as noted):
location
The general screen location of the overlay. (Refer to the DataMixerPluginDefines header for the
latest definition of OverlayLocation.)
enum OverlayLocation
{
OVERLAY_LOCATION_UNKNOWN,
OVERLAY_LOCATION_TOP_LEFT,
OVERLAY_LOCATION_TOP_MIDDLE,
OVERLAY_LOCATION_TOP_RIGHT,
OVERLAY_LOCATION_CENTER,
OVERLAY_LOCATION_BOTTOM_LEFT,
OVERLAY_LOCATION_BOTTOM_MIDDLE,
OVERLAY_LOCATION_BOTTOM_RIGHT,
OVERLAY_LOCATION_COORDINATE
};
unknown
This denotes that the overlay will not appear on the screen.
top_left
The overlay will appear in the top left corner of the screen.
top_middle
The overlay will appear in the top of the screen.
top_right
The overlay will appear in the top right corner of the screen.
center
The overlay will appear in the center of the screen.
bottom_left
The overlay will appear in the bottom left corner of the screen.
bottom_middle
The overlay will appear in the bottom of the screen.
bottom_right
The overlay will appear in the bottom right corner of the screen.
coordinate
This is a system reserved value. Please disregard this value.
value
The actual value to display. For picture overlays, this is the full path to the picture to display. While
for cameraname overlays, this is the name of the camera. Finally for textstring overlays, this is just
the alphanumeric value to display on the overlay. (This does not apply to timestamp overlays.)
fontName
This is the name of an available font to use for displaying overlays. (This does not apply to picture
overlays. )
fontSize
This is the size of a font. (This does not apply to picture overlays .)
66
fontColor
This is the color of a font. (This does not apply to picture overlays.)
fontBgColor
This is the fonts color. (This does not apply to picture overlays.)
pictureOpacity
The opacity of the overlay. This ranges from transparent (0% opacity) to solid (100% opacity). (This
is only relevant for picture overlays.)
dateFormat
This is only relevant to the timestamp overlay.
enum DateFormat
{
DATE_FORMAT_MDYYYY = 0,
DATE_FORMAT_MDYY = 1,
DATE_FORMAT_MMDDYY = 2,
DATE_FORMAT_MMDDYYYY = 3,
DATE_FORMAT_YYMMDD = 4,
DATE_FORMAT_YYYY_MM_DD = 5,
DATE_FORMAT_DD_MM_YY = 6,
DATE_FORMAT_DMYY = 7,
DATE_FORMAT_DDMMYY = 8,
DATE_FORMAT_DMYYYY = 9,
DATE_FORMAT_DDMMYYYY = 10,
DATE_FORMAT_YYMD = 11,
DATE_FORMAT_YYYYMD = 12,
DATE_FORMAT_YYYYMMDD = 13,
DATE_FORMAT_YYYY_M_D = 14,
};
mdyyy
This date format conforms to the following structure: m/d/yyyy (month/day/year), where both 'm' and
'd' could be either one or two digits, for example, 12/8/2001 or 2/23/2001
mdyy
This date format conforms to the following structure: m/d/yy (month/day/year), where both 'm' and 'd'
could be either one or two digits, for example, 12/8/01 or 2/23/01
mmddyy
This date format conforms to the following structure: mm/dd/yy. (month/day/year), for example,
02/23/01
mmddyyyy
This date format conforms to the following structure: mm/dd/yyyy (month/day/year), for example,
02/23/2001
yymmdd
This date format conforms to the following structure: yy/mm/dd (year/month/day), for example,
01/02/23
yyyy_mm_dd
This date format conforms to the following structure: yyyy_mm_dd (year_month_day), for example,
2001-02-23
dd_mm_yy
This date format conforms to the following structure: dd_mm_yy (day_month_year), for example,
02-23-01
dmyy
This date format conforms to the following structure: d/m/yy (day/month/year), where both 'm' and 'd'
could be either one or two digits, for example, 23/2/01 or 8/12/01
ddmmyy
This date format conforms to the following structure: dd/mm/yy (day/month/year), for example,
08/12/01 or 23/02/01
67
dmyyyy
This date format conforms to the following structure: d/m/yyyy (day/month/year), where both 'm' and
'd' could be either one or two digits, for example, 23/2/2001 or 8/12/2001
ddmmyyyy
This date format conforms to the following structure: dd/mm/yyyy (day/month/year), for example,
21/03/2001
yymd
This date format conforms to the following structure: yy/m/d (year/month/day), where both 'm' and 'd'
could be either one or two digits, for example, 54/1/31 or 73/12/1
yyyymd
This date format conforms to the following structure: yyyy/m/d (year/month/day), where both 'm' and
'd' could be either one or two digits, for example, 1954/1/31 or 1973/12/1
yyyymmdd
This date format conforms to the following structure: yyyy/mm/dd (year/month/day), for example,
2001/02/23
yyyy_m_d
This date format conforms to the following structure: yyyy_m_d (year_month_day), where both 'm'
and 'd' could be either one or two digits, for example, 1954-1-31 or 1973-12-1
timeFormat
This is only relevant to the timestamp overlay.
enum TimeFormat
{
TIME_FORMAT_HHMMSSTT = 10,
TIME_FORMAT_HMMSSTT = 11,
TIME_FORMAT_HMMSS = 12,
TIME_FORMAT_HHMMSS = 13,
TIME_FORMAT_HMSTT = 14,
TIME_FORMAT_TTHMS = 15,
TIME_FORMAT_TTHHMMSS = 16,
TIME_FORMAT_HMS = 17,
};
hhmmsstt
This time format conforms to the following 12 hour structure: hh:mm:ss tt (hours:minutes:seconds
AM/PM), for example, 06:07:12 AM or 12:07:12 PM
hmmsstt
This time format conforms to the following 12 hour structure: h:mm:ss tt (hours:minutes:seconds AM/
PM), where 'h' could be either one or two digits, for example, 6:07:12 AM or 12:07:12 PM
hmmss
This time format conforms to the following 24 hour structure: h:mm:ss (hours:minutes:seconds),
where 'h' could be either one or two digits, for example, 6:07:12 or 18:07:12
hhmmss
This time format conforms to the following 24 hour structure: hh:mm:ss (hours:minutes:seconds), for
example, 06:07:12 or 18:07:12
hmstt
This time format conforms to the following 12 hour structure: h:m:s tt (hours:minutes:seconds), where
'h', 'm', or 's' could be either one or two digits, for example, 6:7:12 AM, 12:17:12 PM, or 12:3:2 PM
tthms
This time format conforms to the following 12 hour structure: tt h:m:s (AM/PM
hours:minutes:seconds), where 'h', 'm', or 's' could be either one or two digits, for example, AM
6:7:12, PM 12:17:12, or PM 12:3:2
tthhmmss
This time format conforms to the following 12 hour structure: tt hh:mm:ss (AM/PM
hours:minutes:seconds), for example, AM 06:07:12, PM 12:17:12, or PM 12:03:02
68
hms
This time format conforms to the following 24 hour structure: H:m:s (hours:minutes:seconds), where
'h', 'm', or 's' could be either one or two digits, for example, 6:7:12, 12:17:12, or 12:3:2
Exporting Video
This section describes various video export methods and scenarios.
69
Set to true to export only video, while setting this to false to include audio (if it is available). If you
want audio to be included, it will be available in either PEF or AVI format.
The UUID of the stream to exports audio source, if separate from the video source of the export
C++ Example:
bool bSuccess = exporter.StartExport("D:\\Video\\test123.avi",
"uuid:691fd745-006c-4fc9-9262-23c13e977ce4",
PelcoAPI::CODEC_ID_MPEG4,
"2010-01-11T22:10:35", "2010-01-11T22:11:15", false,
"uuid:691fd745-006c-4fc9-9822-23c13e977ce4");
C# Example:
Boolean bSuccess =
exporter.StartExport("D:\\Video\\test123.avi",
"uuid:691fd745-006c-4fc9-9262-23c13e977ce4",
PelcoAPI::CODEC_ID_MPEG4,
"2010-01-11T22:10:35", "2010-01-11T22:11:15", false,
"uuid:691fd745-006c-4fc9-9822-23c13e977ce4");
5. Poll the status of the video export repeatedly, for example, once per second, until it is finished. For more
information, see Polling a Video Export.
70
AudioDeviceID
The UUID of the stream to exports audio source, if separate from the video source of the export.
StartTime
The start time in UTC (GMT), not local time, using the format yyyy-mm-ddthh:mm:ss
EndTime
The end time in UTC (GMT), not local time, using the format yyyy-mm-ddThh:mm:ss
VideoOnly
A boolean indicating if the clip should be exported with video only. If false, audio will also be
included.
ClipGroup
An integer representing the sequential order to play video clips. Up to 4 clips can be in the same clip
group which will play in sync within the export player.
C++ Example:
PelcoAPI::PlaylistExportInfo playlistExportInfo[ NUM_CLIPS ];
playlistExportInfo[0].sDeviceID = CAMERA_1;
playlistExportInfo[0].sStartTime = START_TIME_1;
playlistExportInfo[0].sEndTime = END_TIME_1;
playlistExportInfo[0].bVideoOnly = false;
playlistExportInfo[0].nClipGroup = 1;
C# Example:
ArrayList playlistExportInfo = new ArrayList( num_clips );
playlistExportInfo.Add( new PelcoAPI.PlaylistExportInfoNet( CAMERA_1,
"", START_TIME_1, END_TIME_1, false, 1 ) );
4. Begin the video export by calling the Exporters StartExport method, passing in the following parameters:
exportFolder
The path of the folder for exports. (The format changes based on operating system.)
playlistName
The name of the playlist. This should be a simple name with no extensions
playlistExportInfo
An array of playlist information for export.
exportInfoCount
The number of export info entries
C++ Example:
bool bSuccess = exporter.StartExport("D:\\Video\\test123",
PlaylistName, PlaylistExportInfo, exportInfoCount);
C# Example:
Boolean bSuccess = pEnduraExporterNet.StartExport("D:\\Video\\test123",
PlaylistName, PlaylistExportInfo, exportInfoCount);
5. Poll the status of the video export repeatedly, for example, once per second, until it is finished.
For more information, see Polling a Video Export.
71
First initialize as many video clip export settings (ExportInfo) instances as you will need. For details on how to
set up one set of video clip export settings, refer toSetting Up Overlay Data on Video to Be Exported .
At this point determine if you want to associate any overlays to the video clips. If so, create and initialize any
overlays to associate with the video clip to export. In the example excerpt below, we have associated four
previously created OverlayInfo instances with two ExportInfo instances.
72
PelcoAPI::OVERLAY_TYPE_CAMERANAME;
// configure other settings for the 2nd overlay
exportInfo[i].overlayInfo[2].type =
PelcoAPI::OVERLAY_TYPE_PICTURE;
// configure other settings for the 3rd overlay
exportInfo[i].overlayInfo[3].type =
PelcoAPI::OVERLAY_TYPE_TEXTSTRING;
// configure other settings for the 4th overlay
}
}
bool bSuccess = exporter.StartExport("D:\\Video\\test123.mp4",
PelcoAPI::CODEC_ID_MPEG4, exportInfo, 2);
C# Example:
PelcoAPI.ExportInfoNet exportInfo_0 = new
PelcoAPI.ExportInfoNet();
exportInfo_0.sDeviceID =
"uuid:00047D01-4CA5-5370-6563-747261495605";
exportInfo_0.sStartTime = "2009-08-16T05:08:00";
exportInfo_0.sEndTime = "2009-08-16T05:09:00";
exportInfo_0.bVideoOnly = true;
PelcoAPI.ExportInfoNet exportInfo_1 = new
PelcoAPI.ExportInfoNet();
// initialize another export video clip setting
exportInfo_0.overlayInfo = new ArrayList();
exportInfo_0.overlayInfo.Add(overlayInfo_0);
// add any other overlay settings here
exportInfo_1.overlayInfo = new ArrayList();
exportInfo_1.overlayInfo.Add(overlayInfo_0);
// add any other overlay settings here
ArrayList exportInfo = new ArrayList(2);
exportInfo.Add(exportInfo_0);
exportInfo.Add(exportInfo_1);
Boolean bSuccess = pEnduraExporterNet.StartExport("C:\\test456.avi",
PelcoAPI.VideoCodecTypeNet.CODEC_ID_MPEG4, exportInfo, 2);
5. Poll the status of the video export repeatedly, for example, once per second, until it is finished.
For more information, see Polling a Video Export.
73
74
Chapter
7
Web Service Proxies
Web Service Proxies
WARNING: Any provided sample code is meant to be a reference implementation focused on educating
developers about Pelco devices. Though there are exceptions, in general Pelco sample code is NOT intended
for immediate production use without modification.
WARNING: The content below assumes that the default target installation directory was chosen during
installation.
For the latest Pelco documentation, visit http://pdn.pelco.com.
Overview
PelcoGSoap is a static linked library generated by gSOAP tools, based on the WSDL files with minor modifications.
The PelcoGSoap library provides an interface for SOAP clients to make SOAP calls to Pelco devices. It accounts for
most issues regarding making SOAP calls to Pelco devices.
General Usage
NOTE: This entry assumes that users have already installed the Pelco SDK.
1. Include the stdsoap2 header and the web service proxy header. For example, if you want to utilize the
CameraConfiguration web service, you should include the CameraConfigurationProxy header.
#include "PelcoAPI/stdsoap2.h"
#include "PelcoAPI/CameraConfigurationProxy.h"
2. Declare your web service proxy. In this case, it will be CameraConfigurationProxy.
CameraConfigurationProxy CameraConfiguration;
3. Set the SOAP header.
pSoap->header = (struct SOAP_ENV__Header *) soap_malloc(CameraConfiguration,
sizeof(struct SOAP_ENV__Header));
4. Set the web services control point URL. For details on the proper way to retrieve the control point URL, refer to
Retrieving a Specific Web Services Control URL.
CameraConfiguration.soap_endpoint = strEndPointURL.c_str();
5. Create a new web service action request instance.
This will hold your request parameters for the web service action ResetConfiguration.
6. Create a new web service action response instance. In the below example, we create an instance of
CameraConfigurations ResetConfigurationResponse data type.
_CameraConfiguration__ResetConfigurationResponse * pResetConfigurationResponse =
soap_new__CameraConfiguration__ResetConfigurationResponse(
75
&CameraConfiguration, -1);
This will hold the web services response including related values to your request.
7. Call the CameraConfiguration web service proxy ResetConfiguration action, passing in both the earlier
created ResetConfiguration and ResetConfigurationResponse parameters. Then determine if the
operation was successful.
CameraConfiguration.ResetConfiguration(pResetConfiguration,
pResetConfigurationResponse);
#include "PelcoAPI/stdsoap2.h"
#include "PelcoAPI/LensControlProxy.h"
#include "GSOAPSample.h"
using namespace PelcoAPI;
void GSOAPSample::StopLens() throw()
{
LensControlProxy LensControl;
std::string cameraAddress = "10.18.129.231";
std::string cameraPort = "49152";
pSoap->header = (struct SOAP_ENV__Header *) soap_malloc(LensControl, sizeof(struct
SOAP_ENV__Header));
std::string strEndPointURL = "http://" + cameraAddress + (cameraPort.empty() ?
"" : ":" + cameraPort) + "/control/LensControl-1";
LensControl.soap_endpoint = strEndPointURL.c_str();
_LensControl__Stop * pStop = soap_new__LensControl__Stop(&LensControl, -1);
_LensControl__StopResponse * pStopResponse =
soap_new__LensControl__StopResponse(&LensControl, -1);
if (LensControl.Stop(pStop, pStopResponse) != SOAP_OK)
76
Chapter
8
Discovery
Device and Service Discovery Overview
WARNING: Any provided sample code is meant to be a reference implementation focused on educating
developers about Pelco devices. Though there are exceptions, in general Pelco sample code is NOT intended
for immediate production use without modification.
WARNING: The content below assumes that the default target installation directory was chosen during
installation.
For the latest Pelco documentation, visit http://pdn.pelco.com.
One of the most basic tasks is to programmatically determine what devices and services are available on your
network.
Where Does the Pelco SDK Fit?
The key to performing device and service discovery related tasks is the System Manager Wrapper. The System
Manager Wrapper is a component of the Pelco SDK. It provides users with convenience functions for device and
service queries.
The majority of the tasks covered in this section can be found in the the System Manager Wrapper C++ sample
project. You should examine the sample project source code while reading this documentation.
NOTE: For more Endura specific information, refer to the Endura appendix.
Getting Started
For more information about getting started and setting up the working directory, refer to Setting Up Sample Projects.
77
C5617M-A | Discovery
Depending on whether you would like to use the release version of the Pelco SDK libraries or the debug version,
change the Working Directory value as appropriate. Assuming that you did not change the default installation directory
for the Pelco SDK, use C:\\Program Files\Pelco\API\Libs\Release to use the production version of the
Pelco SDK libraries. Conversely, use C:\\Program Files\Pelco\API\Libs\Debug to use the debug version of
the Pelco SDK libraries.
Next Steps
The following set of tasks are essential for using the Pelco SDK:
Determine the System Managers IP address and port number, either manually, or automatically through the Pelco
SDK as described in Automatically Determining the System Managers IP Address and Port Number.
Create a class that implements the IDeviceStorageNet interface.
Query all available Pelco devices on your network.
78
C5617M-A | Discovery
C# Example:
sm.UserLogout(loginId);
79
C5617M-A | Discovery
Your login ID: This ID is returned after a successful login. See Initializing the System Manager Wrapper for
details.
The sequence number: This is used to filter results, only returning newly added or changed devices.
GetDevices calls return a new integer value once every few minutes during successive calls. New values are
1 larger than the one before, for example, if the 1st call returned 1, then the subsequent call will return a 2.
The device type you would like to use to filter the results. Known device types include the following:
Camera
Encoder
Decoder
Monitor
a NULL value (to not filter results by type of device)
NOTE: This is not a definitive list of Pelco device types. This list will expand as Pelco expands its product
line.
C++ Example:
int seqNum = 0;
MyStorage storage; // ... You must define this class ...
int loginId = sm.UserLogin("brian", "pelco");
sm.GetDevices(loginId, &seqNum, "Camera", &storage);
C# Example:
int seqNum = 0;
DeviceInformation devStore = new DeviceInformation(); // You must define this
class
int loginId = sm.UserLogin("brian", "pelco");
Boolean bSuccess = sm.GetDevices(loginId, seqNum, "Camera", devStore);
3. Perform the needed operations on the returned device data and store them into your IDeviceStorage class
instance. See Creating an IDeviceStorage Class for further details.
4. To query any changes with available devices from the System Manager, use the returned sequence number value
from your last call to the GetDevices method with your next call to the same method.
This call returns Pelco devices that have changed or are new to the network. Every subsequent call returns only
new changes within your network.
C++ Example:
int seqNum = 0;
MyStorage storage; // ... You must define this class ...
int loginId = sm.UserLogin("brian", "pelco");
sm.GetDevices(loginId, &seqNum, "Camera", &storage); // ... seqNum changes here to
1 ...
// ... Misc logic ...
80
C5617M-A | Discovery
81
C5617M-A | Discovery
C++ Example:
PelcoAPI::xstring sNtpAddress;
int loginId = sm.UserLogin("brian", "pelco");
bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr", &sNtpAddress);
C# Example:
int loginId = sm.UserLogin("brian", "pelco");
String sNtpAddress = "";
Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr",
ref sNtpAddress);
82
C5617M-A | Discovery
83
C5617M-A | Discovery
C# Example:
String sNvr = ;
int loginId = sm.UserLogin("brian", "pelco");
Boolean bSuccess = sm.GetDeviceAttributeValue(loginId,
"uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_NvrAssoc",
ref sNvr);
84
C5617M-A | Discovery
85
C5617M-A | Discovery
NOTE: This entry assumes that you have already completed the steps outlined in Querying Available Devices
from the System Manager, which provides you with UDNs for Pelco devices available on your network.
Device attributes are values that describe the device in some way such as its model number or its model name. The
following are the most common device attributes:
SYS_UpnpPelcoDeviceUdn
A Pelco devices Unique Device Name (UDN); a special device identifier for networks.
SYS_UpnpFriendlyName
A more human readable version of the devices name. A separate attribute, friendlyName, may be
present. Endura users can customize this attribute. When present, friendlyName should be used
in place of SYS_UpnpFriendlyName for display purposes.
SYS_UpnpDeviceType
86
C5617M-A | Discovery
Change Time
This number is the absolute daylight savings time (in time_t time() seconds). If this value is zero,
there is no daylight savings time for the time zone and nothing will have to be done to support
daylight savings. If the value is non-zero, the time zone does support daylight savings time. In this
case, if the value is negative, the time value is being used to indicate the time to turn off daylight
savings time. If the value is positive, the value is being used to indicate the time at which daylight
savings time is to be turned on.
DST Offset
This number is the number of minutes to adjust the time when daylight savings time is in affect. The
offset should be added to the GMT time after adding the GMT offset (see next value).
GMT Offset
This value indicate the number of minutes to adjust the GMT time in order to get the local time (this is
the minutes "west" of the GMT). To get the current local time, simply subtract this number of minutes
from the current GMT time.
SYS_CFG_UPNP_RENEWAL
The UPnP renewal value in seconds. The default setting is 1800 seconds (30 min).
SYS_CFG_UserLanguage
This value is used to indicate the default user language.
To determine a particular attribute value on your System Manager, do the following:
1. Initialize the System Manager Wrapper. (Refer to Initializing the System Manager Wrapper for details.)
2. Call the System Manager Wrappers GetSystemAttribute method, passing in the following parameters:
Your login ID
This ID is returned after a successful login. (Refer to Initializing the System Manager Wrapper for
details.)
systemAttribute
The name of the System Manager attribute. Parameter of type pointer to xstring, value
SYS_CFG_TzInfo.
87
C5617M-A | Discovery
88
C5617M-A | Discovery
What is the IDeviceStorageNet class? An IDeviceStorageNet is simply an interface that parses XML
responses from the System Manager and stores the resulting device data from the XML response internally. Users
need an implementation of this interface, if they wish to manage device data using the System Manager Wrapper.
1. Ensure that the IDeviceStorageNet class implements the following methods:
virtual bool AddDevice(const char* sUDN, const char* sAttributes): This method adds a
new device to the IDeviceStorageNet class. It takes the following parameters:
The System Manager Wrapper will use these methods every time you call its GetDevices method, which in turn
will update your IDeviceStorage instance contents.
C++ Example:
#ifndef PELCO_API_IDEVICE_STORAGE_H
#define PELCO_API_IDEVICE_STORAGE_H
#include <string>
namespace PelcoAPI
{
class IDeviceStorage
{
public:
virtual ~IDeviceStorage(){};
virtual bool AddDevice(const char* sUDN, const char* sXmlAttributes)=0;
virtual bool DeleteDevice(const char* sUDN)=0;
virtual bool UpdateDevice(const char* sUDN, const char* sXmlAttributes)=0;
};
}
#endif
C# Example:
using System;
using System.Collections.Generic;
using System.Text;
namespace SystemManagerWrapperNet
{
class DeviceInformation : PelcoAPI.IDeviceStorageNet
{
public void AddDevice(string sUDN, string sAttributes)
{
// ... User implemented logic here ...
}
public void DeleteDevice(string sUDN)
{
// ... User implemented logic here ...
}
}
}
2. Note that the System Manager Wrapper sample project has an implementation of IDeviceStorage called
MyStorage.
89
C5617M-A | Discovery
MyStorage is a stub class. It does not implement anything that is essential for production usage, such as parsing
the System Managers XML response data (attributes). Nor does it associate the device UDN/attribute XML pairs
into any constructs. Those exercises are left to the user.
90
Appendix
A
Logging
Logging is specific to Endura, and is configurable.
1. To configure logging, run the LoggingSetup application in the C:\Program Files\Pelco\API\Logging
folder.
2. Select the items that you want to log, as well as the folder where the logs should be stored and the max logfile
size.
3. Click Set to save the settings.
NOTE: Logging should be run by an administrative account, because other users do not have write
permissions to C:\Program Files (x86) or subdirectories by default.
4. To view the current log, run the LoggingSetup application in the C:\Program Files\Pelco\API\Logging
folder. Click the View Log File button.
NOTE: The maximum log size is 50MB. Any settings over that value will be reset back to the default
50MB restriction. Usually, logging should be off (no items checked) unless Pelco technical support asks for
logging information when tracing issues.
In the Logging dialog box, the following settings are available:
Error
Logs error messages. This is usually the most important item.
Memory
Logs memory allocation statistics. This should usually be left unchecked.
Info
The next level of severity below Error.
Verbose
91
C5617M-A | Logging
Logs actions that occur often and should normally not be logged because they fill up the logfile
quickly.
92
Appendix
B
Product Compatibility
The following table shows the compatability of Pelco products with API components.
4
5
Product
Exporter
Meta-data
Parser
Pelco API
Viewer
PTZ Control
Wrapper
SM Wrapper
DX Video
Recorders
Digital
Sentry
DVR5100
Y
Y
NET5400T-I
NSM5200
Sarix
Spectra HD
Spectra IV
IP
Spectra Mini Y
SM5000
Endura
Express
IP110
IP3701
NET5301R
NET5402RHD
NET5301T
NET5308T
NET5301T-I
93
94
Appendix
C
Endura
In 2005, Endura provided a distributed architecture that delivered both flexibility and performance. Endura is a
complete solution for high definition video encoding, recording, and display. It controls the origination, transport,
recording, and display of integrated, security-related audio and video.
From a technical standpoint, what defines an Endura system?
System Manager + Endura Devices = Endura System
System Manager (SM)
First and foremost, an Endura system must have a System Manager (SM). The SM is the heart of Endura. It is
responsible for the following:
Managing devices such as cameras, decoders, and NVRs, including administering rights and privileges
Storing device information, like status
Administering users, which includes permissions management
Logging errors and alarms
Security key management
Endura Devices
Endura devices can be defined as IP cameras, encoders, decoders, NVRs, or even work stations. Each Endura
device, including the SM itself, has an Application Programming Interface (API). An API is simply a specified way
for software clients to programmatically communicate with Endura devices, allowing access to their functionality.
All Endura devices provide an API through a set of related web services. These web services adhere to the SOAP
standard. (For more details on SOAP, please refer to the following http://en.wikipedia.org/wiki/SOAP.) It is beyond the
scope of this documentation to fully describe all Endura web services. For details, such as the SOAP web service API
reference, please refer to the Pelco Developer Network (PDN) at http://pdn.pelco.com.
One of the main purposes of a System Manager is to provide a central place to retrieve information on all Endura
devices. How does the System Manager collect all of this information?
95
C5617M-A | Endura
1. The System Manager constantly provides a broadcast of its location on the Endura Network. Once a device comes
online, it will listen for this broadcast. When the new device finds the SM, it will then register itself to the System
Manager.
2. At some point the System Manager will query the devices available web services and its attributes, using a variety
of sources including the UPnP Device Description File (DDF). DDFs are files containing device attributes in XML
format.
3. After the initial query, the System Manager will periodically update the devices status. To be considered online, a
device must constantly notify the SM that it is still alive.
4. At any point a client can make requests to the System Manager regarding devices, including the SM itself, and their
web services.
Endura Events and Alarms
There are two major ways to subscribe to Endura web service events:
Directly contacting the device on which the target web service resides
Using the System Manager as an intermediary to perform actual eventing related work
On newer Endura network deployments, the first option is the default. Users can enable the System Manager to act as
an intermediary by enabling its EventArbiter web service (not to be confused with the Event Arbiter Library). The
EventArbiter web service is used for receiving GENA events from devices within an Endura network. The Event
Arbiter provides two ways for subscribing to events:
96
C5617M-A | Endura
97
C5617M-A | Endura
Video Exports
Currently the Exporter library requires a System Manager to be present to function. How does it work? The Exporter
client sends its request for video clips to export with atimestamp range filter to the System Manager; that is, it wants
clips that fall within a starting date time and an ending date time. The System Manager will then query all available
NSMs for clips that meet both the starting timestamp and the ending timestamp. Specifically, there may be instances
where the API must stitch the end result from more than one NSM source of video clips to meet the filter.
Where Does the Pelco API SDK Fit Within Endura?
The Pelco API SDK is meant to make using Endura web services easier by providing convenience methods and
utilities. It protects the user from all of the potentially overwhelming and complicated details of Endura SOAP web
services. Of course users are still free to directly use Endura web services. However Pelco has found that many of our
customers enjoy the convenience and ease of use that the Pelco API SDK provides.
98
Appendix
D
General Event Messages
LoggableEvent
This defines the general structure of logged data for events. It does not have a set of enclosing tags. For further
details, refer to the event message descriptions below.
<element
<element
<element
<element
<element
<element
<element
<element
<element
name="deviceUdn" type="xs:int"/>
name="deviceUrn" type="xs:string"/>
name="serviceUrn" type="xs:string"/>
name="logId" type="xs:int"/>
name="major" type="xs:int"/>
name="minor" type="xs:int"/>
name="type" type="xs:int"/>
name="reason" type="xs:int"/>
name="parameters" type="tns:LoggableEventParameters"/>
deviceUdn
deviceUrn
serviceUrn
LoggableEventParameters
This contains a list of LoggableEventParameter data types. For further details, refer to the event message
descriptions below.
<complexType name="LoggableEventParameters">
<sequence>
<element minOccurs="0" maxOccurs="unbounded" name="parameter"
type="tns:LoggableEventParameter"/>
</sequence>
</complexType>
99
parameter
LoggableEventParameter
This represents an event-related parameter. For further details, refer to the event message descriptions below.
<complexType name="LoggableEventParameter">
<sequence>
<element name="paramId" type="xs:int"/>
<element name="name" type="xs:string"/>
<element name="value" type="xs:int"/>
<element name="type" type="xs:int"/>
</sequence>
</complexType>
paramId
The parameter's unique identifier.
name
The parameter's name.
value
The parameter's value.
type
The parameter's type identifier.
100
Appendix
E
Hardware Diagnostics Event Messsages
ConfigurationButton (20180)
This event triggers if the front panel configuration button has failed.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="ConfigurationButton">
<sequence>
<element name="objGuid" type="xs:string"
fixed="394af82c-2b05-4df8-b2a6-2caed9ad4fae"/>
<element name="objId" type="xs:int" fixed="20180"/>
<element name="current" type="xs:int"/>
<element name="previous" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 394af82c-2b05-4df8b2a6-2caed9ad4fae
objId
The event's unique database identifier. The value must be: 20180
current
The current state of the button. Possible values are:
1 for BUTTON_CONFIG
The button is in "Configuration mode".
2 for BUTTON_REBOOT
The button is in "Reboot system".
3 for BUTTON_RESET
The button is in "Reset configuration".
4 for BUTTON_NORMAL
The button currently does not have a state.
previous
The previous state of the button. For possible values, refer to current.
<pdDiagnostic>
<objGuid>394af82c-2b05-4df8-b2a6-2caed9ad4fae</objGuid>
<objId>20180</objId>
<current>1</current>
<previous>3</previous>
</pdDiagnostic>
101
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>4</type>
<reason>1</reason>
<parameters></parameters>
DriverFailure (20150)
A DriverFailure PdDiagnostic object is only sent when a device's driver fails, so a LoggableEvent object is
used to set the correct major, minor, type, and reason. This is typically used for multi-channel encoder (MCE) devices.
PdDiagnostic
This is the data that subscribers receive when the event triggers.
<complexType name="DriverFailurePdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/>
<element name="objId" type="xs:int" fixed="20150"/>
<element name="name" type="xs:string"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 94b6d2d3c68e-4b13-974a-08f69f50cb67
objId
The event's unique database identifier. The value must be: 20150
name
The name of the device driver
<complexType name="DriverFailurePdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/>
<element name="objId" type="xs:int" fixed="20150"/>
<element name="name" type="xs:string"/>
</sequence>
</complexType>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>5</type>
<reason>1</reason>
<parameters></parameters>
102
Fans (20020)
Any device with any fans having a changed state will have a LoggableEvent fired.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="FanPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/>
<element name="objId" type="xs:int" fixed="20050"/>
<element name="states" type="tns:FanStates"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 31e41907-53be-4f57-8ae2a56c12d98d0e
objId
The event's unique database identifier. The value must be: 20050
states
A FanStates data type.
FanStates
This contains list of one or more FanState data types.
<complexType name="FanStates">
<sequence>
<element name="state" maxOccurs="unbounded" minOccurs="1"
type="tns:FanState"/>
</sequence>
</complexType>
state
A FanState data type.
FanState
This represents the current and previous condition of a fan.
<complexType name="FanState">
<sequence>
<element name="cur" type="xs:int"/>
<element name="prev" type="xs:int"/>
</sequence>
</complexType>
cur
The current state identifier. Possible values are the following:
1 for FAN_OK
The fan is operating normally.
2 for FAN_FAILED
The fan has failed.
3 for FAN_UNKNOWN
The state of the fan is currently unknown; this fan does not have an initial state registered. NOTE:
This will always be the final stream state.
103
prev
The previous state identifier. This has the same possible values as cur.
<pdDiagnostic>
<objGuid>31e41907-53be-4f57-8ae2-a56c12d98d0e</objGuid>
<objId>20220</objId>
<states>
<state>
<cur>1</cur>
<prev>0</prev>
</state>
<state>
<cur>0</cur>
<prev>0</prev>
</state>
<state>
<cur>0</cur>
<prev>0</prev>
</state>
</states>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>5</type>
<reason>1</reason>
<parameters></parameters>
HardDrives (20060)
For each CPdDiagHarddrives object, you can send loggable events for hard drives that have a state change. Set
the state of the hard drive to the appropriate major, minor, type, and reason.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="HardDrivesPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/>
<element name="objId" type="xs:int" fixed="20060"/>
<element name="states" type="tns:HardDrivesStates"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 31e41907-53be-4f57-8ae2a56c12d98d0e
objId
The event's unique database identifier. The value must be: 20060
states
A HardDrivesStates data type.
104
HardDrivesStates
This contains a list of one or more HardDrivesState data types.
<complexType name="HardDrivesStates">
<sequence>
<element name="state" maxOccurs="unbounded" minOccurs="1"
type="tns:HardDrivesState"/>
</sequence>
</complexType>
state
A HardDrivesState data type.
HardDrivesState
This represents the current and previous condition of a hard drive.
<complexType name="HardDrivesState">
<sequence>
<element name="cur" type="xs:int"/>
<element name="prev" type="xs:int"/>
</sequence>
</complexType>
cur
The current state identifier. Possible values are the following:
1 for HDS_READY
Indicates that the hard disk is currently in use.
NOTE: This may indicate a problem if the disk is known to be currently NOT in use.
2 for HDS_ONLINE
Indicates that a disk is online and currently being used.
3 for HDS_FAILED
Indicates that a disk has failed.
4 for HDS_HOTSPARE
Indicates that a disk is currently being used as a 'hot spare' within the array.
5 for HDS_REBUILD
Indicates that a disk is currently being rebuilt.
6 for HDS_NONE
Shows that there is currently no hard drive connected, and there is room for a hard drive.
7 for HDS_UNKNOWN
The hard drive's state is currently unknown; this typically means that the hard drive has yet to
register any state.
NOTE: This will always be the final stream state.
prev
The previous state identifier. This has the same possible values as cur.
<pdDiagnostic>
<objGuid>8dda89bd-3c2c-4a35-aad4-1256cb5e1d27</objGuid>
<objId>20060</objId>
<states>
<state>
<cur>1</cur>
<prev>2</prev>
</state>
<state>
<cur>1</cur>
105
<prev>1</prev>
</state>
<state>
<cur>1</cur>
<prev>1</prev>
</state>
</states>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>9</type>
<reason>1</reason>
<parameters>
<param>
<paramId>6</paramId>
<name>HardDriveId</name>
<value>0</value>
<type>1</type>
</param>
</parameters>
ImproperShutdown (20070)
A ImproperShutdownPdDiagnostic object is sent when an improper shutdown occurs, so a LoggableEvent object can
be initialized with the appropriate major, minor, type, and reason data.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="ImproperShutdownPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="a44945e0-fa54-4fb0-a614-2e71886c508f"/>
<element name="objId" type="xs:int" fixed="20070"/>
<element name="mode" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: a44945e0-fa54-4fb0a614-2e71886c508f
objId
The event's unique database identifier. The value must be: 20070
mode
The mode of the shutdown.
<pdDiagnostic>
<objGuid>a44945e0-fa54-4fb0-a614-2e71886c508f</objGuid>
<objId>20070</objId>
<mode>4</mode>
</pdDiagnostic>
106
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>4</type>
<reason>4</reason>
<parameters></parameters>
LinkSpeed (20200)
This event triggers when the link speed changes. We then set the correct major, minor, type, and reason for
LoggableEvent. The current LinkSpeed is sent as a parameter with the LoggableEvent object.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="LinkSpeedPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="b9359885-711a-4d71-b908-4bdf8753dbe8"/>
<element name="objId" type="xs:int" fixed="20200"/>
<element name="min" type="xs:int"/>
<element name="cur" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: b9359885-711a-4d71b908-4bdf8753dbe8
objId
The device's unique database identifier. The value must be: 20200
min
The minimum link speed. For example: 100
cur
The current state. For example: 10
<pdDiagnostic>
<objGuid>b9359885-711a-4d71-b908-4bdf8753dbe8</objGuid>
<objId>20200</objId>
<min>100</min>
<cur>10</cur>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>6</type>
<reason>0</reason>
107
<parameters>
<param>
<paramId>5</paramId>
<name>CurrentLinkSpeed</name>
<value>10</value>
<type>1</type>
</param>
</parameters>
PowerSupply (20120)
A PowerSupplyPdDiagnostic object is sent when a power supply encounters a problem so that a
LoggableEvent object can be initialized with the appropriate major, minor, type, and reason data.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="PowerSupplyPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="26f051aa-009b-4a5d-ab20-09b064a07a52"/>
<element name="objId" type="xs:int" fixed="20120"/>
<element name="inAlarm" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: 26f051aa-009b-4a5dab20-09b064a07a52
objId
The device's unique database identifier. The value must be: 20200
inAlarm
This represents whether or not a device is in a problem state. Possible values are:
0
The power supply is operating properly; not in an alarm state.
1
Problems with the power supply; in alarm state.
<pdDiagnostic>
<objGuid>26f051aa-009b-4a5d-ab20-09b064a07a52</objGuid>
<objId>20120</objId>
<inAlarm></inAlarm>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>2</type>
<reason>0</reason>
<parameters></parameters>
108
UPS (20170)
This event triggers if a UPS either fails or runs out of power.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="UPSPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="e746c2c8-0b97-402e-abc3-c784890c8d99"/>
<element name="objId" type="xs:int" fixed="20170"/>
<element name="cur" type="xs:int"/>
<element name="pre" type="xs:int"/>
<element name="rem" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: e746c2c8-0b97-402e-abc3c784890c8d99
objId
The event's unique database identifier. The value must be: 20170
cur
The current state identifier. For example: 4
pre
The previous state identifier. For example: 1
<pdDiagnostic>
<objGuid>e746c2c8-0b97-402e-abc3-c784890c8d99</objGuid>
<objId>20170</objId>
<Cur>4</Cur>
<Pre>1</Pre>
<Rem>0</Rem>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>24</type>
<reason>0</reason>
<parameters>
<param>
<paramId>4</paramId>
<name>TimeRemaining</name>
<value>0</value>
<type>1</type>
</param>
</parameters>
109
110
Appendix
F
Software Diagnostics Event Messsages
DataLoss 20040
When this is triggered by a data loss, set the correct major, minor, type, reason for the LoggableEvent.
PdDiagnostic
This is the data that subscribers will receive when the event triggers.
<complexType name="DataLossPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/>
<element name="objId" type="xs:int" fixed="20040"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 94b6d2d3c68e-4b13-974a-08f69f50cb67
objId
The event's unique database identifier. The value must be: 20040
<complexType name="DataLossPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/>
<element name="objId" type="xs:int" fixed="20040"/>
</sequence>
</complexType>
LoggableEvent object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>8</type>
<reason>0</reason>
<parameters></parameters>
111
InputStreams 20160
For each stream entry that has its state changed from previous state, we send out a loggable event with appropriate
major, minor, type and reason.
<complexType name="InputStreams">
<sequence>
<element name="objGuid" type="xs:string"
fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/>
<element name="objId" type="xs:int" fixed="20160"/>
<element name="states" type="tns:InputStreamsEntries"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 31e41907-53be-4f57-8ae2a56c12d98d0e
objId
The event's unique database identifier. The value must be: 20160
entries
An InputStreamsEntries data type.
<pdDiagnostic>
<objId>20160</objId>
<context>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</context>
<entries>
<entry>
<id>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</id>
<mediaType>0</mediaType>
<hardwareId>1</hardwareId>
<channelId>1</channelId>
<stateCur>4</stateCur>
<statePrev>2</statePrev>
</entry>
</entries>
</pdDiagnostic>
InputStreamsEntries
A list of InputStreamsEntry data types.
<pdDiagnostic>
<objId>20160</objId>
<context>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</context>
<entries>
<entry>
<id>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</id>
<mediaType>0</mediaType>
<hardwareId>1</hardwareId>
<channelId>1</channelId>
<stateCur>4</stateCur>
<statePrev>2</statePrev>
</entry>
</entries>
</pdDiagnostic>
entry
An InputStreamsEntry data type.
InputStreamsEntry
<complexType name="InputStreamsEntry">
112
<sequence>
<element name="id" type="xs:string"/>
<element name="mediaType" type="xs:int"/>
<element name="hardwareId" type="xs:string"/>
<element name="stateCur" type="xs:int"/>
<element name="statePrev" type="xs:int"/>
</sequence>
</complexType>
id
The entry's unique identifier, for example: 2
mediaType
hardwareId
A hardware identifier, for example: hwidv1
stateCur
The current state identifier. Possible values are:
1 for ISS_RECORDING
Currently recieving a stream and it is being recorded.
2 for ISS_RECORD_ERROR
Currently receiving a stream, but it is unable to be recorded due to an error.
3 for ISS_RECEIVING
Currently recieving a stream.
4 for ISS_RECEIVE_ERROR
Unable to receive a stream.
5 for ISS_MISSING
Expecting a stream but there is no available stream. In analog inputs, this means the device is
unable to detect a connection.
6 for ISS_UNKNOWN
The state of the stream is currently unknown; this stream does not have an initial state registered.
NOTE: This will always be the final stream state.
statePrev
The previous state identifier. Refer to stateCur for possible valid values.
PacketLoss 20080
This event is fired when there is data loss during video data writing. Sets the appropriate major, minor, type, and
reason in Loggable Event.
PdDiagnostic
This is the data that subscribers will receive when the event triggers.
<complexType name="PacketLossPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string" fixed="ddfa09d6-64f1-4b39-a7e7de0c5f7780cc"/>
<element name="objId" type="xs:int" fixed="20080"/>
<element name="max" type="xs:float"/>
<element name="cur" type="xs:float"/>
</sequence>
</complexType>
objGuid
113
The event's Universally Unique Identifier. The value must be: ddfa09d6-64f1-4b39-a7e7de0c5f7780cc
objId
The event's unique database identifier. The value must be: 20080
max
The maximum acceptable packet loss percentage, for example: 1.1235
cur
The current packet loss percentage, for example: 5.1235
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>11</type>
<reason>0</reason>
<parameters>
<param>
<paramId>3</paramId>
<name>PercentageOfCurrentPacketLoss</name>
<value>5.1235</value>
<type>0</type>
</param>
</parameters>
SEBs 20210
For each PdDiagSebs object, loggable events are sent only when the state of a particular SEB changes. Set the state
of the SEB to the appropriate major, minor, type, and reason.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="SEBsPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/>
<element name="objId" type="xs:int" fixed="20210"/>
<element name="entries" type="tns:SEBSEntries"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: 31e41907-53be-4f57-8ae2a56c12d98d0e
objId
The event's unique database identifier. The value must be: 20210
entries
An SEBsEntries data type.
114
SEBsEntries
A list of SEBsEntry data types.
<complexType name="SEBsEntries">
<sequence>
<element name="entry" maxOccurs="unbounded" minOccurs="1"
type="tns:SEBsEntry"/>
</sequence>
</complexType>
entry
An SEBsEntry data type.
SEBsEntry
<complexType name="SEBsEntry">
<sequence>
<element name="stateCur" type="xs:int"/>
<element name="statePrev" type="xs:int"/>
</sequence>
<attribute name="id" type="xs:string" fixed="US"/>
</complexType>
stateCur
The current state identifier.
statePrev
The previous state identifier. Refer to stateCur for valid possible values.
id
(Attribute) The entry's identifier - string.
<pdDiagnostic>
<objGuid>2e9f0d2e-adf3-453b-aabc-a0223a604040</objGuid>
<objId>20210</objId>
<entries>
<entry id="hello0">
<stateCur>0</stateCur>
<statePrev>0</statePrev>
</entry>
<entry id="hello1">
<stateCur>0</stateCur>
<statePrev>0</statePrev>
</entry>
<entry id="hello2">
<stateCur>0</stateCur>
<statePrev>0</statePrev>
</entry>
<entry id="hello5"></entry>
</entries>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>9</type>
<reason>2</reason>
<parameters>
115
<param>
<paramId>7</paramId>
<name>SEBId</name>
<value>hello4</value>
<type>0</type>
</param>
</parameters>
StorageFull 20190
When this event triggers from a device with fully used storage, the appropriate major, minor, type, and reason is set in
the Loggable event.
PdDiagnostic
This is the data that subscribers receive when the event triggers.
<complexType name="StorageFullPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string" fixed="94b6d2d3c68e-4b13-974a-08f69f50cb67"/>
<element name="objId" type="xs:int" fixed="20190"/>
<element name="inAlarm" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: 94b6d2d3c68e-4b13-974a-08f69f50cb67
objId
The event's unique database identifier. The value must be: 20190
inAlarm
This represents whether or not a device is in a problem state. Possible values are:
0for storage is not full
Not in an alarm state.
1 for full storage
In an alarm state.
<pdDiagnostic>
<objGuid>3df223ee-8041-4c1a-be77-2d140e5588aa</objGuid>
<objId>20190</objId>
<inAlarm></inAlarm>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to DataLoss 20040 LoggableEvent above.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>13</type>
<reason>0</reason>
116
StorageTime 20130
This event is fired if the NVR/DVR is unable to achieve the user-configured video storage time.
PdDiagnostic
This is the data that subscribers will receive when the event triggers.
<complexType name="StorageTimePdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="e08fa1d1-9b30-4e62-bc8b-16cca0f57cb0"/>
<element name="objId" type="xs:int" fixed="20130"/>
<element name="min" type="xs:int"/>
<element name="cur" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: e08fa1d1-9b30-4e62bc8b-16cca0f57cb0
objId
The event's unique database identifier. The value must be: 20130
min
The minimum number of hours of storage time allowed.
cur
The current number of hours of storage time available.
<pdDiagnostic>
<objGuid>e08fa1d1-9b30-4e62-bc8b-16cca0f57cb0</objGuid>
<objId>20130</objId>
<min>5</min>
<cur>4</cur>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>12</type>
<reason>0</reason>
<parameters>
<param>
<paramId>8</paramId>
<name>CurrentStorageTime</name>
<value>4</value>
<type>1</type>
</param>
</parameters>
Temperature 20140
A Temperature PdDiagnostic object is triggered when temperature goes beyond specific range. The current
range is set between 10C - 50 Celsius. This verifies if the current temperature is below minimum or above maximum
117
threshold, and then determines whether to send Loggable Events, with reason set to either LOW or HIGH
accordingly.
PdDiagnostic
This is the data that subscribers will receive when the event triggers.
<complexType name="TemperaturePdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string"
fixed="26f051aa-009b-4a5d-ab20-09b064a07a52"/>
<element name="objId" type="xs:int" fixed="20140"/>
<element name="min" type="xs:int"/>
<element name="max" type="xs:int"/>
<element name="cur" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: 26f051aa-009b-4a5dab20-09b064a07a52
objId
The event's unique database identifier. The value must be: 20140
min
The minimum allowable temperature.
max
The maximum allowable temperature.
cur
The current temperature.
<pdDiagnostic>
<objGuid>7448f68a-de77-4ea9-b000-65b63bf54bd5</objGuid>
<objId>20140</objId>
<min>10</min>
<max>20</max>
<cur>5</cur>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>3</type>
<reason>0</reason>
<parameters>
<param>
<paramId>1</paramId>
<name>CurrentTemperature</name>
<value>5</value>
<type>1</type>
</param>
</parameters>
118
Appendix
G
Glossary
ActiveX
Active X is an integration platform that provides developers, users, and Web producers a fast and easy way to create
integrated programs and content for Microsoft based Internet and Intranet software. For more information, refer to
http://support.microsoft.com/kb/154544
Advertisement (UPnP)
In a UPnP network, advertisement is the act of one device presenting its services for another device to use. In Endura,
the UPnP advertisement startup and renew intervals are set from the System Configuration tab of the Setup window.
Alarm
In video security: An alarm occurs when a camera detects motion or there is a change in a physical alarm input, such
as a door opening or closing.
In card access: This is a condition caused by a system event or action to raise awareness to security staff.
Alarm relay
The alarm relay is the relay used to output an alarm condition based on a specific system or event message criteria.
Auto-focus
Auto-focus is the ability of the lens to remain in focus during zoom-in, zoom-out, and motion functions.
bit
Abbreviation for binary digit; the smallest unit of information a computer can use. A bit is either a 1 or a 0 (a high or low
voltage state).
bit rate
Bit rate is the number of bits that are transferred between devices in a specified amount of time, typically one second.
Brightness
In NTSC and PAL video signals, the brightness information at any particular instant in a picture is conveyed by the
corresponding instantaneous DC level of active video. Brightness control should be adjusted so that the black picture
content displays as true black on your monitor.
bps
Bits per second. This is a bit rate measurement.
Bps
Bytes per second. Also abbreviated as B/s.
Broadcast
In an IP network environment, broadcast refers to sending information from one device to every device on the network.
When broadcasting, it is not possible to control or specify which devices can receive this information.
byte
A byte is a string of bits processed as a unit by a digital computer. A byte is equal to eight bits (256 possibilities) and is
large enough to hold one character (like an A) or an unsigned integer from 0 to 255.
Camera group
In an Endura system, a camera group is a collection of cameras associated with each other as part of the setup
process. Camera groups may be used in filtering cameras displayed in the Nav window, as well as those selected for
schedules, scripts, or permissions.
Coaxitron
Coaxitron is the Pelco protocol that uses up the coax technology. Commands to control pan/tilt devices are
transmitted during the vertical blanking interval of the video signal. Instead of separate wiring for control commands
and video, Coaxitron uses the coaxial cable for both video and control.
Standard: This older technology uses 15 bits to send a command.
Extended: This newer technology uses 32 bits to send a command.
codec
119
C5617M-A | Glossary
Codec is an acronym for compression/decompression. This term is commonly used in the context of multimedia
compression and decompression, such as video or audio.
Common Intermediate Format (CIF)
A standard video and digital image size. Also refer to SIF.
CIF: 352 x 288 for PAL
2CIF: 704 x 288 for PAL
4CIF: 704 x 480 for PAL
QCIF: 176 x 144 for PAL
Compression
Compression is any algorithm used to reduce the size of a file.
Contrast
Contrast is a common term used in reference to the difference between the darkest and the brightest parts of an
image. Once brightness is set correctly, contrast should be set for comfortable viewing brightness.
D1
D1 is a digital video format developed by Society of Motion Picture and Television Engineers (SMPTE). The D1 format
resolution is 720 480 for NTSC and 720 576 for PAL.
Decoder
In an Endura system, the decoder is a high-performance video device that converts digital video streams back into
analog output for viewing on an analog video monitor, S-video monitor, or VGA monitor.
Decoding
Decoding is the opposite of encoding: decompressing a compressed digital image and then turning it back into an
analog signal.
Device
A device is a piece of hardware (camera, alarm, DVR, NVR, storage expansion box) that is part of a network.
Device ID
A device ID is a unique identifier for an individual device on a network.
Encoder
In an Endura system, the encoder is a high-performance MPEG-4 device that takes analog video signals through
a standard BNC coax and digitizes, compresses, signs, and packetizes them for the network. It also provides an
interface for relays, alarms, and audio connections.
Encoding
Encoding is the process of taking an analog signal and converting it to a digital format (A to D conversion).
Compression is applied at this point in the process.
Firmware
Firmware is a process or program that is embedded in a hardware platform that instructs the hardware unit how to
behave and what action to perform.
Focus
Focus means to adjust a lens to allow objects at various distances from the camera to be sharply defined.
Frame rate
The frame rate is the number of frames or images that are captured, stored, projected, or displayed per second.
Gamma
Gamma is the correction of the linear response of a camera to compensate for the nonlinear response of a monitors
phosphor screen. It is measured with the exponential value of the curve describing the nonlinearity. A typical
monochrome monitor gamma is 2.2, and a camera needs to be set to the inverse value of 2.2 (which is 0.45) for the
overall system to respond linearly (that is, unity).
H.264
Developed by the ITU-T Video Coding Experts Group (VCEG), H.264 is a low-bit-rate compressed video format
standard.
Hue
Hue is one of the characteristics that distinguishes one color from another. Hue defines color on the basis of its
position in the spectrum, that is, whether red, blue, green or yellow, etc. Hue is one of the three characteristics of
television color; the other two are saturation and luminance. In NTSC and PAL video signals, the hue information at
any particular point in the picture is conveyed by the corresponding instantaneous phase of the active video subcarrier.
I-frame
In a compressed digital image, I-frames (intraframes) are the frames that are compressed independently of the other
frames in the sequence.
IP
Internet Protocol. IP is the main method of transmitting data across the Internet.
IP address
120
C5617M-A | Glossary
(static and DHCP) The IP address identifies a particular computer on a network to other computers. An IP address
is similar to your home address. In a neighborhood, each house has a unique address; on a network each computer
must have a unique address. An IP address is a four-byte number, usually written in dotted-decimal notation with
periods separating the bytes (for example, 192.168.0.100). There are two types of IP addresses: static and DCHP.
A static address is assigned when someone physically connects to a computer and defines the IP address for
that computer. A static address does not change unless someone physically changes it. A DHCP (Dynamic Host
Configuration Protocol) address is assigned dynamically from a server that contains a pool of addresses. The server
leases the computer one of the available addresses for a specified amount of time. Once the time has expired, the
computer renews the lease or requests a new IP address.
IP camera
An IP camera is a digital video camera that outputs IP packets over Ethernet cabling. An IP camera may use TCP
protocol, as well as UDP or RTP.
IP header
An IP packet can be divided into two main parts: the payload and the header. The header is the part of the packet that
contains the routing information, and is is comprised of many parts. The header contains all IP and MAC addressing
information. The header is the only part of the packet that a router examines when trying to determine where to send a
packet.
Iris
The iris is a means of controlling the size of a lens aperture and therefore the amount of light passing through the lens.
marshalling
Marshalling is synonymous with serialization.
MPEG-4
Developed by Moving Picture Experts Group (MPEG), MPEG-4 expands the MPEG-1 specification to support AV
objects, 3D content, low bit-rate encoding, and Digital Right Management (DRM).
Multicast
A single device sends information across a network and that stream is received by all listening devices on the network.
A special IP address range has been reserved for this purpose: 224.0.0.1-239.255.255.255 with a sub-net mask
of 255.255.0.0. Each multicast transmitting device sends a data stream to an address from the above range. Any
device on the network can then listen for transmissions to that IP address and receive the stream. Multicast offers a
reduction of bandwidth consumption over the unicast and broadcast delivery methods. Multicast also offers control
over which devices on a network can receive a multicast stream. In an Endura system, only Endura devices can
receive Endura multicast streams. Multicast traffic is not routable across the Internet without a specially reserved
address or encapsulation.
Multicast server
A multicast server is any server that takes a unicast transmission on behalf of a client and converts it to a multicast
transmission on the network.
Namespace
Namespace is an identifier that denotes a group of names. It is used to prevent resource identifier conflicts.
Network Time Protocol (NTP)
NTP is a protocol designed to synchronize the clocks of computers over a network. On systems that have an NTP
server, you may use the WS5050 to configure the NTP settings (NTP server IP and renew interval). By default, time
and date information is included with video streams and other device data. The software relies on the PC system clock
for other needed time information.
National Television System Committee (NTSC)
NTSC developed the U.S. color TV specifications. It specifies 525 lines/screen. It also specifies 59.94 fields per
second, although most people refer to this frame rate as 30 frames per second. NTSC now describes the American
system of color telecasting. It is used in North America, Japan, and some parts of South America.
Network Storage Manager (NSM)
A combination of high performance, scalable hardware and advanced software for managing pooled storage of
recorded video and audio streams.
Phase Alternation by Line (PAL)
PAL is the European (50 Hz) color TV standard. It is used by most foreign countries around the world. It specifies 625
lines/screen, and 25 frames per second.
Parity
Parity is a method of checking the accuracy of data to identify whether the bits being moved arrived successfully.
Parity bit checking can be based on odd or even bits. No parity means that a parity bit is not transmitted or checked.
P-frame
In a compressed digital image, a P-frame (predicted frame) is a frame calculated based on the change from one frame
to the next. An area of the display that does not change from one frame to the next does not need to be contained in
the P-frame. If an area of the display does not change but does move on the screen, then only the vector describing
this movement is contained in the P-frame. This allows a reduction in overall file size.
PIN
121
C5617M-A | Glossary
122
C5617M-A | Glossary
123
C5617M-A | Glossary
124
Pelco by Schneider Electric 3500 Pelco Way Clovis, California 93612-5699 United States
USA & Canada Tel (800) 289-9100 Fax (800) 289-9150
International Tel +1 (559) 292-1981 Fax +1 (559) 348-1120