Pelco Developer Network (PDN)

Device Capability

Overview

This topic introduces the Device Capability API. The API will provide methods for a user to get service capabilities of the device, get resource availability, get available stream configuration, etc. This feature will help partners/integrators more easily integrate with Pelco products. For more information, please see the Device Capability web service reference.

Device Capability Service

The service will have the following namespace:

http://www.pelco.com/api/DeviceCapability/1

The service will be hosted at the following fixed URL on the device:

http://x.x.x.x/control/DeviceCapability-1

Assumptions

The following assumptions should be considered when using the service:

  1. There are only two streams available per encoder named primary and secondary
  2. You can configure streams separately, though a change to one might affect the other
  3. Each stream can be configured with different codec’s and different stream parameters, e.g. Primary stream to stream h.264 and secondary to be JPEG
  4. No matter how high the Primary stream is configured on the device, there are always resources available for the secondary stream.

Faults

The Service will use the fault.xsd schema (available as part of the Pelco API WSDLs zip file on the General Downloads page) . 

The service primarily uses 2 faults:

  1. ActionNotImplementedFault - This fault is thrown whenever a particular method could not be implemented due to some reason on a particular device. On Sarix all the methods listed below will be implemented.

  2. InvalidArgumentFault - This fault is thrown whenever the arguments supplied to a method are invalid. All the sub codes related to each method parameters are listed below.

Device Capabilities Use Cases

  1. An integrator wants to determine what services are available on the device to determine the capabilities of the device.
  2. An integrator wants to determine the URL at which the services are hosted, so that he can make calls on the service to execute supported functionality.
  3. An integrator wants to determine whether a service (e.g. Audio) is currently enabled on the device or not.
  4. An integrator wants to determine the hardware and software capabilities on the device. This will enable the integrator to enable/disable functionality on the head end depending on the capabilities supported. The integrator expects the following capabilities to be returned back:
    1. Number of alarms and relays supported on the device
    2. Number of Audio In and Audio Out supported on the device
    3. Number of directly accessible serial ports (not via USB) supported on the device
    4. PTZ support is available on the device
    5. What compression formats (H.264, MPEG4, MJPEG, JPEG) are available on the device
    6. Total number of primary and secondary streams that are available on the device and how many are currently in use.

GetServices

This operation retrieves of all the services supported by the device. The following parameters of each service are returned back

  • Namespace: The namespace of the service
  • URL: The URL at which the service is hosted
  • IsEnabled: Whether the service is current enabled on the device

This call satisfies Use Cases 1, 2 and 3.

 

GetServices

Fault codes

Description

ActionNotSupportedFault

env:Sender

 

The method is currently not supported on the device

 

GetDeviceCapability

This operation returns back the resources available on the device. The resources returned are as follows

  • Total number of physical video sources
  • Total number of Alarms
  • Total number of Relays
  • Total number of Audio In
  • Total number of Audio Out
  • PTZ Capability
  • Built in Pan/Tilt available on device
  • Built in Zoom available on device
  • Compression format available (H.264,MPEG4, MJPEG, JPEG)
  • Total number of directly accessible Serial ports
  • Available Streams
  •  Total and in use Primary/Secondary streams

This call satisfies Use Case 4.

 

GetDeviceCapability

Fault codes

Description

ActionNotSupportedFault

env:Sender

 

The method is currently not supported on the device

 

Stream Capabilities Use Cases

1.     An integrator would like to retrieve the best available settings for the primary stream. The integrator would like to keep the services that are currently enabled on the device to be enabled. Integrator would like to specify the format for the compression, however if its not specified the following would be the priority that the integrator would like to be use when determining the format

  • H.264
  • MPEG4
  • MJPEG
  • JPEG

The following is the feature priority that the integrator would like to be used when determining the best settings (best first)

  • Resolution
  • Framerate
  • Bitrate
  • Gop/GopStructure
  • Advance Sharpening
  • Endura Signing

The integrator is expecting that the best resolution is available. While determining the best capabilities for the primary stream, the secondary stream can be degraded (Assumption 4 applies).

2.     An integrator would like to retrieve the best available settings for the secondary stream. The integrator would like to keep the current primary stream setting intact and the services that are currently enabled on the device to be enabled. Integrator would like to specify the format for the compression, however if its not specified the following would be the priority that the integrator would like to be use when determining the format

  • H.264
  • MPEG4
  • MJPEG
  • JPEG

The following is the feature priority that the integrator would like to be used when determining the best settings (best first)

  • Resolution
  • Framerate
  • Bitrate
  • Gop/GopStructure
  • Endura Signing
  • Advance Sharpening

GetPrimaryStreamCapabilities

This operation returns the best capability for the primary stream based on currently enabled services on the device for a given compression format. If the compression format is not specified then the best available compression format will be selected. The following would be returned

  • Bitrate
  • Framerate
  • Gop
  • GopStructure
  • Dscp
  • Resolution(Height/Width)
  • Compression Format
  • Endura signing
  • Advance Sharpening
Dscp is not support for Jpeg. Due to the amount of resources used by Endura Signing and Advance Sharpening, these 2 setting will always be disabled by default, so that those resources can be used for settings higher in the priority.

This call satisfies Use Case 1.

 

GetPrimaryStreamCapabilities

Fault codes

Description

ActionNotSupportedFault

env:Sender

 

The method is currently not supported on the device

 

InvalidArgumentFault

env:Sender

  fault:InvalidCompressionFormat

The argument (compression format) supplied to the method is not valid. 

GetSecondaryStreamCapabilities

This operation returns the best capability for the secondary stream based on currently enabled services and primary stream configuration on the device for a given compression format. If compression format were not specified, the device would select the best available format. The following would be returned

  • Bitrate
  • Framerate
  • Gop
  • GopStructure
  • Dscp
  • Resolution (Height/Width)
  • Compression Format
  • Endura signing
Dscp is not support for Jpeg. Due to the amount of resources used by Endura Signing, that setting will always be disabled by default, so that those resources can be used for settings higher in the priority.

This call satisfies Use Case 2.

 

GetSecondaryStreamCapabilities

Fault codes

Description

ActionNotSupportedFault

env:Sender

 

The method is currently not supported on the device

 

InvalidArgumentFault

env:Sender

  fault:InvalidCompressionFormat

The argument (compression format) supplied to the method is not valid.

InvalidArgumentFault

env:Sender

  fault:IncompatibleConfiguration

The argument (compression format) supplied to the method is not compatible with existing stream format

Stream Configuration Use Cases

1.     An integrator wants to determine the current stream configuration on the device. This will enable the integrator to determine the primary and secondary stream configuration currently applied on the device.

2.     An integrator wants to enable services on the device that are currently disabled and wants to know what would be the best stream configuration to enable the services. The integrator expects that the services that are currently enabled will remain enabled.  The integrator expects that the configuration for primary stream is the best available and then a configuration for the secondary stream based on the resource availability (Assumption 4 applies). The following would be the priority that the integrator would like to be use when determining the format

  • H.264
  • MPEG4
  • MJPEG
  • JPEG

The following is the feature priority that the integrator would like to be used when determining the best settings (best first)

  • Resolution
  • Framerate
  • Bitrate
  • Gop/GopStructure
  • Endura Signing
  • Advance Sharpening

GetStreamConfigurations

This call returns the current stream configuration on the device. This call can be considered as a alternative to the GetAllCurrentConfiguration call in the StreamConfiguration API.

This call satisfies Use Case 1.

 

GetStreamConfigurations

Fault codes

Description

ActionNotSupportedFault

env:Sender

 

The method is currently not supported on the device

 

GetRecommendedStreamConfiguration

This call returns the available stream configuration for a given service or list of services. Currently enabled services will remain enabled if the returned stream configuration is applied to the device.

The services asked for could be motion, video, audio etc.

Due to the amount of resources used by Endura Signing and Advance Sharpening, these 2 setting will always be disabled by default, so that those resources can be used for settings higher in the priority.

This call satisfies Use Case 2.

 

GetRecommendedStreamConfiguration

Request-Response

Message name

Description

GetAvailableStreamCapabilitiesForServicesRequest

This message contains namespace of the services that stream capabilities needs to be retrieved.

GetAvailableStreamCapabilitiesForServicesResponse

This message contains the stream capabilities

Fault codes

Description

ActionNotSupportedFault

env:Sender

 

The method is currently not supported on the device

 

InvalidArgumentFault

env:Sender

  fault:InvalidServiceNamespace

The service namespace supplied to the method is not valid.